Proposal for an additional (sub)section in the porters handbook

[Alexander Leidinger]

Pav Lucistnik <pav at FreeBSD.org> wrote:

> I really think you should keep using "static" and "dynamic" in the
> "ambiguous" way, and perhaps define them in the text with a sentence or
> two each, to clear any confusion.  With your new terms, you're risking a
> confusion of all the longtimers.

Attached is a revised version. Native english speakers (or people which know
the english language better than me) are encouraged to highlight bugs...

Note: I'm only interested in the content of this new part of the porters
handbook. So if someone thinks he can come up with a better wording: feel
free to share it with us.

Bye,
Alexander.

-- 
http://www.Leidinger.net  Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org     netchild @ FreeBSD.org  : PGP ID = 72077137
You have only to mumble a few words in church to get married
and few words in your sleep to get divorced.

-------------- next part --------------
Dynamic vs. static plist
------------------------

Definition "static plist": a static plist is a plist which is available in the Ports Collection either as a pkg-plist file (with or without <ref "7.1 Changing pkg-plist based on make variables">plist variables</ref>), or embedded into the Makefile of the port as PLIST_FILES/PLIST_DIRS variables. The contents may be auto-generated by a tool or a target in the Makefile *before* the inclusion into the Ports Collection by a committer.

Definition "dynamic plist": a dynamic plist is a plist which is generated at the time the port is build/compiled based upon the files and directories which are installed and is not available in the Ports Collection before the source files of the port are downloaded and build or after a "make clean".


Some maintainers prefer to use dynamic plists. While the use of them is not forbidden, maintainers should use dynamic plists wherever possible, as it enables users to grep(1) through available plists to discover, for example, which port installs a certain file.
Exceptions are complex ports where the plist changes a lot based upon optional features of the port and getting the static plist right would result in a major headache, or ports which change the plist based upon the version of BUILD_DEPENDS used (e.g. ports which generate docs with Javadoc).

Maintainers which prefer dynamic plists are encouraged to add a new target to their port which generates the plist.



Some additional info for the commit log:
---snip---
Benefits of static plists:
 - Allows to search for files which are not installed. Affects users.
 - Allows to determine if a particular port contains what we want. Affects users.
 - Allows to check just with grep if two ports install conflicting files. Affects users (which debug a problem) and developers (which process a bug report).
 - Allows to check the plist for flaws/pitfalls with portlint. Affects developers.
 - Allows to answer some classes of support requests without the need to install the port. Affects "support frontliners".
 - Allows to notice files which are not build but should be build. Affects users (quality of the port/package) and developers (automatic bug notification by the ports build cluster).
 - Allows to have a look at the history of what a port installs. Affects users (which have a problem and need support with an old version of a port).

Drawback of static plists: an dynamic plist is generated when the port is installed while a static plists needs to be transfered to the user.

Counter argument to the drawback of static plists: while there are still some locations with limited connectivity where this may matter, the size of the rest of the ports tree combined with only transferring differences (if this results in smaller sizes) and compression (as done by cvsup and portsnap), the additional size of static plists is negligible.
---snip---