Re: Newbie question about additional documentation
On Tue, Nov 24, 2009 at 06:26:34AM +, Matthew Seaman wrote:
dave wrote:
On Mon, 2009-11-23 at 22:20 +, Matthew Seaman wrote:
Correct. In fact, it possibly means the LICENSE ends up in the plist
twice, which is almost as bad as it not being mentioned at all.
Ok, I think I'm starting to get a hang of this. Personally, I prefer the
static pkg-plist.
There's one last minor detail, though. The where's the final packing
list located? Is it in /var/db/pkg/${DISTNAME}?
While you're building the port, the packing list is assembled as
${WRKDIR}/PLIST where ${WRKDIR} is by default /usr/ports/foo/bar/work/
although it's not uncommon to locate it somewhere else by modifying
$WRKDIRPREFIX.
Once installed the PLIST is turned into /var/db/pkg/${DISTNAME}/+CONTENTS
which adds information about the ports this one depends on, plus the
md5 sumes of all of the installed files.
Just a small correction: it's /var/db/pkg/${PKGNAME}, not ${DISTNAME} :)
A slight difference, but important sometimes, most often when
PORTREVISION 0, but also when there are differences between
the representation of the version in the upstream distribution and in
the FreeBSD port.
G'luck,
Peter
--
Peter Pentchev r...@ringlet.netr...@space.bgr...@freebsd.org
PGP key:http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint 2EE7 A7A5 17FC 124C F115 C354 651E EFB0 2527 DF13
I am not the subject of this sentence.
pgpzPCW1hlGij.pgp
Description: PGP signature
Re: Newbie question about additional documentation
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.. %%PORTDOCSDOCSDIR%%/LICENSE %%portdoc...@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 %%PORTDOCSDOCSDIR%%/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 -- Dr Matthew J Seaman MA, D.Phil. Flat 3 7 Priory Courtyard PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate Kent, CT11 9PW, UK signature.asc Description: OpenPGP digital signature
Re: Newbie question about additional documentation
On Mon, 2009-11-23 at 12:21 +, 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.. %%PORTDOCSDOCSDIR%%/LICENSE %%portdoc...@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 %%PORTDOCSDOCSDIR%%/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 %%PORTDOCSDOCSDIR%%/LICENSE in pkg-plist would be redundant, wouldn't it? ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Newbie question about additional documentation
On Mon, Nov 23, 2009 at 09:23:18PM +0100, dave wrote: On Mon, 2009-11-23 at 12:21 +, 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.. %%PORTDOCSDOCSDIR%%/LICENSE %%portdoc...@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 %%PORTDOCSDOCSDIR%%/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: [snip] 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 %%PORTDOCSDOCSDIR%%/LICENSE in pkg-plist would be redundant, wouldn't it? Seems to be so... There is one bad thing about PORTDOCS method: you don't have static list of files the port is going to install. Some commiters here don't like it. This is of course up to you but if it is not hard it is better to manually list all of the installed files in static pkg-plist. Just 0.02$, Alexey. ___ freebsd-ports@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-ports To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
Re: Newbie question about additional documentation
dave wrote: 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 %%PORTDOCSDOCSDIR%%/LICENSE in pkg-plist would be redundant, wouldn't it? Correct. In fact, it possibly means the LICENSE ends up in the plist twice, which is almost as bad as it not being mentioned at all. Cheers, Matthew -- Dr Matthew J Seaman MA, D.Phil. 7 Priory Courtyard Flat 3 PGP: http://www.infracaninophile.co.uk/pgpkey Ramsgate Kent, CT11 9PW signature.asc Description: OpenPGP digital signature
Re: Newbie question about additional documentation
On Tue, 24 Nov 2009, dave wrote:
On Mon, 2009-11-23 at 22:20 +, Matthew Seaman wrote:
Correct. In fact, it possibly means the LICENSE ends up in the plist
twice, which is almost as bad as it not being mentioned at all.
Ok, I think I'm starting to get a hang of this. Personally, I prefer the
static pkg-plist.
There's one last minor detail, though. The where's the final packing
list located? Is it in /var/db/pkg/${DISTNAME}?
+CONTENTS within that directory.
--
Sahil Tandon sa...@tandon.net
___
freebsd-ports@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-ports
To unsubscribe, send any mail to freebsd-ports-unsubscr...@freebsd.org
