From owner-freebsd-ports@FreeBSD.ORG Mon Nov 23 20:23:25 2009 Return-Path: Delivered-To: freebsd-ports@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id F305A106568B for ; Mon, 23 Nov 2009 20:23:24 +0000 (UTC) (envelope-from djf@gmx.ch) Received: from mail.gmx.net (mail.gmx.net [213.165.64.20]) by mx1.freebsd.org (Postfix) with SMTP id 4C1638FC0C for ; Mon, 23 Nov 2009 20:23:24 +0000 (UTC) Received: (qmail invoked by alias); 23 Nov 2009 20:23:21 -0000 Received: from adsl-89-217-54-219.adslplus.ch (EHLO [192.168.1.5]) [89.217.54.219] by mail.gmx.net (mp009) with SMTP; 23 Nov 2009 21:23:21 +0100 X-Authenticated: #2052246 X-Provags-ID: V01U2FsdGVkX19CSB16LCdCDBKiUHI9rBR/ADHSfX3zoKf1jaajju 6AcuqbJuERr0ly From: dave To: Matthew Seaman In-Reply-To: <4B0A7E3E.4020500@infracaninophile.co.uk> References: <20091123112929.151170@gmx.net> <4B0A7E3E.4020500@infracaninophile.co.uk> Content-Type: text/plain Date: Mon, 23 Nov 2009 21:23:18 +0100 Message-Id: <1259007798.1283.68.camel@localhost> Mime-Version: 1.0 X-Mailer: Evolution 2.26.3 FreeBSD GNOME Team Port Content-Transfer-Encoding: 7bit X-Y-GMX-Trusted: 0 X-FuHaFi: 0.55 Cc: freebsd-ports@freebsd.org Subject: Re: Newbie question about additional documentation X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: djf@gmx.ch List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 23 Nov 2009 20:23:25 -0000 On Mon, 2009-11-23 at 12:21 +0000, Matthew Seaman wrote: > 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%%%%DOCSDIR%%/LICENSE > > %%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/bsd.port.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 > beforehand. > > Cheers, > > Matthew Thanks for the hints. In section 5.14.4 of Porter's Handbook it says: "As an alternative to enumerating the documentation files in pkg-plist, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. If NOPORTDOCS is defined then files and directories listed in PORTDOCS would not be installed and neither would be added to port packing list" After looking at the Makefile again, I noticed that the maintainer of hs-zlib defined PORTDOCS= * . If I understand correctly, that means you can put as many files in DOCSDIR as you want. The asterisk will match everything and you always end up with everything registered in the final packing list. Right? If so, the line %%PORTDOCS%%%%DOCSDIR%%/LICENSE in pkg-plist would be redundant, wouldn't it?