Newbie question about additional documentation

Matthew Seaman m.seaman at
Mon Nov 23 12:21:37 UTC 2009

David Fries wrote:
> Hi everybody
> I started working on my first port (a Haskell cabal package) over the
> last weekend. I read the porter's handbook and then began by looking
> at similar ports that already existed in the ports collection (e.g.
> archivers/hs-zlib) to get a basic idea of what the port should look
> like. I noticed that the only documentation listed in pkg-plist of
> these ports is the LICENSE file. So pkg-plist looks something like
> this:
> ... other files..
> %%PORTDOCS%%@dirrm %%DOCSDIR%%
> ... @exec/@unexec...
> However, when you install the port (assuming NOPORTDOCS is not set),
> a HTML documentation will also be generated by the Haskell compiler
> and put into %%PORTDOCS%%%%DOCSDIR%%/html/*. So my question is, is it
> ok to omit these html files in the pkg-plist? I thought, you should
> list those too...

It's not OK to install files without any record in the pkgdb.  If you do
things like that, firstly any committer working on the port should bounce
it back to you as not fulfilling the required standards, and secondly, if
the port does somehow get committed you'll be getting irate e-mails from
various QA systems that spend all their time looking for such problems.

Now, explicitly listing all of the files that get installed in pkg-plist
in the port directory is one way of dealing with this.  There are alternatives
though, which might suit your port better.  Check out the PLIST_FILES and
PORTDOCS variables in /usr/ports/Mk/ -- in short these are:

   PLIST_FILES a way of listing a short pkg_plist entirely from within
               the port Makefile, which helps avoid using up inodes for
               tiny little files

   PORTDOCS a way of automatically adding a whole directory tree of
            documentation to the pkg pretty much automatically. This is
            particularly useful if your docco is generated automatically
            and you can't always know exactly what files there will be



Dr Matthew J Seaman MA, D.Phil.                       Flat 3
                                                      7 Priory Courtyard
PGP:         Ramsgate
                                                      Kent, CT11 9PW, UK

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 259 bytes
Desc: OpenPGP digital signature
Url :

More information about the freebsd-ports mailing list