Date: Thu, 25 Feb 2021 19:46:16 +0000 From: Norman Gray <norman.gray@glasgow.ac.uk> To: FreeBSD Mailing List <freebsd-questions@freebsd.org> Subject: Package manifest documentation Message-ID: <036EF329-A35D-42F1-A1B8-2D8B4D8DA90D@glasgow.ac.uk>
next in thread | raw e-mail | index | archive | help
Greetings.
Is there any comprehensive documentation of the format of pkg manifest =
files?
Answer: yes, there does appear to be (see at end), but it's much harder =
to find than I think it should be. Re which, read on.
The pkg-create(8) manpage mentions some relevant keywords for the file, =
but doesn't say anything about the syntax.
It illustrates the 'desc' keyword with a here-string after an '=3D' sign,=
=
but illustrates 'deps' with some JSON-like syntax, complete with quotes =
around keywords.
I see issue [1] from 2015, which is asking the same question. I could I =
suppose add a +1 to this issue.
Dumping a package manifest with `pkg info -R` I see something I can =
probably imitate, but there are plenty of keywords in there that aren't =
mentioned in pkg-create. Are these documenting the same file?
Issues such as [2] mention a UCL syntax in passing, but libucl(3) =
mentions only a library for parsing this syntax, not what the syntax is. =
'UCL' isn't mentioned in pkg-create(8) at all.
Templates elsewhere online (eg [3]) illustrate a 'key: value' syntax, =
which _appears_, from the dumped manifest, to be current.
Also, has the syntax changed? I have a manifest file which I wrote =
myself some while ago (11.x, I think?), which has a files { hash =
filename ... } entry, which doesn't work with 12.x, and I now see only a =
'file' key mentioned in pkg-create(8). Looking at a dumped manifest, it =
appears that this should now be files: { file: hash,...}.
The Handbook doesn't mention package creation at all, nor does the =
Developers' Handbook.
In the Porter's Handbook [4] I do see a link to UCL [5] (hooray!), but =
that seems to document four _different_ syntaxes, which is interesting =
but not particularly helpful (since it's three more than I want to learn =
about right now). This handbook somewhat surprisingly doesn't seem to =
mention pkg-create at all, but does mention pkg-plist (Sect.3.2.2), =
which pkg-create describes as 'legacy'.
I'm getting a picture as follows:
* the manifest is in a 'UCL' syntax, which is documented only on =
github
* since this has multiple syntaxes (presumably I can use any of the =
UCL syntaxes in here?), the pkg-create(8) manpage only documents key =
names
* there are more manifest keywords available than are mentioned in =
pkg-create(8)
* the syntax for pkg-create manifests has changed significantly in =
recent releases
Is that right?
I also see a FreeBSD bug [6] mentioning the file/files thing I mentioned =
above. At _this_ point, pointed to from the bugparade, I find =
<https://wiki.freebsd.org/pkgng>, which is about 'pkg', not 'pkgng', and =
which points to the Github page at <https://github.com/freebsd/pkg>; as =
the source, which does include an example.
A suggestion: It would be *ahem* really useful if the manpage could lead =
me to this information by a slightly more direct route. It would =
probably be more efficient, in fact, if the sections on 'manifest file =
details' and 'plist format' were simply deleted from the manpage, and =
replaced by a pointer to GitHub.
Best wishes,
Norman
[1] https://github.com/freebsd/pkg/issues/1331
[2] https://github.com/freebsd/pkg/issues/1933
[3] =
https://github.com/dwcarder/oneoff-pkg-create/blob/master/manifest_templa=
te.example
[4] https://docs.freebsd.org/en/books/porters-handbook/#pkg-files
[5] https://github.com/vstakhov/libucl
[6] https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D250834
-- =
Norman Gray : http://www.astro.gla.ac.uk/users/norman/it/
Research IT Coordinator
SUPA School of Physics and Astronomy, University of Glasgow, UK
Charity number SC004401
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?036EF329-A35D-42F1-A1B8-2D8B4D8DA90D>