Package manifest documentation

[Norman Gray]

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 '=' 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_template.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=250834


-- 
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