Index: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml @@ -19,45 +19,47 @@ need to change their pkg-plist depending on what options they are configured with (or version of perl, in the case of p5- - ports). To make this easy, any instances in the + ports). To make this easy, any instances in pkg-plist of %%OSREL%%, %%PERL_VER%%, and - %%PERL_VERSION%% will be substituted for + %%PERL_VERSION%% will be substituted appropriately. The value of %%OSREL%% is the - numeric revision of the operating system (e.g., + numeric revision of the operating system (for example, 4.9). %%PERL_VERSION%% and %%PERL_VER%% is the full version number - of perl (e.g., 5.8.9). + of perl (for example, 5.8.9). Several other %%VARS%% related to port's documentation files are described in the relevant section. - If you need to make other substitutions, you can set the - PLIST_SUB variable with a list of + To make other substitutions, set + PLIST_SUB with a list of VAR=VALUE pairs and instances of %%VAR%% will be - substituted with VALUE in the + substituted with VALUE in pkg-plist. - For instance, if you have a port that installs many files - in a version-specific subdirectory, you can put something - like + For instance, if a port installs many files + in a version-specific subdirectory, use a placeholder for the + version so that pkg-plist does not have to + be regenerated every time the port is updated. For + example: - OCTAVE_VERSION= 2.0.13 + OCTAVE_VERSION= ${PORTREVISION} PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} in the Makefile and use %%OCTAVE_VERSION%% wherever the version shows - up in pkg-plist. That way, when you - upgrade the port, you will not have to change dozens (or in some - cases, hundreds) of lines in the + up in pkg-plist. When + the port is upgraded, it will not be necessary to edit dozens (or in some + cases, hundreds) of lines in pkg-plist. - If your port installs files conditionally on the options - set in the port, the usual way of handling it is prefixing the + If files are installed conditionally on the options + set in the port, the usual way of handling it is prefixing pkg-plist lines with a %%OPT%% for lines needed when the option is enabled, or %%NO_OPT%% when the option is @@ -66,13 +68,13 @@ linkend="options_sub"/> for more information. For instance, if there are files that are only installed - when the X11 option is enabled, and the + when the X11 option is enabled, and Makefile has: OPTIONS_DEFINE= X11 OPTIONS_SUB= yes - In the pkg-plist file, put + In pkg-plist, put %%X11%% in front of the lines only being installed when the option is enabled, like this : @@ -83,9 +85,9 @@ do-install targets, by reading from PLIST and writing to TMPPLIST (default: - WRKDIR/.PLIST.mktmp). So if your port + WRKDIR/.PLIST.mktmp). So if the port builds PLIST on the fly, do so in or before - pre-install. Also, if your port + pre-install. Also, if the port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. @@ -108,13 +110,13 @@ PLIST_DIRSTRY, respectively. To take effect, PLIST_FILES, PLIST_DIRS, and PLIST_DIRSTRY must be set before - TMPPLIST is written, i.e., in + TMPPLIST is written, that is, in pre-install or earlier. - From time to time, the OPTIONS_SUB - construct is not enough, in those cases, adding a specific - TAG to the PLIST_SUB - variable inside the Makefile with a special + From time to time, using OPTIONS_SUB + is not enough. In those cases, adding a specific + TAG to PLIST_SUB + inside the Makefile with a special value of @comment, makes package tools to ignore the line. For instance, if some files are only installed when the X11 option is on and the @@ -139,8 +141,8 @@ When being de-installed, A port has to remove empty directories it created. This is usually accomplished by adding @dirrm lines for all directories - that are specifically created by the port. You need to delete - subdirectories before you can delete parent + that are specifically created by the port. Subdirectories + must be deleted before deleting parent directories. : @@ -152,8 +154,8 @@ @dirrm lib/X11/oneko However, sometimes @dirrm will give - you errors because other ports share the same directory. You - can use @dirrmtry to remove only empty + errors because other ports share the same directory. + Use @dirrmtry to remove only empty directories without warning. @dirrmtry share/doc/gimp @@ -169,33 +171,38 @@ Creating Empty Directories Empty directories created during port installation need - special attention. They will not get created when installing - the package, because packages only store the files, and both - pkg add and pkg install - creates directories for them as needed. To make sure the - empty directory is created when installing the package, add - this line to pkg-plist above the - corresponding @dirrm line: + special attention. They must be present when the package + is created. If they are not created by the port code, create + them in the Makefile: + + post-stage: + @${MKDIR} ${STAGEDIR}${PREFIX}/some/directory + + Add the directory to pkg-plist + like any other. For example, if the directory has files + created when the port is used: - @exec mkdir -p %D/share/foo/templates + @dirrmtry some/directory Configuration Files - If your port installs configuration files to + If the port installs configuration files to PREFIX/etc (or elsewhere) do - not simply list them in the + not list them in pkg-plist. That will cause - pkg delete to remove the files carefully + pkg delete to remove files that have been carefully edited by the user, and a re-installation will wipe them out. - Instead, install sample file(s) as - filename.sample, - and for each sample file, add this line to your - pkg-plist. + Instead, install sample files with a + filename.sample + extension. The @sample macro automates this, + see for what it does + exactly. For each sample file, add a line to + pkg-plist: @sample etc/orbit.conf.sample @@ -209,19 +216,19 @@ When a port installs its configuration in a subdirectory - of ${PREFIX}/etc, it should be in + of ${PREFIX}/etc, use ETCDIR, which defaults to ${PREFIX}/etc/${PORTNAME}, it can be overridden in the ports Makefile if there is a convention for the port to use some other directory. The - %%ETCDIR%% macro should be used in its - stead in the pkg-plist file. + %%ETCDIR%% macro will be used in its + stead in pkg-plist. The sample configuration files should always have the .sample suffix. If for some historical - reason you cannot use the standard suffix, you can still use + reason using the standard suffix is not possible, use this construct: @unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi @@ -253,15 +260,15 @@ Dynamic Versus Static Package List A static package list is a package - list which is available in the Ports Collection either as a - pkg-plist file (with or without variable + list which is available in the Ports Collection either as + pkg-plist (with or without variable substitution), or embedded into the Makefile via PLIST_FILES, PLIST_DIRS, and PLIST_DIRSTRY. Even if the contents are auto-generated by a tool or a target in the Makefile before the inclusion into the Ports - Collection by a committer (e.g., using make + Collection by a committer (for example, using make makeplist>), this is still considered a static list, since it is possible to examine it without having to download or compile the distfile. @@ -281,8 +288,8 @@ the package list changes drastically based upon optional features of the port (and thus maintaining a static package list is infeasible), or ports which change the package list based - upon the version of dependent software used (e.g., ports which - generate docs with Javadoc). + upon the version of dependent software used. For example, ports which + generate docs with Javadoc. @@ -290,7 +297,7 @@ First, make sure the port is almost complete, with only pkg-plist missing. Running make - makeplist will show what should be put in + makeplist will show an example for pkg-plist. The output of makeplist must be double checked for correctness as it tries to automatically guess a few things, and @@ -298,12 +305,12 @@ User configuration files should be installed as filename.sample, - as it is described in . The - info/dir file should not be listed and - appropriate install-info lines should be + as it is described in . + info/dir must not be listed and + appropriate install-info lines must be added as noted in the info files section. Any libraries installed by the port - should be listed as specified in the shared libraries section. @@ -412,9 +419,9 @@ command Execute command as part of - the unpacking process. If command contains any of the - following sequences somewhere in it, they are expanded - inline. For the following examples, assume that + the unpacking process. If command contains any of these + sequences somewhere in it, they are expanded + inline. For these examples, assume that @cwd is set to /usr/local and the last extracted file was bin/emacs. @@ -527,7 +534,7 @@ By default, directories created by a package installation are not deleted when the package is deinstalled. This provides an explicit directory cleanup method. These - directives should appear at the end of the package list. If + directives must appear at the end of the package list. If the directory is not empty a warning is printed, and the directory is not removed. @@ -542,8 +549,8 @@ - - Creating Your Own Keyword + + Creating New Keywords Package list files can be extended by keywords that are defined in the YAML file named keyword.yaml. - The file must contain at least one of the following + The file must contain at least one of the next sections: @@ -713,13 +720,19 @@ actions: [file] post-install: | - sample_file="%D/%@" + case "%@" in + /*) sample_file="%@" ;; + *) sample_file="%D/%@" ;; + esac target_file="${sample_file%.sample}" if ! [ -f "${target_file}" ]; then /bin/cp -p "${sample_file}" "${target_file}" fi pre-deinstall: | - sample_file="%D/%@" + case "%@" in + /*) sample_file="%@" ;; + *) sample_file="%D/%@" ;; + esac target_file="${sample_file%.sample}" if cmp -s "${target_file}" "${sample_file}"; then rm -f "${target_file}"