diff options
| author | jmmv <jmmv@pkgsrc.org> | 2005-06-03 12:28:56 +0000 |
|---|---|---|
| committer | jmmv <jmmv@pkgsrc.org> | 2005-06-03 12:28:56 +0000 |
| commit | 5e33fbd01dd566a726f9c72a7b64e16e13ed2f4e (patch) | |
| tree | e418c8ffaef38fd634e03b6fc0e541a0309e4e04 | |
| parent | 6e1112e58ced7fb6356ad64c1d8432b0e8e450d0 (diff) | |
| download | pkgsrc-5e33fbd01dd566a726f9c72a7b64e16e13ed2f4e.tar.gz | |
Regenerate after addition of the pkginstall chapter.
| -rw-r--r-- | doc/pkgsrc.html | 1729 | ||||
| -rw-r--r-- | doc/pkgsrc.txt | 973 |
2 files changed, 1751 insertions, 951 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index 9e38278048a..ae22d0a8d04 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -350,8 +350,8 @@ alink="#0000FF"> pkgsrc</a></span></dt> <dt><span class="sect1"><a href="#faq.conf">6.14. - Configuration files handling and - placement</a></span></dt> + How do I change the location of configuration + files?</a></span></dt> <dt><span class="sect1"><a href= "#audit-packages">6.15. Automated security @@ -540,261 +540,326 @@ alink="#0000FF"> </dl> </dd> - <dt><span class="chapter"><a href="#options">11. + <dt><span class="chapter"><a href="#pkginstall">11. The + pkginstall framework</a></span></dt> + + <dd> + <dl> + <dt><span class="sect1"><a href= + "#files-and-dirs-outside-prefix">11.1. Files and + directories outside the installation + prefix</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#dirs-outside-prefix">11.1.1. Directory + manipulation</a></span></dt> + + <dt><span class="sect2"><a href= + "#files-outside-prefix">11.1.2. File + manipulation</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href="#conf-files">11.2. + Configuration files</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#conf-files-sysconfdir">11.2.1. How + <code class="varname">PKG_SYSCONFDIR</code> is + set</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-configure">11.2.2. Telling the + software were configuration files + are</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-patching">11.2.3. Patching + installations</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-disable">11.2.4. Disabling + handling of configuration files</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href= + "#rcd-scripts">11.3. System startup + scripts</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#rcd-scripts-disable">11.3.1. Disabling + handling of system startup + scripts</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href= + "#users-and-groups">11.4. System users and + groups</a></span></dt> + + <dt><span class="sect1"><a href="#shells">11.5. + System shells</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#shells-disable">11.5.1. Disabling handling of + configuration files</a></span></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><span class="chapter"><a href="#options">12. Options handling</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#global-default-options">11.1. Global default + "#global-default-options">12.1. Global default options</a></span></dt> <dt><span class="sect1"><a href= - "#converting-to-options">11.2. Converting packages + "#converting-to-options">12.2. Converting packages to use <code class= "filename">bsd.options.mk</code></a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#build">12. The + <dt><span class="chapter"><a href="#build">13. The build process</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#build.prefix">12.1. Program + "#build.prefix">13.1. Program location</a></span></dt> <dt><span class="sect1"><a href= - "#main-targets">12.2. Main targets</a></span></dt> + "#main-targets">13.2. Main targets</a></span></dt> <dt><span class="sect1"><a href= - "#build.helpful-targets">12.3. Other helpful + "#build.helpful-targets">13.3. Other helpful targets</a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#fixes">13. Notes on + <dt><span class="chapter"><a href="#fixes">14. Notes on fixes for packages</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#general-operation">13.1. General + "#general-operation">14.1. General operation</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#pulling-vars-from-etc-mk.conf">13.1.1. How to + "#pulling-vars-from-etc-mk.conf">14.1.1. How to pull in variables from /etc/mk.conf</a></span></dt> <dt><span class="sect2"><a href= - "#where-to-install-documentation">13.1.2. Where + "#where-to-install-documentation">14.1.2. Where to install documentation</a></span></dt> <dt><span class="sect2"><a href= - "#restricted-packages">13.1.3. Restricted + "#restricted-packages">14.1.3. Restricted packages</a></span></dt> <dt><span class="sect2"><a href= - "#dependencies">13.1.4. Handling + "#dependencies">14.1.4. Handling dependencies</a></span></dt> <dt><span class="sect2"><a href= - "#conflicts">13.1.5. Handling conflicts with + "#conflicts">14.1.5. Handling conflicts with other packages</a></span></dt> <dt><span class="sect2"><a href= - "#not-building-packages">13.1.6. Packages that + "#not-building-packages">14.1.6. Packages that cannot or should not be built</a></span></dt> <dt><span class="sect2"><a href= - "#undeletable-packages">13.1.7. Packages which + "#undeletable-packages">14.1.7. Packages which should not be deleted, once installed</a></span></dt> <dt><span class="sect2"><a href= - "#security-handling">13.1.8. Handling packages + "#security-handling">14.1.8. Handling packages with security problems</a></span></dt> <dt><span class="sect2"><a href= - "#compiler-bugs">13.1.9. How to handle compiler + "#compiler-bugs">14.1.9. How to handle compiler bugs</a></span></dt> <dt><span class="sect2"><a href= - "#bumping-pkgrevision">13.1.10. How to handle + "#bumping-pkgrevision">14.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt> <dt><span class="sect2"><a href= - "#portability-of-packages">13.1.11. Portability + "#portability-of-packages">14.1.11. Portability of packages</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#downloading-issues">13.2. Possible downloading + "#downloading-issues">14.2. Possible downloading issues</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#no-plain-download">13.2.1. Packages whose + "#no-plain-download">14.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt> <dt><span class="sect2"><a href= - "#modified-distfiles-same-name">13.2.2. How to + "#modified-distfiles-same-name">14.2.2. How to handle modified distfiles with the 'old' name</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#configuration-gotchas">13.3. Configuration + "#configuration-gotchas">14.3. Configuration gotchas</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#fixes.libtool">13.3.1. Shared libraries - + "#fixes.libtool">14.3.1. Shared libraries - libtool</a></span></dt> <dt><span class="sect2"><a href= - "#using-libtool">13.3.2. Using libtool on GNU + "#using-libtool">14.3.2. Using libtool on GNU packages that already support libtool</a></span></dt> <dt><span class="sect2"><a href= - "#autoconf-automake">13.3.3. GNU + "#autoconf-automake">14.3.3. GNU Autoconf/Automake</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#building-considerations">13.4. Building + "#building-considerations">14.4. Building considerations</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#cpp-defines">13.4.1. CPP + "#cpp-defines">14.4.1. CPP defines</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#package-specific-actions">13.5. Package specific + "#package-specific-actions">14.5. Package specific actions</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#package-configuration-files">13.5.1. Package - configuration files</a></span></dt> - - <dt><span class="sect2"><a href= - "#user-interaction">13.5.2. User + "#user-interaction">14.5.1. User interaction</a></span></dt> <dt><span class="sect2"><a href= - "#handling-licenses">13.5.3. Handling + "#handling-licenses">14.5.2. Handling licenses</a></span></dt> <dt><span class="sect2"><a href= - "#creating-accounts">13.5.4. Creating an - account from a package</a></span></dt> - - <dt><span class="sect2"><a href= - "#installing-score-files">13.5.5. Installing + "#installing-score-files">14.5.3. Installing score files</a></span></dt> <dt><span class="sect2"><a href= - "#login-shells">13.5.6. Packages providing - login shells</a></span></dt> - - <dt><span class="sect2"><a href= - "#perl-scripts">13.5.7. Packages containing + "#perl-scripts">14.5.4. Packages containing perl scripts</a></span></dt> <dt><span class="sect2"><a href= - "#hardcoded-paths">13.5.8. Packages with + "#hardcoded-paths">14.5.5. Packages with hardcoded paths to other interpreters</a></span></dt> <dt><span class="sect2"><a href= - "#perl-modules">13.5.9. Packages installing + "#perl-modules">14.5.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href= - "#faq.info-files">13.5.10. Packages installing + "#faq.info-files">14.5.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href= - "#gconf2-data-files">13.5.11. Packages + "#gconf2-data-files">14.5.8. Packages installing GConf2 data files</a></span></dt> <dt><span class="sect2"><a href= - "#scrollkeeper-data-files">13.5.12. Packages + "#scrollkeeper-data-files">14.5.9. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href= - "#x11-fonts">13.5.13. Packages installing X11 + "#x11-fonts">14.5.10. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href= - "#gtk2-modules">13.5.14. Packages installing + "#gtk2-modules">14.5.11. Packages installing GTK2 modules</a></span></dt> <dt><span class="sect2"><a href= - "#sgml-xml-data">13.5.15. Packages installing + "#sgml-xml-data">14.5.12. Packages installing SGML or XML data</a></span></dt> <dt><span class="sect2"><a href= - "#mime-database">13.5.16. Packages installing + "#mime-database">14.5.13. Packages installing extensions to the MIME database</a></span></dt> <dt><span class="sect2"><a href= - "#intltool">13.5.17. Packages using + "#intltool">14.5.14. Packages using intltool</a></span></dt> <dt><span class="sect2"><a href= - "#startup-scripts">13.5.18. Packages installing + "#startup-scripts">14.5.15. Packages installing startup scripts</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#feedback-to-author">13.6. Feedback to the + "#feedback-to-author">14.6. Feedback to the author</a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#debug">14. + <dt><span class="chapter"><a href="#debug">15. Debugging</a></span></dt> - <dt><span class="chapter"><a href="#submit">15. + <dt><span class="chapter"><a href="#submit">16. Submitting and Committing</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#submitting-your-package">15.1. Submitting your + "#submitting-your-package">16.1. Submitting your packages</a></span></dt> <dt><span class="sect1"><a href= - "#committing-importing">15.2. Committing: Importing + "#committing-importing">16.2. Committing: Importing a package into CVS</a></span></dt> <dt><span class="sect1"><a href= - "#updating-package">15.3. Updating a package to a + "#updating-package">16.3. Updating a package to a newer version</a></span></dt> <dt><span class="sect1"><a href= - "#moving-package">15.4. Moving a package in + "#moving-package">16.4. Moving a package in pkgsrc</a></span></dt> </dl> </dd> @@ -1437,9 +1502,9 @@ alink="#0000FF"> "#using-sudo-with-pkgsrc">6.13. Using 'sudo' with pkgsrc</a></span></dt> - <dt><span class="sect1"><a href="#faq.conf">6.14. - Configuration files handling and - placement</a></span></dt> + <dt><span class="sect1"><a href="#faq.conf">6.14. How + do I change the location of configuration + files?</a></span></dt> <dt><span class="sect1"><a href= "#audit-packages">6.15. Automated security @@ -3124,8 +3189,8 @@ CFLAGS= -xtarget=ultra -xarch=v9 class="pkgname">misc/figlet</a> example.</p> <p>See <a href="#submit" title= - "Chapter 15. Submitting and Committing">Chapter - 15, <i>Submitting and Committing</i></a> for information + "Chapter 16. Submitting and Committing">Chapter + 16, <i>Submitting and Committing</i></a> for information on how to submit such a binary package.</p> </div> @@ -3142,7 +3207,7 @@ CFLAGS= -xtarget=ultra -xarch=v9 </div> <p>See <a href="#build.helpful-targets" title= - "12.3. Other helpful targets">Section 12.3, + "13.3. Other helpful targets">Section 13.3, “Other helpful targets”</a>.</p> </div> @@ -4008,9 +4073,9 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> "#using-sudo-with-pkgsrc">6.13. Using 'sudo' with pkgsrc</a></span></dt> - <dt><span class="sect1"><a href="#faq.conf">6.14. - Configuration files handling and - placement</a></span></dt> + <dt><span class="sect1"><a href="#faq.conf">6.14. How + do I change the location of configuration + files?</a></span></dt> <dt><span class="sect1"><a href="#audit-packages">6.15. Automated security checks</a></span></dt> @@ -4718,135 +4783,38 @@ SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c <div> <div> <h2 class="title" style="clear: both"><a name= - "faq.conf" id= - "faq.conf"></a>6.14. Configuration files - handling and placement</h2> - </div> - </div> - </div> - - <p>The global variable <code class= - "varname">PKG_SYSCONFBASE</code> (and some others) can be - set by the system administrator in <code class= - "filename">/etc/mk.conf</code> to define the place where - configuration files get installed. Therefore, packages - must be adapted to support this feature. Keep in mind - that you should only install files that are strictly - necessary in the configuration directory, files that can - go to <code class="filename">$PREFIX/share</code> should - go there.</p> - - <p>We will take a look at available variables first - (<code class="filename">bsd.pkg.mk</code> contains more - information). <code class="varname">PKG_SYSCONFDIR</code> - is where the configuration files for a package may be - found (that is, the full path, e.g. <code class= - "filename">/etc</code> or <code class= - "filename">/usr/pkg/etc</code>). This value may be - customized in various ways:</p> - - <div class="orderedlist"> - <ol type="1"> - <li> - <p><code class="varname">PKG_SYSCONFBASE</code> is - the main config directory under which all package - configuration files are to be found. Users will - typically want to set it to <code class= - "filename">/etc</code>, or accept the default - location of <code class= - "filename">$PREFIX/etc</code>.</p> - </li> - - <li> - <p><code class="varname">PKG_SYSCONFSUBDIR</code> - is the subdirectory of <code class= - "varname">PKG_SYSCONFBASE</code> under which the - configuration files for a particular package may be - found. Defaults to <code class= - "varname">${SYSCONFBASE}</code>.</p> - </li> - - <li> - <p><code class="varname">PKG_SYSCONFVAR</code> is - the special suffix used to distinguish any - overriding values for a particular package (see - next item). It defaults to <code class= - "varname">${PKGBASE}</code>, but for a collection - of related packages that should all have the same - <code class="varname">PKG_SYSCONFDIR</code> value, - it can be set in each of the package Makefiles to a - common value.</p> - </li> - - <li> - <p><code class= - "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> - overrides the value of <code class= - "varname">${PKG_SYSCONFDIR}</code> for packages - with the same value for <code class= - "varname">PKG_SYSCONFVAR</code>.</p> - - <p>As an example, all the various KDE packages may - want to set <code class= - "varname">PKG_SYSCONFVAR</code> to - “<span class="quote">kde</span>” so - admins can set <code class= - "varname">PKG_SYSCONFDIR.kde</code> in <code class= - "filename">/etc/mk.conf</code> to define where to - install KDE config files.</p> - </li> - </ol> - </div> - - <p>Programs' configuration directory should be defined - during the configure stage. Packages that use GNU - autoconf can usually do this by using the - “<span class="quote">--sysconfdir</span>” - parameter, but this brings some problems as we will see - now. When you change this pathname in packages, you - should not allow them to install files in that directory - directly. Instead they need to install those files under - <code class="filename">share/examples/${PKGNAME}</code> - so <code class="filename">PLIST</code> can register - them.</p> - - <p>Once you have the required configuration files in - place (under the <code class= - "filename">share/examples</code> directory) the variable - <code class="varname">CONF_FILES</code> should be set to - copy them into <code class= - "varname">PKG_SYSCONFDIR</code>. The contents of this - variable is formed by pairs of filenames; the first - element of the pair specifies the file inside the - examples directory (registered by <code class= - "filename">PLIST</code>) and the second element specifies - the target file. This is done this way to allow binary - packages to place files in the right directory using - <code class="filename">INSTALL</code>/<code class= - "filename">DEINSTALL</code> scripts which are created - automatically. The package <code class= - "filename">Makefile</code> must also set <code class= - "varname">USE_PKGINSTALL=YES</code> to use these - automatically generated scripts. The automatic copying of - config files can be toggled by setting the environment - variable <code class="varname">PKG_CONFIG</code> prior to - package installation.</p> - - <p>Here is an example, taken from <code class= - "filename">mail/mutt/Makefile</code>:</p> - <pre class="programlisting"> -EGDIR= ${PREFIX}/share/doc/mutt/samples -CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc -</pre> - - <p>As you can see, this package installs configuration - files inside <code class="varname">EGDIR</code>, which - are registered by <code class="filename">PLIST</code>. - After that, the variable <code class= - "varname">CONF_FILES</code> lists the installed file - first and then the target file. Users will also get an - automatic message when files are installed using this - method.</p> + "faq.conf" id="faq.conf"></a>6.14. How do I + change the location of configuration files?</h2> + </div> + </div> + </div> + + <p>As the system administrator, you can choose where + configuration files are installed. The default settings + make all these files go into <code class= + "filename">${PREFIX}/etc</code> or some of its + subdirectories; this may be suboptimal depending on your + expectations (e.g., a read-only, NFS-exported + <code class="varname">PREFIX</code> with a need of + per-machine configuration of the provided packages).</p> + + <p>In order to change the defaults, you can modify the + <code class="varname">PKG_SYSCONFBASE</code> variable (in + <code class="filename">/etc/mk.conf</code>) to point to + your preferred configuration directory; some common + examples include <code class="filename">/etc</code> or + <code class="filename">/etc/pkg</code>.</p> + + <p>Furthermore, you can change this value on a + per-package basis by setting the <code class= + "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> + variable. <code class="varname">PKG_SYSCONFVAR</code>'s + value usually matches the name of the package you would + like to modify, that is, the contents of <code class= + "varname">PKGBASE</code>.</p> + + <p>Note that, after changing these settings, you must + rebuild and reinstall any affected packages.</p> </div> <div class="sect1" lang="en" xml:lang="en"> @@ -5102,260 +5070,323 @@ CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc </dl> </dd> - <dt><span class="chapter"><a href="#options">11. Options + <dt><span class="chapter"><a href="#pkginstall">11. The + pkginstall framework</a></span></dt> + + <dd> + <dl> + <dt><span class="sect1"><a href= + "#files-and-dirs-outside-prefix">11.1. Files and + directories outside the installation + prefix</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#dirs-outside-prefix">11.1.1. Directory + manipulation</a></span></dt> + + <dt><span class="sect2"><a href= + "#files-outside-prefix">11.1.2. File + manipulation</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href="#conf-files">11.2. + Configuration files</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#conf-files-sysconfdir">11.2.1. How <code class= + "varname">PKG_SYSCONFDIR</code> is + set</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-configure">11.2.2. Telling the + software were configuration files + are</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-patching">11.2.3. Patching + installations</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-disable">11.2.4. Disabling handling + of configuration files</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href="#rcd-scripts">11.3. + System startup scripts</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#rcd-scripts-disable">11.3.1. Disabling handling + of system startup scripts</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href= + "#users-and-groups">11.4. System users and + groups</a></span></dt> + + <dt><span class="sect1"><a href="#shells">11.5. + System shells</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#shells-disable">11.5.1. Disabling handling of + configuration files</a></span></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><span class="chapter"><a href="#options">12. Options handling</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#global-default-options">11.1. Global default + "#global-default-options">12.1. Global default options</a></span></dt> <dt><span class="sect1"><a href= - "#converting-to-options">11.2. Converting packages to + "#converting-to-options">12.2. Converting packages to use <code class= "filename">bsd.options.mk</code></a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#build">12. The build + <dt><span class="chapter"><a href="#build">13. The build process</a></span></dt> <dd> <dl> - <dt><span class="sect1"><a href="#build.prefix">12.1. + <dt><span class="sect1"><a href="#build.prefix">13.1. Program location</a></span></dt> - <dt><span class="sect1"><a href="#main-targets">12.2. + <dt><span class="sect1"><a href="#main-targets">13.2. Main targets</a></span></dt> <dt><span class="sect1"><a href= - "#build.helpful-targets">12.3. Other helpful + "#build.helpful-targets">13.3. Other helpful targets</a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#fixes">13. Notes on + <dt><span class="chapter"><a href="#fixes">14. Notes on fixes for packages</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#general-operation">13.1. General + "#general-operation">14.1. General operation</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#pulling-vars-from-etc-mk.conf">13.1.1. How to + "#pulling-vars-from-etc-mk.conf">14.1.1. How to pull in variables from /etc/mk.conf</a></span></dt> <dt><span class="sect2"><a href= - "#where-to-install-documentation">13.1.2. Where + "#where-to-install-documentation">14.1.2. Where to install documentation</a></span></dt> <dt><span class="sect2"><a href= - "#restricted-packages">13.1.3. Restricted + "#restricted-packages">14.1.3. Restricted packages</a></span></dt> <dt><span class="sect2"><a href= - "#dependencies">13.1.4. Handling + "#dependencies">14.1.4. Handling dependencies</a></span></dt> <dt><span class="sect2"><a href= - "#conflicts">13.1.5. Handling conflicts with + "#conflicts">14.1.5. Handling conflicts with other packages</a></span></dt> <dt><span class="sect2"><a href= - "#not-building-packages">13.1.6. Packages that + "#not-building-packages">14.1.6. Packages that cannot or should not be built</a></span></dt> <dt><span class="sect2"><a href= - "#undeletable-packages">13.1.7. Packages which + "#undeletable-packages">14.1.7. Packages which should not be deleted, once installed</a></span></dt> <dt><span class="sect2"><a href= - "#security-handling">13.1.8. Handling packages + "#security-handling">14.1.8. Handling packages with security problems</a></span></dt> <dt><span class="sect2"><a href= - "#compiler-bugs">13.1.9. How to handle compiler + "#compiler-bugs">14.1.9. How to handle compiler bugs</a></span></dt> <dt><span class="sect2"><a href= - "#bumping-pkgrevision">13.1.10. How to handle + "#bumping-pkgrevision">14.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt> <dt><span class="sect2"><a href= - "#portability-of-packages">13.1.11. Portability + "#portability-of-packages">14.1.11. Portability of packages</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#downloading-issues">13.2. Possible downloading + "#downloading-issues">14.2. Possible downloading issues</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#no-plain-download">13.2.1. Packages whose + "#no-plain-download">14.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt> <dt><span class="sect2"><a href= - "#modified-distfiles-same-name">13.2.2. How to + "#modified-distfiles-same-name">14.2.2. How to handle modified distfiles with the 'old' name</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#configuration-gotchas">13.3. Configuration + "#configuration-gotchas">14.3. Configuration gotchas</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#fixes.libtool">13.3.1. Shared libraries - + "#fixes.libtool">14.3.1. Shared libraries - libtool</a></span></dt> <dt><span class="sect2"><a href= - "#using-libtool">13.3.2. Using libtool on GNU + "#using-libtool">14.3.2. Using libtool on GNU packages that already support libtool</a></span></dt> <dt><span class="sect2"><a href= - "#autoconf-automake">13.3.3. GNU + "#autoconf-automake">14.3.3. GNU Autoconf/Automake</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#building-considerations">13.4. Building + "#building-considerations">14.4. Building considerations</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#cpp-defines">13.4.1. CPP + "#cpp-defines">14.4.1. CPP defines</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#package-specific-actions">13.5. Package specific + "#package-specific-actions">14.5. Package specific actions</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#package-configuration-files">13.5.1. Package - configuration files</a></span></dt> - - <dt><span class="sect2"><a href= - "#user-interaction">13.5.2. User + "#user-interaction">14.5.1. User interaction</a></span></dt> <dt><span class="sect2"><a href= - "#handling-licenses">13.5.3. Handling + "#handling-licenses">14.5.2. Handling licenses</a></span></dt> <dt><span class="sect2"><a href= - "#creating-accounts">13.5.4. Creating an account - from a package</a></span></dt> - - <dt><span class="sect2"><a href= - "#installing-score-files">13.5.5. Installing + "#installing-score-files">14.5.3. Installing score files</a></span></dt> <dt><span class="sect2"><a href= - "#login-shells">13.5.6. Packages providing login - shells</a></span></dt> - - <dt><span class="sect2"><a href= - "#perl-scripts">13.5.7. Packages containing perl + "#perl-scripts">14.5.4. Packages containing perl scripts</a></span></dt> <dt><span class="sect2"><a href= - "#hardcoded-paths">13.5.8. Packages with + "#hardcoded-paths">14.5.5. Packages with hardcoded paths to other interpreters</a></span></dt> <dt><span class="sect2"><a href= - "#perl-modules">13.5.9. Packages installing perl + "#perl-modules">14.5.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href= - "#faq.info-files">13.5.10. Packages installing + "#faq.info-files">14.5.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href= - "#gconf2-data-files">13.5.11. Packages installing + "#gconf2-data-files">14.5.8. Packages installing GConf2 data files</a></span></dt> <dt><span class="sect2"><a href= - "#scrollkeeper-data-files">13.5.12. Packages + "#scrollkeeper-data-files">14.5.9. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href= - "#x11-fonts">13.5.13. Packages installing X11 + "#x11-fonts">14.5.10. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href= - "#gtk2-modules">13.5.14. Packages installing GTK2 + "#gtk2-modules">14.5.11. Packages installing GTK2 modules</a></span></dt> <dt><span class="sect2"><a href= - "#sgml-xml-data">13.5.15. Packages installing + "#sgml-xml-data">14.5.12. Packages installing SGML or XML data</a></span></dt> <dt><span class="sect2"><a href= - "#mime-database">13.5.16. Packages installing + "#mime-database">14.5.13. Packages installing extensions to the MIME database</a></span></dt> <dt><span class="sect2"><a href= - "#intltool">13.5.17. Packages using + "#intltool">14.5.14. Packages using intltool</a></span></dt> <dt><span class="sect2"><a href= - "#startup-scripts">13.5.18. Packages installing + "#startup-scripts">14.5.15. Packages installing startup scripts</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#feedback-to-author">13.6. Feedback to the + "#feedback-to-author">14.6. Feedback to the author</a></span></dt> </dl> </dd> - <dt><span class="chapter"><a href="#debug">14. + <dt><span class="chapter"><a href="#debug">15. Debugging</a></span></dt> - <dt><span class="chapter"><a href="#submit">15. + <dt><span class="chapter"><a href="#submit">16. Submitting and Committing</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#submitting-your-package">15.1. Submitting your + "#submitting-your-package">16.1. Submitting your packages</a></span></dt> <dt><span class="sect1"><a href= - "#committing-importing">15.2. Committing: Importing a + "#committing-importing">16.2. Committing: Importing a package into CVS</a></span></dt> <dt><span class="sect1"><a href= - "#updating-package">15.3. Updating a package to a + "#updating-package">16.3. Updating a package to a newer version</a></span></dt> <dt><span class="sect1"><a href= - "#moving-package">15.4. Moving a package in + "#moving-package">16.4. Moving a package in pkgsrc</a></span></dt> </dl> </dd> @@ -5599,8 +5630,8 @@ converters games mbone print x11 <li> <p>If the package installs any info files, see <a href="#faq.info-files" title= - "13.5.10. Packages installing info files">Section - 13.5.10, “Packages installing info + "14.5.7. Packages installing info files">Section + 14.5.7, “Packages installing info files”</a>.</p> </li> @@ -6609,7 +6640,7 @@ for_test: print-PLIST</strong></span> command to output a PLIST that matches any new files since the package was extracted. See <a href="#build.helpful-targets" title= - "12.3. Other helpful targets">Section 12.3, + "13.3. Other helpful targets">Section 13.3, “Other helpful targets”</a> for more information on this target.</p> </div> @@ -7546,8 +7577,8 @@ BUILDLINK_DEPTH:= ${BUILDLINK_DEPTH:S/+$//} want to cause unneeded package deletions and rebuilds. In many cases, new versions of packages work just fine with older dependencies. See <a href="#dependencies" - title="13.1.4. Handling dependencies">Section - 13.1.4, “Handling dependencies”</a> and + title="14.1.4. Handling dependencies">Section + 14.1.4, “Handling dependencies”</a> and <a href="#buildlink" title= "Chapter 10. Buildlink methodology">Chapter 10, <i>Buildlink methodology</i></a> for more @@ -7792,8 +7823,738 @@ CHECK_BUILTIN.foo?= no <div class="titlepage"> <div> <div> + <h2 class="title"><a name="pkginstall" id= + "pkginstall"></a>Chapter 11. The pkginstall + framework</h2> + </div> + </div> + </div> + + <div class="toc"> + <p><b>Table of Contents</b></p> + + <dl> + <dt><span class="sect1"><a href= + "#files-and-dirs-outside-prefix">11.1. Files and + directories outside the installation + prefix</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#dirs-outside-prefix">11.1.1. Directory + manipulation</a></span></dt> + + <dt><span class="sect2"><a href= + "#files-outside-prefix">11.1.2. File + manipulation</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href="#conf-files">11.2. + Configuration files</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#conf-files-sysconfdir">11.2.1. How <code class= + "varname">PKG_SYSCONFDIR</code> is + set</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-configure">11.2.2. Telling the + software were configuration files + are</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-patching">11.2.3. Patching + installations</a></span></dt> + + <dt><span class="sect2"><a href= + "#conf-files-disable">11.2.4. Disabling handling of + configuration files</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href="#rcd-scripts">11.3. + System startup scripts</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#rcd-scripts-disable">11.3.1. Disabling handling + of system startup scripts</a></span></dt> + </dl> + </dd> + + <dt><span class="sect1"><a href= + "#users-and-groups">11.4. System users and + groups</a></span></dt> + + <dt><span class="sect1"><a href="#shells">11.5. System + shells</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#shells-disable">11.5.1. Disabling handling of + configuration files</a></span></dt> + </dl> + </dd> + </dl> + </div> + + <p>This chapter describes the framework known as + <code class="literal">pkginstall</code>, whose key features + are:</p> + + <div class="itemizedlist"> + <ul type="disc"> + <li> + <p>Generic installation and manipulation of + directories and files outside the pkgsrc-handled + tree, <code class="varname">LOCALBASE</code>.</p> + </li> + + <li> + <p>Automatic handling of configuration files during + installation, provided that packages are correctly + designed.</p> + </li> + + <li> + <p>Generation and installation of system startup + scripts.</p> + </li> + + <li> + <p>Registration of system users and groups.</p> + </li> + + <li> + <p>Registration of system shells.</p> + </li> + </ul> + </div> + + <p>The following sections inspect each of the above points + in detail. Note that, in order to use any of the described + functionalities, you must add the following to your + package's <code class="filename">Makefile</code>:</p> + <pre class="programlisting"> +USE_PKGINSTALL=YES +</pre> + + <p>You may be thinking that many of the things described + here could be easily done with simple code in the package's + post-installation target (<code class= + "literal">post-install</code>). <span class= + "emphasis"><em>This is incorrect</em></span>, as the code + in them is only executed when building from source. + Machines using binary packages could not benefit from it at + all (as the code itself could be unavailable). Therefore, + the only way to achieve any of the items described above is + by means of the installation scripts, which are + automatically generated by pkginstall.</p> + + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "files-and-dirs-outside-prefix" id= + "files-and-dirs-outside-prefix"></a>11.1. Files and + directories outside the installation prefix</h2> + </div> + </div> + </div> + + <p>As you already know, the <code class= + "filename">PLIST</code> file holds a list of files and + directories that belong to a package. The names used in + it are relative to the installation prefix (<code class= + "filename">${PREFIX}</code>), which means that it cannot + register files outside this directory (absolute path + names are not allowed). Despite this restriction, some + packages need to install files outside this location; + e.g., under <code class="filename">${VARBASE}</code> or + <code class="filename">${PKG_SYSCONFDIR}</code>.</p> + + <p>The only way to achieve this is to create such files + during installation time by using the installation + scripts. These scripts can run arbitrary commands, so + they have the potential to create and manage files + anywhere in the filesystem. Here is where pkginstall + comes into play: it provides generic scripts to abstract + the manipulation of such files and directories based on + variables set in the package's <code class= + "filename">Makefile</code>. The rest of this section + describes which these variables are.</p> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="dirs-outside-prefix" + id="dirs-outside-prefix"></a>11.1.1. Directory + manipulation</h3> + </div> + </div> + </div> + + <p>The following variables can be set to request the + creation of directories anywhere in the filesystem:</p> + + <div class="itemizedlist"> + <ul type="disc"> + <li> + <p><code class="varname">MAKE_DIRS</code> and + <code class="varname">OWN_DIRS</code> contain a + list of directories that should be created and + should attempt to be destroyed by the + installation scripts. The difference between the + two is that the latter prompts the administrator + to remove any directories that may be left after + deinstallation (because they were not empty), + while the former does not.</p> + </li> + + <li> + <p><code class="varname">MAKE_DIRS_PERMS</code> + and <code class="varname">OWN_DIRS_PERMS</code> + contain a list of tuples describing which + directories should be created and should attempt + to be destroyed by the installation scripts. Each + tuple holds the following values, separated by + spaces: the directory name, its owner, its group + and its numerical mode. For example:</p> + <pre class="programlisting"> +MAKE_DIRS_PERMS+= ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700 +</pre> + + <p>The difference between the two is exactly the + same as their non-<code class= + "varname">PERMS</code> counterparts.</p> + </li> + </ul> + </div> + </div> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="files-outside-prefix" + id="files-outside-prefix"></a>11.1.2. File + manipulation</h3> + </div> + </div> + </div> + + <p>Creating non-empty files outside the installation + prefix is tricky because the <code class= + "filename">PLIST</code> forces all files to be inside + it. To overcome this problem, the only solution is to + extract the file in the known place (i.e., inside the + installation prefix) and copy it to the appropriate + location during installation (done by the installation + scripts generated by pkginstall). We will call the + former the <span class="emphasis"><em>master + file</em></span> in the following paragraphs, which + describe the variables that can be used to + automatically and consistently handle files outside the + installation prefix:</p> + + <div class="itemizedlist"> + <ul type="disc"> + <li> + <p><code class="varname">CONF_FILES</code> and + <code class="varname">SUPPORT_FILES</code> are + pairs of master and target files. During + installation time, the master file is copied to + the target one if and only if the latter does not + exist. Upon deinstallation, the target file is + removed provided that it was not modified by the + installation.</p> + + <p>The difference between the two is that the + latter prompts the administrator to remove any + files that may be left after deinstallation + (because they were not empty), while the former + does not.</p> + </li> + + <li> + <p><code class="varname">CONF_FILES_PERMS</code> + and <code class= + "varname">SUPPORT_FILES_PERMS</code> contain + tuples describing master files as well as their + target locations. For each of them, it also + specifies their owner, their group and their + numeric permissions, in this order. For + example:</p> + <pre class="programlisting"> +SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700 +</pre> + + <p>The difference between the two is exactly the + same as their non-<code class= + "varname">PERMS</code> counterparts.</p> + </li> + </ul> + </div> + </div> + </div> + + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "conf-files" id="conf-files"></a>11.2. + Configuration files</h2> + </div> + </div> + </div> + + <p>Configuration files are special in the sense that they + are installed in their own specific directory, + <code class="varname">PKG_SYSCONFDIR</code>, and need + special treatment during installation (most of which is + automated by pkginstall). The main concept you must bear + in mind is that files marked as a configuration are + automatically copied to the right place (somewhere inside + <code class="varname">PKG_SYSCONFDIR</code>) during + installation <span class="emphasis"><em>if and only + if</em></span> they didn't exist before. Similarly, they + will not be removed if they have local modifications. + This ensures that administrators never loose any custom + changes they may have made.</p> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="conf-files-sysconfdir" + id="conf-files-sysconfdir"></a>11.2.1. How + <code class="varname">PKG_SYSCONFDIR</code> is + set</h3> + </div> + </div> + </div> + + <p>As said before, the <code class= + "varname">PKG_SYSCONFDIR</code> variable specifies + where configuration files shall be installed. Its + contents are set based upon the following + variables:</p> + + <div class="itemizedlist"> + <ul type="disc"> + <li> + <p><code class="varname">PKG_SYSCONFBASE</code>: + The configuration's root directory. Defaults to + <code class="filename">${PREFIX}/etc</code> + although may be overridden by the user to point + to his preferred location (e.g., <code class= + "filename">/etc</code>, <code class= + "filename">/etc/pkg</code>, etc.). Packages must + not use it directly.</p> + </li> + + <li> + <p><code class= + "varname">PKG_SYSCONFSUBDIR</code>: A + subdirectory of <code class= + "varname">PKG_SYSCONFBASE</code> under which the + configuration files for the package being built + shall be installed. The definition of this + variable only makes sense in the package's + <code class="filename">Makefile</code> (i.e., it + is not user customizable).</p> + + <p>As an example, consider the Apache package, + <a xmlns= + "http://www.w3.org/TR/xhtml1/transitional" href= + "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache2/README.html" + class="pkgname">www/apache2</a>, which places its + configuration files under the <code class= + "filename">httpd/</code> subdirectory of + <code class="varname">PKG_SYSCONFBASE</code>. + This should be set in the package Makefile.</p> + </li> + + <li> + <p><code class="varname">PKG_SYSCONFVAR</code>: + Specifies the name of the variable that holds + this package's configuration directory (if + different from <code class= + "varname">PKG_SYSCONFBASE</code>). It defaults to + <code class="varname">PKGBASE</code>'s value, and + is always prefixed with <code class= + "literal">PKG_SYSCONFDIR</code>.</p> + </li> + + <li> + <p><code class= + "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>: + Holds the directory where the configuration files + for the package identified by <code class= + "varname">PKG_SYSCONFVAR</code>'s shall be + placed.</p> + </li> + </ul> + </div> + + <p>Based on the above variables, pkginstall determines + the value of <code class= + "varname">PKG_SYSCONFDIR</code>, which is the + <span class="emphasis"><em>only</em></span> variable + that can be used within a package to refer to its + configuration directory. The algorithm used to set its + value is basically the following:</p> + + <div class="orderedlist"> + <ol type="1"> + <li> + <p>If <code class= + "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> + is set, its value is used.</p> + </li> + + <li> + <p>If the previous variable is not defined but + <code class="varname">PKG_SYSCONFSUBDIR</code> is + set in the package's <code class= + "filename">Makefile</code>, the resulting value + is <code class= + "filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p> + </li> + + <li> + <p>Otherwise, it is set to <code class= + "filename">${PKG_SYSCONFBASE}</code>.</p> + </li> + </ol> + </div> + + <p>It is worth mentioning that <code class= + "filename">${PKG_SYSCONFDIR}</code> is automatically + added to <code class="filename">OWN_DIRS</code>. See + <a href="#dirs-outside-prefix" title= + "11.1.1. Directory manipulation">Section 11.1.1, + “Directory manipulation”</a> what this + means.</p> + </div> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="conf-files-configure" + id="conf-files-configure"></a>11.2.2. Telling the + software were configuration files are</h3> + </div> + </div> + </div> + + <p>Given that pkgsrc (and users!) expect configuration + files to be in a known place, you need to teach each + package where shall it install its files. In some cases + you will have to patch the package Makefiles to achieve + it. If you are lucky, though, it may be as easy as + passing an extra flag to the configuration script; this + is the case of GNU Autoconf generated files:</p> + <pre class="programlisting"> +CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR} +</pre> + + <p>Note that this specifies where the package has to + <span class="emphasis"><em>look for</em></span> its + configuration files, not where they will be originally + installed (although the difference is never explicit, + unfortunately).</p> + </div> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="conf-files-patching" + id="conf-files-patching"></a>11.2.3. Patching + installations</h3> + </div> + </div> + </div> + + <p>As said before, pkginstall automatically handles + configuration files. This means that <span class= + "strong"><strong>the packages themselves must not touch + the contents of <code class= + "filename">${PKG_SYSCONFDIR}</code> + directly</strong></span>. Bad news is that the software + they build will, out of the box, mess with the contents + of that directory. So which is the correct procedure to + fix this issue?</p> + + <p>You must teach the package (usually by manually + patching it) to install any configuration files under + the examples hierarchy, <code class= + "filename">share/examples/${PKGBASE}/</code>. This way, + the <code class="filename">PLIST</code> registers them + and the administrator always has the original copies + available.</p> + + <p>Once the required configuration files are in place + (i.e., under the examples hierarchy), the pkginstall + framework can use them as master copies during the + package installation to update what is in <code class= + "filename">${PKG_SYSCONFDIR}</code>. To achieve this, + the variables <code class="varname">CONF_FILES</code> + and <code class="varname">CONF_FILES_PERMS</code> are + used. Check out <a href="#files-outside-prefix" title= + "11.1.2. File manipulation">Section 11.1.2, + “File manipulation”</a> for information + about their syntax and their purpose. Here is an + example, taken from the <a xmlns= + "http://www.w3.org/TR/xhtml1/transitional" href= + "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/mail/mutt/README.html" + class="pkgname">mail/mutt</a> package:</p> + <pre class="programlisting"> +EGDIR= ${PREFIX}/share/doc/mutt/samples +CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc +</pre> + + <p>Note that the <code class="varname">EGDIR</code> + variable is specific to that package and has no meaning + outside it.</p> + </div> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="conf-files-disable" + id="conf-files-disable"></a>11.2.4. Disabling + handling of configuration files</h3> + </div> + </div> + </div> + + <p>The automatic copying of config files can be toggled + by setting the environment variable <code class= + "varname">PKG_CONFIG</code> prior to package + installation.</p> + </div> + </div> + + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "rcd-scripts" id="rcd-scripts"></a>11.3. System + startup scripts</h2> + </div> + </div> + </div> + + <p>System startup scripts are special files because they + must be installed in a place known by the underlying OS, + usually outside the installation prefix. Therefore, the + same rules described in <a href= + "#files-and-dirs-outside-prefix" title= + "11.1. Files and directories outside the installation prefix"> + Section 11.1, “Files and directories outside the + installation prefix”</a> apply, and the same + solutions can be used. However, pkginstall provides a + specific mechanism to handle these files, given that they + are special.</p> + + <p>In order to provide system startup scripts, the + package has to:</p> + + <div class="orderedlist"> + <ol type="1"> + <li> + <p>Store the script inside <code class= + "filename">${FILESDIR}</code>, with the + <code class="literal">.sh</code> suffix appended. + Considering the <a xmlns= + "http://www.w3.org/TR/xhtml1/transitional" href= + "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/cups/README.html" + class="pkgname">print/cups</a> package as an + example, it has the <code class= + "filename">cupsd.sh</code> in its files + directory.</p> + </li> + + <li> + <p>Tell pkginstall to handle it, appending the name + of the script, without its extension, to the + <code class="varname">RCD_SCRIPTS</code> variable. + Continuing the previous example:</p> + <pre class="programlisting"> +RCD_SCRIPTS+= cupsd +</pre> + </li> + </ol> + </div> + + <p>Once this is done, pkginstall will do the following + steps for each script in an automated fashion:</p> + + <div class="orderedlist"> + <ol type="1"> + <li> + <p>Process the file found in the files directory + applying all the substitutions described in the + <code class="filename">FILES_SUBST</code> + variable.</p> + </li> + + <li> + <p>Copy the script from the files directory to the + examples hierarchy, <code class= + "filename">${PREFIX}/share/examples/rc.d/</code>. + Note that the master file must be explicitly + registered in the <code class= + "filename">PLIST</code>.</p> + </li> + + <li> + <p>Add code to the installation scripts to copy the + startup script from the examples hierarchy into the + system-wide startup scripts directory.</p> + </li> + </ol> + </div> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="rcd-scripts-disable" + id="rcd-scripts-disable"></a>11.3.1. Disabling + handling of system startup scripts</h3> + </div> + </div> + </div> + + <p>The automatic copying of config files can be toggled + by setting the environment variable <code class= + "varname">PKG_RCD_SCRIPTS</code> prior to package + installation. Note that the scripts will be always + copied inside the examples hierarchy, <code class= + "filename">${PREFIX}/share/examples/rc.d/</code>, no + matter what the value of this variable is.</p> + </div> + </div> + + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "users-and-groups" id="users-and-groups"></a>11.4. + System users and groups</h2> + </div> + </div> + </div> + + <p>If a package needs to create special users and/or + groups during installation, it can do so by using the + pkginstall framework.</p> + + <p>Users can be created by adding entries to the + <code class="varname">PKG_USERS</code> variable. Each + entry has the following syntax, which mimics <code class= + "filename">/etc/passwd</code>:</p> + <pre class="programlisting"> +user:group[:[userid][:[descr][:[home][:shell]]]] +</pre> + + <p>Only the user and group are required; everything else + is optional, but the colons must be in the right places + when specifying optional bits. By default, a new user + will have home directory <code class= + "filename">/nonexistent</code>, and login shell + <code class="filename">/sbin/nologin</code> unless they + are specified as part of the user element. Note that if + the description contains spaces, then spaces should be + double backslash-escaped, as in:</p> + <pre class="programlisting"> +foo:foogrp::The\\ Foomister +</pre> + + <p>Similarly, groups can be created using the + <code class="varname">PKG_GROUPS</code> variable, whose + syntax is:</p> + <pre class="programlisting"> +group[:groupid] +</pre> + + <p>As before, only the group name is required; the + numeric identifier is optional.</p> + </div> + + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "shells" id="shells"></a>11.5. System shells</h2> + </div> + </div> + </div> + + <p>Packages that install system shells should register + them in the shell database, <code class= + "filename">/etc/shells</code>, to make things easier to + the administrator. This must be done from the + installation scripts to keep binary packages working on + any system. pkginstall provides an easy way to accomplish + this task.</p> + + <p>When a package provides a shell interpreter, it has to + set the <code class="varname">PKG_SHELL</code> variable + to its absolute file name. This will add some hooks to + the installation scripts to handle it. Consider the + following example, taken from <a xmlns= + "http://www.w3.org/TR/xhtml1/transitional" href= + "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/zsh/README.html" + class="pkgname">shells/zsh</a>:</p> + <pre class="programlisting"> +USE_PKGINSTALL= YES +PKG_SHELL= ${PREFIX}/bin/zsh +</pre> + + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name="shells-disable" id= + "shells-disable"></a>11.5.1. Disabling handling + of configuration files</h3> + </div> + </div> + </div> + + <p>The automatic registration of shell interpreters can + be disabled by the administrator by setting the + <code class="filename">PKG_REGISTER_SHELLS</code> + environment variable to <code class= + "literal">NO</code>.</p> + </div> + </div> + </div> + + <div class="chapter" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> <h2 class="title"><a name="options" id= - "options"></a>Chapter 11. Options + "options"></a>Chapter 12. Options handling</h2> </div> </div> @@ -7804,11 +8565,11 @@ CHECK_BUILTIN.foo?= no <dl> <dt><span class="sect1"><a href= - "#global-default-options">11.1. Global default + "#global-default-options">12.1. Global default options</a></span></dt> <dt><span class="sect1"><a href= - "#converting-to-options">11.2. Converting packages to + "#converting-to-options">12.2. Converting packages to use <code class= "filename">bsd.options.mk</code></a></span></dt> </dl> @@ -7829,7 +8590,7 @@ CHECK_BUILTIN.foo?= no <div> <h2 class="title" style="clear: both"><a name= "global-default-options" id= - "global-default-options"></a>11.1. Global + "global-default-options"></a>12.1. Global default options</h2> </div> </div> @@ -7848,7 +8609,7 @@ CHECK_BUILTIN.foo?= no <div> <h2 class="title" style="clear: both"><a name= "converting-to-options" id= - "converting-to-options"></a>11.2. Converting + "converting-to-options"></a>12.2. Converting packages to use <code class= "filename">bsd.options.mk</code></h2> </div> @@ -7990,7 +8751,7 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} <div> <div> <h2 class="title"><a name="build" id= - "build"></a>Chapter 12. The build + "build"></a>Chapter 13. The build process</h2> </div> </div> @@ -8000,14 +8761,14 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} <p><b>Table of Contents</b></p> <dl> - <dt><span class="sect1"><a href="#build.prefix">12.1. + <dt><span class="sect1"><a href="#build.prefix">13.1. Program location</a></span></dt> - <dt><span class="sect1"><a href="#main-targets">12.2. + <dt><span class="sect1"><a href="#main-targets">13.2. Main targets</a></span></dt> <dt><span class="sect1"><a href= - "#build.helpful-targets">12.3. Other helpful + "#build.helpful-targets">13.3. Other helpful targets</a></span></dt> </dl> </div> @@ -8030,7 +8791,7 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} <div> <h2 class="title" style="clear: both"><a name= "build.prefix" id= - "build.prefix"></a>12.1. Program location</h2> + "build.prefix"></a>13.1. Program location</h2> </div> </div> </div> @@ -8054,7 +8815,7 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} "7.3. patches/*">Section 7.3, “patches/*”</a> and <a href="#fixes.libtool" title= - "13.3.1. Shared libraries - libtool">Section 13.3.1, + "14.3.1. Shared libraries - libtool">Section 14.3.1, “Shared libraries - libtool”</a> for more details.</p> @@ -8205,7 +8966,7 @@ GTKDIR_DEFAULT= ${LOCALBASE} <div> <h2 class="title" style="clear: both"><a name= "main-targets" id= - "main-targets"></a>12.2. Main targets</h2> + "main-targets"></a>13.2. Main targets</h2> </div> </div> </div> @@ -8455,7 +9216,7 @@ make build <div> <h2 class="title" style="clear: both"><a name= "build.helpful-targets" id= - "build.helpful-targets"></a>12.3. Other + "build.helpful-targets"></a>13.3. Other helpful targets</h2> </div> </div> @@ -8973,7 +9734,7 @@ make build <div> <div> <h2 class="title"><a name="fixes" id= - "fixes"></a>Chapter 13. Notes on fixes for + "fixes"></a>Chapter 14. Notes on fixes for packages</h2> </div> </div> @@ -8984,191 +9745,179 @@ make build <dl> <dt><span class="sect1"><a href= - "#general-operation">13.1. General + "#general-operation">14.1. General operation</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#pulling-vars-from-etc-mk.conf">13.1.1. How to + "#pulling-vars-from-etc-mk.conf">14.1.1. How to pull in variables from /etc/mk.conf</a></span></dt> <dt><span class="sect2"><a href= - "#where-to-install-documentation">13.1.2. Where to + "#where-to-install-documentation">14.1.2. Where to install documentation</a></span></dt> <dt><span class="sect2"><a href= - "#restricted-packages">13.1.3. Restricted + "#restricted-packages">14.1.3. Restricted packages</a></span></dt> <dt><span class="sect2"><a href= - "#dependencies">13.1.4. Handling + "#dependencies">14.1.4. Handling dependencies</a></span></dt> <dt><span class="sect2"><a href= - "#conflicts">13.1.5. Handling conflicts with other + "#conflicts">14.1.5. Handling conflicts with other packages</a></span></dt> <dt><span class="sect2"><a href= - "#not-building-packages">13.1.6. Packages that + "#not-building-packages">14.1.6. Packages that cannot or should not be built</a></span></dt> <dt><span class="sect2"><a href= - "#undeletable-packages">13.1.7. Packages which + "#undeletable-packages">14.1.7. Packages which should not be deleted, once installed</a></span></dt> <dt><span class="sect2"><a href= - "#security-handling">13.1.8. Handling packages with + "#security-handling">14.1.8. Handling packages with security problems</a></span></dt> <dt><span class="sect2"><a href= - "#compiler-bugs">13.1.9. How to handle compiler + "#compiler-bugs">14.1.9. How to handle compiler bugs</a></span></dt> <dt><span class="sect2"><a href= - "#bumping-pkgrevision">13.1.10. How to handle + "#bumping-pkgrevision">14.1.10. How to handle incrementing versions when fixing an existing package</a></span></dt> <dt><span class="sect2"><a href= - "#portability-of-packages">13.1.11. Portability of + "#portability-of-packages">14.1.11. Portability of packages</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#downloading-issues">13.2. Possible downloading + "#downloading-issues">14.2. Possible downloading issues</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#no-plain-download">13.2.1. Packages whose + "#no-plain-download">14.2.1. Packages whose distfiles aren't available for plain downloading</a></span></dt> <dt><span class="sect2"><a href= - "#modified-distfiles-same-name">13.2.2. How to + "#modified-distfiles-same-name">14.2.2. How to handle modified distfiles with the 'old' name</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#configuration-gotchas">13.3. Configuration + "#configuration-gotchas">14.3. Configuration gotchas</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#fixes.libtool">13.3.1. Shared libraries - + "#fixes.libtool">14.3.1. Shared libraries - libtool</a></span></dt> <dt><span class="sect2"><a href= - "#using-libtool">13.3.2. Using libtool on GNU + "#using-libtool">14.3.2. Using libtool on GNU packages that already support libtool</a></span></dt> <dt><span class="sect2"><a href= - "#autoconf-automake">13.3.3. GNU + "#autoconf-automake">14.3.3. GNU Autoconf/Automake</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#building-considerations">13.4. Building + "#building-considerations">14.4. Building considerations</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#cpp-defines">13.4.1. CPP defines</a></span></dt> + "#cpp-defines">14.4.1. CPP defines</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#package-specific-actions">13.5. Package specific + "#package-specific-actions">14.5. Package specific actions</a></span></dt> <dd> <dl> <dt><span class="sect2"><a href= - "#package-configuration-files">13.5.1. Package - configuration files</a></span></dt> - - <dt><span class="sect2"><a href= - "#user-interaction">13.5.2. User + "#user-interaction">14.5.1. User interaction</a></span></dt> <dt><span class="sect2"><a href= - "#handling-licenses">13.5.3. Handling + "#handling-licenses">14.5.2. Handling licenses</a></span></dt> <dt><span class="sect2"><a href= - "#creating-accounts">13.5.4. Creating an account - from a package</a></span></dt> - - <dt><span class="sect2"><a href= - "#installing-score-files">13.5.5. Installing score + "#installing-score-files">14.5.3. Installing score files</a></span></dt> <dt><span class="sect2"><a href= - "#login-shells">13.5.6. Packages providing login - shells</a></span></dt> - - <dt><span class="sect2"><a href= - "#perl-scripts">13.5.7. Packages containing perl + "#perl-scripts">14.5.4. Packages containing perl scripts</a></span></dt> <dt><span class="sect2"><a href= - "#hardcoded-paths">13.5.8. Packages with hardcoded + "#hardcoded-paths">14.5.5. Packages with hardcoded paths to other interpreters</a></span></dt> <dt><span class="sect2"><a href= - "#perl-modules">13.5.9. Packages installing perl + "#perl-modules">14.5.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href= - "#faq.info-files">13.5.10. Packages installing info + "#faq.info-files">14.5.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href= - "#gconf2-data-files">13.5.11. Packages installing + "#gconf2-data-files">14.5.8. Packages installing GConf2 data files</a></span></dt> <dt><span class="sect2"><a href= - "#scrollkeeper-data-files">13.5.12. Packages + "#scrollkeeper-data-files">14.5.9. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href= - "#x11-fonts">13.5.13. Packages installing X11 + "#x11-fonts">14.5.10. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href= - "#gtk2-modules">13.5.14. Packages installing GTK2 + "#gtk2-modules">14.5.11. Packages installing GTK2 modules</a></span></dt> <dt><span class="sect2"><a href= - "#sgml-xml-data">13.5.15. Packages installing SGML + "#sgml-xml-data">14.5.12. Packages installing SGML or XML data</a></span></dt> <dt><span class="sect2"><a href= - "#mime-database">13.5.16. Packages installing + "#mime-database">14.5.13. Packages installing extensions to the MIME database</a></span></dt> <dt><span class="sect2"><a href= - "#intltool">13.5.17. Packages using + "#intltool">14.5.14. Packages using intltool</a></span></dt> <dt><span class="sect2"><a href= - "#startup-scripts">13.5.18. Packages installing + "#startup-scripts">14.5.15. Packages installing startup scripts</a></span></dt> </dl> </dd> <dt><span class="sect1"><a href= - "#feedback-to-author">13.6. Feedback to the + "#feedback-to-author">14.6. Feedback to the author</a></span></dt> </dl> </div> @@ -9179,7 +9928,7 @@ make build <div> <h2 class="title" style="clear: both"><a name= "general-operation" id= - "general-operation"></a>13.1. General + "general-operation"></a>14.1. General operation</h2> </div> </div> @@ -9191,7 +9940,7 @@ make build <div> <h3 class="title"><a name= "pulling-vars-from-etc-mk.conf" id= - "pulling-vars-from-etc-mk.conf"></a>13.1.1. How + "pulling-vars-from-etc-mk.conf"></a>14.1.1. How to pull in variables from /etc/mk.conf</h3> </div> </div> @@ -9253,7 +10002,7 @@ CFLAGS+= -your -flags <div> <h3 class="title"><a name= "where-to-install-documentation" id= - "where-to-install-documentation"></a>13.1.2. Where + "where-to-install-documentation"></a>14.1.2. Where to install documentation</h3> </div> </div> @@ -9272,7 +10021,7 @@ CFLAGS+= -your -flags <div> <h3 class="title"><a name="restricted-packages" id= - "restricted-packages"></a>13.1.3. Restricted + "restricted-packages"></a>14.1.3. Restricted packages</h3> </div> </div> @@ -9351,7 +10100,7 @@ CFLAGS+= -your -flags <div> <div> <h3 class="title"><a name="dependencies" id= - "dependencies"></a>13.1.4. Handling + "dependencies"></a>14.1.4. Handling dependencies</h3> </div> </div> @@ -9504,8 +10253,8 @@ RECOMMENDED+= tiff>=3.6.1:../../graphics/tiff vulnerabilities file as well as setting <code class="varname">RECOMMENDED</code>, see <a href="#security-handling" title= - "13.1.8. Handling packages with security problems"> - Section 13.1.8, “Handling packages with + "14.1.8. Handling packages with security problems"> + Section 14.1.8, “Handling packages with security problems”</a> for more information.</p> </li> @@ -9580,7 +10329,7 @@ pre-clean: <div> <div> <h3 class="title"><a name="conflicts" id= - "conflicts"></a>13.1.5. Handling conflicts + "conflicts"></a>14.1.5. Handling conflicts with other packages</h3> </div> </div> @@ -9629,7 +10378,7 @@ CONFLICTS= Xaw3d-[0-9]* <div> <h3 class="title"><a name="not-building-packages" id= - "not-building-packages"></a>13.1.6. Packages + "not-building-packages"></a>14.1.6. Packages that cannot or should not be built</h3> </div> </div> @@ -9662,7 +10411,7 @@ CONFLICTS= Xaw3d-[0-9]* <div> <h3 class="title"><a name="undeletable-packages" id= - "undeletable-packages"></a>13.1.7. Packages + "undeletable-packages"></a>14.1.7. Packages which should not be deleted, once installed</h3> </div> </div> @@ -9687,7 +10436,7 @@ CONFLICTS= Xaw3d-[0-9]* <div> <div> <h3 class="title"><a name="security-handling" id= - "security-handling"></a>13.1.8. Handling + "security-handling"></a>14.1.8. Handling packages with security problems</h3> </div> </div> @@ -9726,7 +10475,7 @@ CONFLICTS= Xaw3d-[0-9]* <div> <div> <h3 class="title"><a name="compiler-bugs" id= - "compiler-bugs"></a>13.1.9. How to handle + "compiler-bugs"></a>14.1.9. How to handle compiler bugs</h3> </div> </div> @@ -9752,7 +10501,7 @@ CONFLICTS= Xaw3d-[0-9]* <div> <div> <h3 class="title"><a name="bumping-pkgrevision" - id="bumping-pkgrevision"></a>13.1.10. How to + id="bumping-pkgrevision"></a>14.1.10. How to handle incrementing versions when fixing an existing package</h3> </div> @@ -9794,7 +10543,7 @@ DISTNAME= foo-17.43 <div> <h3 class="title"><a name= "portability-of-packages" id= - "portability-of-packages"></a>13.1.11. Portability + "portability-of-packages"></a>14.1.11. Portability of packages</h3> </div> </div> @@ -9811,7 +10560,7 @@ DISTNAME= foo-17.43 <div> <div> <h4 class="title"><a name="install-scripts" id= - "install-scripts"></a>13.1.11.1. ${INSTALL}, + "install-scripts"></a>14.1.11.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ...</h4> </div> </div> @@ -9837,7 +10586,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 <div> <h2 class="title" style="clear: both"><a name= "downloading-issues" id= - "downloading-issues"></a>13.2. Possible + "downloading-issues"></a>14.2. Possible downloading issues</h2> </div> </div> @@ -9848,7 +10597,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 <div> <div> <h3 class="title"><a name="no-plain-download" id= - "no-plain-download"></a>13.2.1. Packages + "no-plain-download"></a>14.2.1. Packages whose distfiles aren't available for plain downloading</h3> </div> @@ -9911,7 +10660,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 <div> <h3 class="title"><a name= "modified-distfiles-same-name" id= - "modified-distfiles-same-name"></a>13.2.2. How + "modified-distfiles-same-name"></a>14.2.2. How to handle modified distfiles with the 'old' name</h3> </div> @@ -9952,7 +10701,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 <div> <h2 class="title" style="clear: both"><a name= "configuration-gotchas" id= - "configuration-gotchas"></a>13.3. Configuration + "configuration-gotchas"></a>14.3. Configuration gotchas</h2> </div> </div> @@ -9963,7 +10712,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2 <div> <div> <h3 class="title"><a name="fixes.libtool" id= - "fixes.libtool"></a>13.3.1. Shared libraries + "fixes.libtool"></a>14.3.1. Shared libraries - libtool</h3> </div> </div> @@ -10172,7 +10921,7 @@ ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib <div> <div> <h3 class="title"><a name="using-libtool" id= - "using-libtool"></a>13.3.2. Using libtool on + "using-libtool"></a>14.3.2. Using libtool on GNU packages that already support libtool</h3> </div> </div> @@ -10251,7 +11000,7 @@ ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib <div> <div> <h3 class="title"><a name="autoconf-automake" id= - "autoconf-automake"></a>13.3.3. GNU + "autoconf-automake"></a>14.3.3. GNU Autoconf/Automake</h3> </div> </div> @@ -10260,46 +11009,37 @@ ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib <p>If a package needs GNU autoconf or automake to be executed to regenerate the configure script and Makefile.in makefile templates, then they should be - executed in a pre-configure target. Two Makefile - fragments are provided in <code class= - "filename">pkgsrc/mk/autoconf.mk</code> and - <code class="filename">pkgsrc/mk/automake.mk</code> to - help dealing with these tools. See comments in these - files for details.</p> + executed in a pre-configure target.</p> <p>For packages that need only autoconf:</p> <pre class="programlisting"> -AUTOCONF_REQD= 2.50 # if default version is not good enough +AUTOCONF_REQD= 2.50 # if default version is not good enough +USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 ... pre-configure: - cd ${WRKSRC}; ${AUTOCONF} + cd ${WRKSRC}; autoconf ... -.include "../../mk/autoconf.mk" </pre> <p>and for packages that need automake and autoconf:</p> <pre class="programlisting"> -AUTOMAKE_REQD= 1.7.1 # if default version is not good enough +AUTOMAKE_REQD= 1.7.1 # if default version is not good enough +USE_TOOLS+= automake # use "automake14" for autoconf-1.4 ... pre-configure: cd ${WRKSRC}; \ - ${ACLOCAL}; \ - ${AUTOHEADER}; \ - ${AUTOMAKE} -a --foreign -i; \ - ${AUTOCONF} + aclocal; autoheader; \ + automake -a --foreign -i; autoconf ... -.include "../mk/automake.mk" </pre> <p>Packages which use GNU Automake will almost - certainly require GNU Make, but that's automatically - provided for you in <code class= - "filename">mk/automake.mk</code>.</p> + certainly require GNU Make.</p> <p>There are times when the configure process makes additional changes to the generated files, which then @@ -10318,7 +11058,7 @@ pre-configure: <div> <h2 class="title" style="clear: both"><a name= "building-considerations" id= - "building-considerations"></a>13.4. Building + "building-considerations"></a>14.4. Building considerations</h2> </div> </div> @@ -10329,7 +11069,7 @@ pre-configure: <div> <div> <h3 class="title"><a name="cpp-defines" id= - "cpp-defines"></a>13.4.1. CPP defines</h3> + "cpp-defines"></a>14.4.1. CPP defines</h3> </div> </div> </div> @@ -10369,7 +11109,7 @@ pre-configure: <div> <h2 class="title" style="clear: both"><a name= "package-specific-actions" id= - "package-specific-actions"></a>13.5. Package + "package-specific-actions"></a>14.5. Package specific actions</h2> </div> </div> @@ -10379,82 +11119,8 @@ pre-configure: <div class="titlepage"> <div> <div> - <h3 class="title"><a name= - "package-configuration-files" id= - "package-configuration-files"></a>13.5.1. Package - configuration files</h3> - </div> - </div> - </div> - - <p>Packages should be taught to look for their - configuration files in <code class= - "varname">${PKG_SYSCONFDIR}</code>, which is passed - through to the configure and build processes. - <code class="varname">PKG_SYSCONFDIR</code> may be - customized in various ways by setting other make - variables:</p> - - <div class="itemizedlist"> - <ul type="disc"> - <li> - <p><code class="varname">PKG_SYSCONFBASE</code> - is the main config directory under which all - package configuration files are to be found. This - defaults to <code class= - "filename">${PREFIX}/etc</code>, but may be - overridden in <code class= - "filename">/etc/mk.conf</code>.</p> - </li> - - <li> - <p><code class="varname">PKG_SYSCONFSUBDIR</code> - is the subdirectory of <code class= - "varname">PKG_SYSCONFBASE</code> under which the - configuration files for a particular package may - be found, e.g. the Apache configuration files may - all be found under the <code class= - "filename">httpd/</code> subdirectory of - <code class="varname">${PKG_SYSCONFBASE}</code>. - This should be set in the package Makefile.</p> - </li> - - <li> - <p>By default, <code class= - "varname">PKG_SYSCONFDIR</code> is set to - <code class= - "varname">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>, - but this may be overridden by setting - <code class="varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code> - for a particular package, where <code class= - "varname">PKG_SYSCONFVAR</code> defaults to - <code class="varname">${PKGBASE}</code>. This is - not meant to be set by a package Makefile, but is - reserved for users who wish to override the - <code class="varname">PKG_SYSCONFDIR</code> - setting for a particular package with a special - location.</p> - </li> - </ul> - </div> - - <p>The only variables that users should customize are - <code class="varname">PKG_SYSCONFBASE</code> and - <code class= - "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>. - Users will typically want to set <code class= - "varname">PKG_SYSCONFBASE</code> to <code class= - "filename">/etc</code>, or to accept the default - location of <code class= - "filename">${PREFIX}/etc</code>.</p> - </div> - - <div class="sect2" lang="en" xml:lang="en"> - <div class="titlepage"> - <div> - <div> <h3 class="title"><a name="user-interaction" id= - "user-interaction"></a>13.5.2. User + "user-interaction"></a>14.5.1. User interaction</h3> </div> </div> @@ -10504,7 +11170,7 @@ INTERACTIVE_STAGE= configure install <div> <div> <h3 class="title"><a name="handling-licenses" id= - "handling-licenses"></a>13.5.3. Handling + "handling-licenses"></a>14.5.2. Handling licenses</h3> </div> </div> @@ -10578,64 +11244,9 @@ ACCEPTABLE_LICENSES+=graphviz-license <div class="titlepage"> <div> <div> - <h3 class="title"><a name="creating-accounts" id= - "creating-accounts"></a>13.5.4. Creating an - account from a package</h3> - </div> - </div> - </div> - - <p>There are two make variables used to control the - creation of package-specific groups and users at - pre-install time. The first is <code class= - "varname">PKG_GROUPS</code>, which is a list of - group[:groupid] elements, where the groupid is - optional. The second is <code class= - "varname">PKG_USERS</code>, which is a list of elements - of the form:</p> - <pre class="programlisting"> -user:group[:[userid][:[description][:[home][:shell]]]] -</pre> - - <p>where only the user and group are required, the rest - being optional. A simple example is:</p> - <pre class="programlisting"> - PKG_GROUPS= foogroup - PKG_USERS= foouser:foogroup -</pre> - - <p>A more complex example is that creates two groups - and two users is:</p> - <pre class="programlisting"> - PKG_GROUPS= group1 group2:1005 - PKG_USERS= first:group1::First\\ User \ - second:group2::Second\\ User:/home/second:${SH} -</pre> - - <p>By default, a new user will have home directory - <code class="filename">/nonexistent</code>, and login - shell <code class="filename">/sbin/nologin</code> - unless they are specified as part of the user - element.</p> - - <p>The package <code class="filename">Makefile</code> - must also set <code class= - "varname">USE_PKGINSTALL=YES</code>. This will cause - the users and groups to be created at pre-install time, - and the admin will be prompted to remove them at - post-deinstall time. Automatic creation of the users - and groups can be toggled on and off by setting the - <code class="varname">PKG_CREATE_USERGROUP</code> - variable prior to package installation.</p> - </div> - - <div class="sect2" lang="en" xml:lang="en"> - <div class="titlepage"> - <div> - <div> <h3 class="title"><a name= "installing-score-files" id= - "installing-score-files"></a>13.5.5. Installing + "installing-score-files"></a>14.5.3. Installing score files</h3> </div> </div> @@ -10672,44 +11283,8 @@ user:group[:[userid][:[description][:[home][:shell]]]] <div class="titlepage"> <div> <div> - <h3 class="title"><a name="login-shells" id= - "login-shells"></a>13.5.6. Packages - providing login shells</h3> - </div> - </div> - </div> - - <p>If the purpose of the package is to provide a login - shell, the variable <code class= - "varname">PKG_SHELL</code> should contain the full - pathname of the shell executable installed by this - package. The package <code class= - "filename">Makefile</code> must also set <code class= - "varname">USE_PKGINSTALL=YES</code> to use the - automatically generated <code class= - "filename">INSTALL</code>/<code class= - "filename">DEINSTALL</code> scripts.</p> - - <p>An example taken from shells/zsh:</p> - <pre class="programlisting"> - USE_PKGINSTALL= YES - PKG_SHELL= ${PREFIX}/bin/zsh -</pre> - - <p>The shell is registered into <code class= - "filename">/etc/shells</code> file automatically in the - post-install target by the generated <code class= - "filename">INSTALL</code> script and removed in the - deinstall target by the <code class= - "filename">DEINSTALL</code> script.</p> - </div> - - <div class="sect2" lang="en" xml:lang="en"> - <div class="titlepage"> - <div> - <div> <h3 class="title"><a name="perl-scripts" id= - "perl-scripts"></a>13.5.7. Packages + "perl-scripts"></a>14.5.4. Packages containing perl scripts</h3> </div> </div> @@ -10728,7 +11303,7 @@ user:group[:[userid][:[description][:[home][:shell]]]] <div> <div> <h3 class="title"><a name="hardcoded-paths" id= - "hardcoded-paths"></a>13.5.8. Packages with + "hardcoded-paths"></a>14.5.5. Packages with hardcoded paths to other interpreters</h3> </div> </div> @@ -10755,7 +11330,7 @@ user:group[:[userid][:[description][:[home][:shell]]]] <div> <div> <h3 class="title"><a name="perl-modules" id= - "perl-modules"></a>13.5.9. Packages + "perl-modules"></a>14.5.6. Packages installing perl modules</h3> </div> </div> @@ -10798,7 +11373,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="faq.info-files" id= - "faq.info-files"></a>13.5.10. Packages + "faq.info-files"></a>14.5.7. Packages installing info files</h3> </div> </div> @@ -10895,7 +11470,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="gconf2-data-files" id= - "gconf2-data-files"></a>13.5.11. Packages + "gconf2-data-files"></a>14.5.8. Packages installing GConf2 data files</h3> </div> </div> @@ -10936,10 +11511,10 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <p>Check the PLIST and remove any entries under the etc/gconf directory, as they will be handled automatically. See <a href="#faq.conf" title= - "6.14. Configuration files handling and placement"> - Section 6.14, “Configuration files - handling and placement”</a> for more - information.</p> + "6.14. How do I change the location of configuration files?"> + Section 6.14, “How do I change the + location of configuration files?”</a> for + more information.</p> </li> <li> @@ -10971,7 +11546,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h3 class="title"><a name= "scrollkeeper-data-files" id= - "scrollkeeper-data-files"></a>13.5.12. Packages + "scrollkeeper-data-files"></a>14.5.9. Packages installing scrollkeeper data files</h3> </div> </div> @@ -11016,7 +11591,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="x11-fonts" id= - "x11-fonts"></a>13.5.13. Packages installing + "x11-fonts"></a>14.5.10. Packages installing X11 fonts</h3> </div> </div> @@ -11054,7 +11629,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="gtk2-modules" id= - "gtk2-modules"></a>13.5.14. Packages + "gtk2-modules"></a>14.5.11. Packages installing GTK2 modules</h3> </div> </div> @@ -11121,7 +11696,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="sgml-xml-data" id= - "sgml-xml-data"></a>13.5.15. Packages + "sgml-xml-data"></a>14.5.12. Packages installing SGML or XML data</h3> </div> </div> @@ -11183,7 +11758,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="mime-database" id= - "mime-database"></a>13.5.16. Packages + "mime-database"></a>14.5.13. Packages installing extensions to the MIME database</h3> </div> </div> @@ -11242,7 +11817,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="intltool" id= - "intltool"></a>13.5.17. Packages using + "intltool"></a>14.5.14. Packages using intltool</h3> </div> </div> @@ -11266,7 +11841,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h3 class="title"><a name="startup-scripts" id= - "startup-scripts"></a>13.5.18. Packages + "startup-scripts"></a>14.5.15. Packages installing startup scripts</h3> </div> </div> @@ -11290,7 +11865,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "feedback-to-author" id= - "feedback-to-author"></a>13.6. Feedback to the + "feedback-to-author"></a>14.6. Feedback to the author</h2> </div> </div> @@ -11314,7 +11889,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h2 class="title"><a name="debug" id= - "debug"></a>Chapter 14. Debugging</h2> + "debug"></a>Chapter 15. Debugging</h2> </div> </div> </div> @@ -11504,7 +12079,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <li> <p>Submit (or commit, if you have cvs access); see <a href="#submit" title= - "Chapter 15. Submitting and Committing">Chapter 15, + "Chapter 16. Submitting and Committing">Chapter 16, <i>Submitting and Committing</i></a>.</p> </li> </ul> @@ -11516,7 +12091,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <div> <h2 class="title"><a name="submit" id= - "submit"></a>Chapter 15. Submitting and + "submit"></a>Chapter 16. Submitting and Committing</h2> </div> </div> @@ -11527,18 +12102,18 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <dl> <dt><span class="sect1"><a href= - "#submitting-your-package">15.1. Submitting your + "#submitting-your-package">16.1. Submitting your packages</a></span></dt> <dt><span class="sect1"><a href= - "#committing-importing">15.2. Committing: Importing a + "#committing-importing">16.2. Committing: Importing a package into CVS</a></span></dt> <dt><span class="sect1"><a href= - "#updating-package">15.3. Updating a package to a newer + "#updating-package">16.3. Updating a package to a newer version</a></span></dt> - <dt><span class="sect1"><a href="#moving-package">15.4. + <dt><span class="sect1"><a href="#moving-package">16.4. Moving a package in pkgsrc</a></span></dt> </dl> </div> @@ -11549,7 +12124,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "submitting-your-package" id= - "submitting-your-package"></a>15.1. Submitting + "submitting-your-package"></a>16.1. Submitting your packages</h2> </div> </div> @@ -11582,7 +12157,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <p>First, check that your package is complete, compiles and runs well; see <a href="#debug" title= - "Chapter 14. Debugging">Chapter 14, + "Chapter 15. Debugging">Chapter 15, <i>Debugging</i></a> and the rest of this document. Next, generate an uuencoded gzipped <a href= "http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current"> @@ -11619,7 +12194,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "committing-importing" id= - "committing-importing"></a>15.2. Committing: + "committing-importing"></a>16.2. Committing: Importing a package into CVS</h2> </div> </div> @@ -11676,7 +12251,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "updating-package" id= - "updating-package"></a>15.3. Updating a + "updating-package"></a>16.3. Updating a package to a newer version</h2> </div> </div> @@ -11728,7 +12303,7 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <div> <h2 class="title" style="clear: both"><a name= "moving-package" id= - "moving-package"></a>15.4. Moving a package in + "moving-package"></a>16.4. Moving a package in pkgsrc</h2> </div> </div> diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index ed4ad09cfed..3b22dca40d1 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -104,7 +104,7 @@ I. The pkgsrc user's guide mean? 6.12. What does "Could not find bsd.own.mk" mean? 6.13. Using 'sudo' with pkgsrc - 6.14. Configuration files handling and placement + 6.14. How do I change the location of configuration files? 6.15. Automated security checks II. The pkgsrc developer's guide @@ -157,80 +157,100 @@ II. The pkgsrc developer's guide 10.3.1. Anatomy of a builtin.mk file 10.3.2. Global preferences for native or pkgsrc software - 11. Options handling + 11. The pkginstall framework - 11.1. Global default options - 11.2. Converting packages to use bsd.options.mk + 11.1. Files and directories outside the installation prefix - 12. The build process + 11.1.1. Directory manipulation + 11.1.2. File manipulation - 12.1. Program location - 12.2. Main targets - 12.3. Other helpful targets + 11.2. Configuration files - 13. Notes on fixes for packages + 11.2.1. How PKG_SYSCONFDIR is set + 11.2.2. Telling the software were configuration files are + 11.2.3. Patching installations + 11.2.4. Disabling handling of configuration files - 13.1. General operation + 11.3. System startup scripts - 13.1.1. How to pull in variables from /etc/mk.conf - 13.1.2. Where to install documentation - 13.1.3. Restricted packages - 13.1.4. Handling dependencies - 13.1.5. Handling conflicts with other packages - 13.1.6. Packages that cannot or should not be built - 13.1.7. Packages which should not be deleted, once installed - 13.1.8. Handling packages with security problems - 13.1.9. How to handle compiler bugs - 13.1.10. How to handle incrementing versions when fixing an + 11.3.1. Disabling handling of system startup scripts + + 11.4. System users and groups + 11.5. System shells + + 11.5.1. Disabling handling of configuration files + + 12. Options handling + + 12.1. Global default options + 12.2. Converting packages to use bsd.options.mk + + 13. The build process + + 13.1. Program location + 13.2. Main targets + 13.3. Other helpful targets + + 14. Notes on fixes for packages + + 14.1. General operation + + 14.1.1. How to pull in variables from /etc/mk.conf + 14.1.2. Where to install documentation + 14.1.3. Restricted packages + 14.1.4. Handling dependencies + 14.1.5. Handling conflicts with other packages + 14.1.6. Packages that cannot or should not be built + 14.1.7. Packages which should not be deleted, once installed + 14.1.8. Handling packages with security problems + 14.1.9. How to handle compiler bugs + 14.1.10. How to handle incrementing versions when fixing an existing package - 13.1.11. Portability of packages + 14.1.11. Portability of packages - 13.2. Possible downloading issues + 14.2. Possible downloading issues - 13.2.1. Packages whose distfiles aren't available for plain + 14.2.1. Packages whose distfiles aren't available for plain downloading - 13.2.2. How to handle modified distfiles with the 'old' name + 14.2.2. How to handle modified distfiles with the 'old' name - 13.3. Configuration gotchas + 14.3. Configuration gotchas - 13.3.1. Shared libraries - libtool - 13.3.2. Using libtool on GNU packages that already support libtool - 13.3.3. GNU Autoconf/Automake + 14.3.1. Shared libraries - libtool + 14.3.2. Using libtool on GNU packages that already support libtool + 14.3.3. GNU Autoconf/Automake - 13.4. Building considerations + 14.4. Building considerations - 13.4.1. CPP defines + 14.4.1. CPP defines - 13.5. Package specific actions + 14.5. Package specific actions - 13.5.1. Package configuration files - 13.5.2. User interaction - 13.5.3. Handling licenses - 13.5.4. Creating an account from a package - 13.5.5. Installing score files - 13.5.6. Packages providing login shells - 13.5.7. Packages containing perl scripts - 13.5.8. Packages with hardcoded paths to other interpreters - 13.5.9. Packages installing perl modules - 13.5.10. Packages installing info files - 13.5.11. Packages installing GConf2 data files - 13.5.12. Packages installing scrollkeeper data files - 13.5.13. Packages installing X11 fonts - 13.5.14. Packages installing GTK2 modules - 13.5.15. Packages installing SGML or XML data - 13.5.16. Packages installing extensions to the MIME database - 13.5.17. Packages using intltool - 13.5.18. Packages installing startup scripts + 14.5.1. User interaction + 14.5.2. Handling licenses + 14.5.3. Installing score files + 14.5.4. Packages containing perl scripts + 14.5.5. Packages with hardcoded paths to other interpreters + 14.5.6. Packages installing perl modules + 14.5.7. Packages installing info files + 14.5.8. Packages installing GConf2 data files + 14.5.9. Packages installing scrollkeeper data files + 14.5.10. Packages installing X11 fonts + 14.5.11. Packages installing GTK2 modules + 14.5.12. Packages installing SGML or XML data + 14.5.13. Packages installing extensions to the MIME database + 14.5.14. Packages using intltool + 14.5.15. Packages installing startup scripts - 13.6. Feedback to the author + 14.6. Feedback to the author - 14. Debugging - 15. Submitting and Committing + 15. Debugging + 16. Submitting and Committing - 15.1. Submitting your packages - 15.2. Committing: Importing a package into CVS - 15.3. Updating a package to a newer version - 15.4. Moving a package in pkgsrc + 16.1. Submitting your packages + 16.2. Committing: Importing a package into CVS + 16.3. Updating a package to a newer version + 16.4. Moving a package in pkgsrc A. A simple example package: bison @@ -461,7 +481,7 @@ Table of Contents 6.11. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? 6.12. What does "Could not find bsd.own.mk" mean? 6.13. Using 'sudo' with pkgsrc - 6.14. Configuration files handling and placement + 6.14. How do I change the location of configuration files? 6.15. Automated security checks Chapter 2. Where to get pkgsrc @@ -1182,12 +1202,12 @@ manipulate it. Binary packages are created by default in /usr/pkgsrc/packages, in the form of a gzipped tar file. See Section B.2, "Packaging figlet" for a continuation of the above misc/figlet example. -See Chapter 15, Submitting and Committing for information on how to submit such +See Chapter 16, Submitting and Committing for information on how to submit such a binary package. 5.2. Settings for creation of binary packages -See Section 12.3, "Other helpful targets". +See Section 13.3, "Other helpful targets". 5.3. Doing a bulk build of all packages @@ -1559,7 +1579,7 @@ Table of Contents 6.11. What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean? 6.12. What does "Could not find bsd.own.mk" mean? 6.13. Using 'sudo' with pkgsrc -6.14. Configuration files handling and placement +6.14. How do I change the location of configuration files? 6.15. Automated security checks This section contains hints, tips & tricks on special things in pkgsrc that we @@ -1812,67 +1832,25 @@ binary package or from security/sudo) and then put the following into your /etc SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c .endif -6.14. Configuration files handling and placement - -The global variable PKG_SYSCONFBASE (and some others) can be set by the system -administrator in /etc/mk.conf to define the place where configuration files get -installed. Therefore, packages must be adapted to support this feature. Keep in -mind that you should only install files that are strictly necessary in the -configuration directory, files that can go to $PREFIX/share should go there. - -We will take a look at available variables first (bsd.pkg.mk contains more -information). PKG_SYSCONFDIR is where the configuration files for a package may -be found (that is, the full path, e.g. /etc or /usr/pkg/etc). This value may be -customized in various ways: - - 1. PKG_SYSCONFBASE is the main config directory under which all package - configuration files are to be found. Users will typically want to set it to - /etc, or accept the default location of $PREFIX/etc. - - 2. PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which the - configuration files for a particular package may be found. Defaults to $ - {SYSCONFBASE}. - - 3. PKG_SYSCONFVAR is the special suffix used to distinguish any overriding - values for a particular package (see next item). It defaults to ${PKGBASE}, - but for a collection of related packages that should all have the same - PKG_SYSCONFDIR value, it can be set in each of the package Makefiles to a - common value. - - 4. PKG_SYSCONFDIR.${PKG_SYSCONFVAR} overrides the value of ${PKG_SYSCONFDIR} - for packages with the same value for PKG_SYSCONFVAR. - - As an example, all the various KDE packages may want to set PKG_SYSCONFVAR - to "kde" so admins can set PKG_SYSCONFDIR.kde in /etc/mk.conf to define - where to install KDE config files. - -Programs' configuration directory should be defined during the configure stage. -Packages that use GNU autoconf can usually do this by using the "--sysconfdir" -parameter, but this brings some problems as we will see now. When you change -this pathname in packages, you should not allow them to install files in that -directory directly. Instead they need to install those files under share/ -examples/${PKGNAME} so PLIST can register them. - -Once you have the required configuration files in place (under the share/ -examples directory) the variable CONF_FILES should be set to copy them into -PKG_SYSCONFDIR. The contents of this variable is formed by pairs of filenames; -the first element of the pair specifies the file inside the examples directory -(registered by PLIST) and the second element specifies the target file. This is -done this way to allow binary packages to place files in the right directory -using INSTALL/DEINSTALL scripts which are created automatically. The package -Makefile must also set USE_PKGINSTALL=YES to use these automatically generated -scripts. The automatic copying of config files can be toggled by setting the -environment variable PKG_CONFIG prior to package installation. - -Here is an example, taken from mail/mutt/Makefile: +6.14. How do I change the location of configuration files? -EGDIR= ${PREFIX}/share/doc/mutt/samples -CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc +As the system administrator, you can choose where configuration files are +installed. The default settings make all these files go into ${PREFIX}/etc or +some of its subdirectories; this may be suboptimal depending on your +expectations (e.g., a read-only, NFS-exported PREFIX with a need of per-machine +configuration of the provided packages). + +In order to change the defaults, you can modify the PKG_SYSCONFBASE variable +(in /etc/mk.conf) to point to your preferred configuration directory; some +common examples include /etc or /etc/pkg. + +Furthermore, you can change this value on a per-package basis by setting the +PKG_SYSCONFDIR.${PKG_SYSCONFVAR} variable. PKG_SYSCONFVAR's value usually +matches the name of the package you would like to modify, that is, the contents +of PKGBASE. -As you can see, this package installs configuration files inside EGDIR, which -are registered by PLIST. After that, the variable CONF_FILES lists the -installed file first and then the target file. Users will also get an automatic -message when files are installed using this method. +Note that, after changing these settings, you must rebuild and reinstall any +affected packages. 6.15. Automated security checks @@ -1952,79 +1930,99 @@ Table of Contents 10.3.1. Anatomy of a builtin.mk file 10.3.2. Global preferences for native or pkgsrc software -11. Options handling +11. The pkginstall framework + + 11.1. Files and directories outside the installation prefix + + 11.1.1. Directory manipulation + 11.1.2. File manipulation + + 11.2. Configuration files + + 11.2.1. How PKG_SYSCONFDIR is set + 11.2.2. Telling the software were configuration files are + 11.2.3. Patching installations + 11.2.4. Disabling handling of configuration files - 11.1. Global default options - 11.2. Converting packages to use bsd.options.mk + 11.3. System startup scripts -12. The build process + 11.3.1. Disabling handling of system startup scripts - 12.1. Program location - 12.2. Main targets - 12.3. Other helpful targets + 11.4. System users and groups + 11.5. System shells -13. Notes on fixes for packages + 11.5.1. Disabling handling of configuration files - 13.1. General operation +12. Options handling - 13.1.1. How to pull in variables from /etc/mk.conf - 13.1.2. Where to install documentation - 13.1.3. Restricted packages - 13.1.4. Handling dependencies - 13.1.5. Handling conflicts with other packages - 13.1.6. Packages that cannot or should not be built - 13.1.7. Packages which should not be deleted, once installed - 13.1.8. Handling packages with security problems - 13.1.9. How to handle compiler bugs - 13.1.10. How to handle incrementing versions when fixing an existing + 12.1. Global default options + 12.2. Converting packages to use bsd.options.mk + +13. The build process + + 13.1. Program location + 13.2. Main targets + 13.3. Other helpful targets + +14. Notes on fixes for packages + + 14.1. General operation + + 14.1.1. How to pull in variables from /etc/mk.conf + 14.1.2. Where to install documentation + 14.1.3. Restricted packages + 14.1.4. Handling dependencies + 14.1.5. Handling conflicts with other packages + 14.1.6. Packages that cannot or should not be built + 14.1.7. Packages which should not be deleted, once installed + 14.1.8. Handling packages with security problems + 14.1.9. How to handle compiler bugs + 14.1.10. How to handle incrementing versions when fixing an existing package - 13.1.11. Portability of packages + 14.1.11. Portability of packages - 13.2. Possible downloading issues + 14.2. Possible downloading issues - 13.2.1. Packages whose distfiles aren't available for plain downloading - 13.2.2. How to handle modified distfiles with the 'old' name + 14.2.1. Packages whose distfiles aren't available for plain downloading + 14.2.2. How to handle modified distfiles with the 'old' name - 13.3. Configuration gotchas + 14.3. Configuration gotchas - 13.3.1. Shared libraries - libtool - 13.3.2. Using libtool on GNU packages that already support libtool - 13.3.3. GNU Autoconf/Automake + 14.3.1. Shared libraries - libtool + 14.3.2. Using libtool on GNU packages that already support libtool + 14.3.3. GNU Autoconf/Automake - 13.4. Building considerations + 14.4. Building considerations - 13.4.1. CPP defines + 14.4.1. CPP defines - 13.5. Package specific actions + 14.5. Package specific actions - 13.5.1. Package configuration files - 13.5.2. User interaction - 13.5.3. Handling licenses - 13.5.4. Creating an account from a package - 13.5.5. Installing score files - 13.5.6. Packages providing login shells - 13.5.7. Packages containing perl scripts - 13.5.8. Packages with hardcoded paths to other interpreters - 13.5.9. Packages installing perl modules - 13.5.10. Packages installing info files - 13.5.11. Packages installing GConf2 data files - 13.5.12. Packages installing scrollkeeper data files - 13.5.13. Packages installing X11 fonts - 13.5.14. Packages installing GTK2 modules - 13.5.15. Packages installing SGML or XML data - 13.5.16. Packages installing extensions to the MIME database - 13.5.17. Packages using intltool - 13.5.18. Packages installing startup scripts + 14.5.1. User interaction + 14.5.2. Handling licenses + 14.5.3. Installing score files + 14.5.4. Packages containing perl scripts + 14.5.5. Packages with hardcoded paths to other interpreters + 14.5.6. Packages installing perl modules + 14.5.7. Packages installing info files + 14.5.8. Packages installing GConf2 data files + 14.5.9. Packages installing scrollkeeper data files + 14.5.10. Packages installing X11 fonts + 14.5.11. Packages installing GTK2 modules + 14.5.12. Packages installing SGML or XML data + 14.5.13. Packages installing extensions to the MIME database + 14.5.14. Packages using intltool + 14.5.15. Packages installing startup scripts - 13.6. Feedback to the author + 14.6. Feedback to the author -14. Debugging -15. Submitting and Committing +15. Debugging +16. Submitting and Committing - 15.1. Submitting your packages - 15.2. Committing: Importing a package into CVS - 15.3. Updating a package to a newer version - 15.4. Moving a package in pkgsrc + 16.1. Submitting your packages + 16.2. Committing: Importing a package into CVS + 16.3. Updating a package to a newer version + 16.4. Moving a package in pkgsrc Chapter 7. Package components - files, directories and contents @@ -2146,7 +2144,7 @@ Please pay attention to the following gotchas: * Replace /usr/local with "${PREFIX}" in all files (see patches, below). - * If the package installs any info files, see Section 13.5.10, "Packages + * If the package installs any info files, see Section 14.5.7, "Packages installing info files". * Set MAINTAINER to be yourself. If you really can't maintain the package for @@ -2581,7 +2579,7 @@ Be sure to add a RCS ID line as the first thing in any PLIST file you write: 9.2. Semi-automatic PLIST generation You can use the make print-PLIST command to output a PLIST that matches any new -files since the package was extracted. See Section 12.3, "Other helpful +files since the package was extracted. See Section 13.3, "Other helpful targets" for more information on this target. 9.3. Tweaking output of make print-PLIST @@ -2960,7 +2958,7 @@ libraries. Please take careful consideration before adjusting BUILDLINK_DEPENDS.pkg as we don't want to cause unneeded package deletions and rebuilds. In many cases, new versions of packages work just fine with older dependencies. See Section -13.1.4, "Handling dependencies" and Chapter 10, Buildlink methodology for more +14.1.4, "Handling dependencies" and Chapter 10, Buildlink methodology for more information about dependencies on other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED definitions. @@ -3072,12 +3070,320 @@ all but the most basic bits on a NetBSD system, you can set: A package must have a builtin.mk file to be listed in PREFER_NATIVE, otherwise it is simply ignored in that list. -Chapter 11. Options handling +Chapter 11. The pkginstall framework Table of Contents -11.1. Global default options -11.2. Converting packages to use bsd.options.mk +11.1. Files and directories outside the installation prefix + + 11.1.1. Directory manipulation + 11.1.2. File manipulation + +11.2. Configuration files + + 11.2.1. How PKG_SYSCONFDIR is set + 11.2.2. Telling the software were configuration files are + 11.2.3. Patching installations + 11.2.4. Disabling handling of configuration files + +11.3. System startup scripts + + 11.3.1. Disabling handling of system startup scripts + +11.4. System users and groups +11.5. System shells + + 11.5.1. Disabling handling of configuration files + +This chapter describes the framework known as pkginstall, whose key features +are: + + * Generic installation and manipulation of directories and files outside the + pkgsrc-handled tree, LOCALBASE. + + * Automatic handling of configuration files during installation, provided + that packages are correctly designed. + + * Generation and installation of system startup scripts. + + * Registration of system users and groups. + + * Registration of system shells. + +The following sections inspect each of the above points in detail. Note that, +in order to use any of the described functionalities, you must add the +following to your package's Makefile: + +USE_PKGINSTALL=YES + +You may be thinking that many of the things described here could be easily done +with simple code in the package's post-installation target (post-install). This +is incorrect, as the code in them is only executed when building from source. +Machines using binary packages could not benefit from it at all (as the code +itself could be unavailable). Therefore, the only way to achieve any of the +items described above is by means of the installation scripts, which are +automatically generated by pkginstall. + +11.1. Files and directories outside the installation prefix + +As you already know, the PLIST file holds a list of files and directories that +belong to a package. The names used in it are relative to the installation +prefix (${PREFIX}), which means that it cannot register files outside this +directory (absolute path names are not allowed). Despite this restriction, some +packages need to install files outside this location; e.g., under ${VARBASE} or +${PKG_SYSCONFDIR}. + +The only way to achieve this is to create such files during installation time +by using the installation scripts. These scripts can run arbitrary commands, so +they have the potential to create and manage files anywhere in the filesystem. +Here is where pkginstall comes into play: it provides generic scripts to +abstract the manipulation of such files and directories based on variables set +in the package's Makefile. The rest of this section describes which these +variables are. + +11.1.1. Directory manipulation + +The following variables can be set to request the creation of directories +anywhere in the filesystem: + + * MAKE_DIRS and OWN_DIRS contain a list of directories that should be created + and should attempt to be destroyed by the installation scripts. The + difference between the two is that the latter prompts the administrator to + remove any directories that may be left after deinstallation (because they + were not empty), while the former does not. + + * MAKE_DIRS_PERMS and OWN_DIRS_PERMS contain a list of tuples describing + which directories should be created and should attempt to be destroyed by + the installation scripts. Each tuple holds the following values, separated + by spaces: the directory name, its owner, its group and its numerical mode. + For example: + + MAKE_DIRS_PERMS+= ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700 + + The difference between the two is exactly the same as their non-PERMS + counterparts. + +11.1.2. File manipulation + +Creating non-empty files outside the installation prefix is tricky because the +PLIST forces all files to be inside it. To overcome this problem, the only +solution is to extract the file in the known place (i.e., inside the +installation prefix) and copy it to the appropriate location during +installation (done by the installation scripts generated by pkginstall). We +will call the former the master file in the following paragraphs, which +describe the variables that can be used to automatically and consistently +handle files outside the installation prefix: + + * CONF_FILES and SUPPORT_FILES are pairs of master and target files. During + installation time, the master file is copied to the target one if and only + if the latter does not exist. Upon deinstallation, the target file is + removed provided that it was not modified by the installation. + + The difference between the two is that the latter prompts the administrator + to remove any files that may be left after deinstallation (because they + were not empty), while the former does not. + + * CONF_FILES_PERMS and SUPPORT_FILES_PERMS contain tuples describing master + files as well as their target locations. For each of them, it also + specifies their owner, their group and their numeric permissions, in this + order. For example: + + SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700 + + The difference between the two is exactly the same as their non-PERMS + counterparts. + +11.2. Configuration files + +Configuration files are special in the sense that they are installed in their +own specific directory, PKG_SYSCONFDIR, and need special treatment during +installation (most of which is automated by pkginstall). The main concept you +must bear in mind is that files marked as a configuration are automatically +copied to the right place (somewhere inside PKG_SYSCONFDIR) during installation +if and only if they didn't exist before. Similarly, they will not be removed if +they have local modifications. This ensures that administrators never loose any +custom changes they may have made. + +11.2.1. How PKG_SYSCONFDIR is set + +As said before, the PKG_SYSCONFDIR variable specifies where configuration files +shall be installed. Its contents are set based upon the following variables: + + * PKG_SYSCONFBASE: The configuration's root directory. Defaults to ${PREFIX}/ + etc although may be overridden by the user to point to his preferred + location (e.g., /etc, /etc/pkg, etc.). Packages must not use it directly. + + * PKG_SYSCONFSUBDIR: A subdirectory of PKG_SYSCONFBASE under which the + configuration files for the package being built shall be installed. The + definition of this variable only makes sense in the package's Makefile + (i.e., it is not user customizable). + + As an example, consider the Apache package, www/apache2, which places its + configuration files under the httpd/ subdirectory of PKG_SYSCONFBASE. This + should be set in the package Makefile. + + * PKG_SYSCONFVAR: Specifies the name of the variable that holds this + package's configuration directory (if different from PKG_SYSCONFBASE). It + defaults to PKGBASE's value, and is always prefixed with PKG_SYSCONFDIR. + + * PKG_SYSCONFDIR.${PKG_SYSCONFVAR}: Holds the directory where the + configuration files for the package identified by PKG_SYSCONFVAR's shall be + placed. + +Based on the above variables, pkginstall determines the value of +PKG_SYSCONFDIR, which is the only variable that can be used within a package to +refer to its configuration directory. The algorithm used to set its value is +basically the following: + + 1. If PKG_SYSCONFDIR.${PKG_SYSCONFVAR} is set, its value is used. + + 2. If the previous variable is not defined but PKG_SYSCONFSUBDIR is set in the + package's Makefile, the resulting value is ${PKG_SYSCONFBASE}/$ + {PKG_SYSCONFSUBDIR}. + + 3. Otherwise, it is set to ${PKG_SYSCONFBASE}. + +It is worth mentioning that ${PKG_SYSCONFDIR} is automatically added to +OWN_DIRS. See Section 11.1.1, "Directory manipulation" what this means. + +11.2.2. Telling the software were configuration files are + +Given that pkgsrc (and users!) expect configuration files to be in a known +place, you need to teach each package where shall it install its files. In some +cases you will have to patch the package Makefiles to achieve it. If you are +lucky, though, it may be as easy as passing an extra flag to the configuration +script; this is the case of GNU Autoconf generated files: + +CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR} + +Note that this specifies where the package has to look for its configuration +files, not where they will be originally installed (although the difference is +never explicit, unfortunately). + +11.2.3. Patching installations + +As said before, pkginstall automatically handles configuration files. This +means that the packages themselves must not touch the contents of $ +{PKG_SYSCONFDIR} directly. Bad news is that the software they build will, out +of the box, mess with the contents of that directory. So which is the correct +procedure to fix this issue? + +You must teach the package (usually by manually patching it) to install any +configuration files under the examples hierarchy, share/examples/${PKGBASE}/. +This way, the PLIST registers them and the administrator always has the +original copies available. + +Once the required configuration files are in place (i.e., under the examples +hierarchy), the pkginstall framework can use them as master copies during the +package installation to update what is in ${PKG_SYSCONFDIR}. To achieve this, +the variables CONF_FILES and CONF_FILES_PERMS are used. Check out Section +11.1.2, "File manipulation" for information about their syntax and their +purpose. Here is an example, taken from the mail/mutt package: + +EGDIR= ${PREFIX}/share/doc/mutt/samples +CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc + +Note that the EGDIR variable is specific to that package and has no meaning +outside it. + +11.2.4. Disabling handling of configuration files + +The automatic copying of config files can be toggled by setting the environment +variable PKG_CONFIG prior to package installation. + +11.3. System startup scripts + +System startup scripts are special files because they must be installed in a +place known by the underlying OS, usually outside the installation prefix. +Therefore, the same rules described in Section 11.1, "Files and directories +outside the installation prefix" apply, and the same solutions can be used. +However, pkginstall provides a specific mechanism to handle these files, given +that they are special. + +In order to provide system startup scripts, the package has to: + + 1. Store the script inside ${FILESDIR}, with the .sh suffix appended. + Considering the print/cups package as an example, it has the cupsd.sh in + its files directory. + + 2. Tell pkginstall to handle it, appending the name of the script, without its + extension, to the RCD_SCRIPTS variable. Continuing the previous example: + + RCD_SCRIPTS+= cupsd + + +Once this is done, pkginstall will do the following steps for each script in an +automated fashion: + + 1. Process the file found in the files directory applying all the + substitutions described in the FILES_SUBST variable. + + 2. Copy the script from the files directory to the examples hierarchy, $ + {PREFIX}/share/examples/rc.d/. Note that the master file must be explicitly + registered in the PLIST. + + 3. Add code to the installation scripts to copy the startup script from the + examples hierarchy into the system-wide startup scripts directory. + +11.3.1. Disabling handling of system startup scripts + +The automatic copying of config files can be toggled by setting the environment +variable PKG_RCD_SCRIPTS prior to package installation. Note that the scripts +will be always copied inside the examples hierarchy, ${PREFIX}/share/examples/ +rc.d/, no matter what the value of this variable is. + +11.4. System users and groups + +If a package needs to create special users and/or groups during installation, +it can do so by using the pkginstall framework. + +Users can be created by adding entries to the PKG_USERS variable. Each entry +has the following syntax, which mimics /etc/passwd: + +user:group[:[userid][:[descr][:[home][:shell]]]] + +Only the user and group are required; everything else is optional, but the +colons must be in the right places when specifying optional bits. By default, a +new user will have home directory /nonexistent, and login shell /sbin/nologin +unless they are specified as part of the user element. Note that if the +description contains spaces, then spaces should be double backslash-escaped, as +in: + +foo:foogrp::The\\ Foomister + +Similarly, groups can be created using the PKG_GROUPS variable, whose syntax +is: + +group[:groupid] + +As before, only the group name is required; the numeric identifier is optional. + +11.5. System shells + +Packages that install system shells should register them in the shell database, +/etc/shells, to make things easier to the administrator. This must be done from +the installation scripts to keep binary packages working on any system. +pkginstall provides an easy way to accomplish this task. + +When a package provides a shell interpreter, it has to set the PKG_SHELL +variable to its absolute file name. This will add some hooks to the +installation scripts to handle it. Consider the following example, taken from +shells/zsh: + +USE_PKGINSTALL= YES +PKG_SHELL= ${PREFIX}/bin/zsh + +11.5.1. Disabling handling of configuration files + +The automatic registration of shell interpreters can be disabled by the +administrator by setting the PKG_REGISTER_SHELLS environment variable to NO. + +Chapter 12. Options handling + +Table of Contents + +12.1. Global default options +12.2. Converting packages to use bsd.options.mk Many packages have the ability to be built to support different sets of features. bsd.options.mk is a framework in pkgsrc that provides generic @@ -3086,13 +3392,13 @@ can be built. It's possible for the user to specify exactly which sets of options will be built into a package or to allow a set of global default options apply. -11.1. Global default options +12.1. Global default options Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of the options that should be built into every package if that option is supported. This variable should be set in /etc/mk.conf. -11.2. Converting packages to use bsd.options.mk +12.2. Converting packages to use bsd.options.mk The following example shows how bsd.options.mk should be used by the hypothetical ``wibble'' package, either in the package Makefile, or in a file, @@ -3174,13 +3480,13 @@ should be clear documentation on what turning on the option will do in the comments preceding each section. The correct way to check for an option is to check whether it is listed in PKG_OPTIONS. -Chapter 12. The build process +Chapter 13. The build process Table of Contents -12.1. Program location -12.2. Main targets -12.3. Other helpful targets +13.1. Program location +13.2. Main targets +13.3. Other helpful targets The basic steps for building a program are always the same. First the program's source (distfile) must be brought to the local system and then extracted. After @@ -3190,7 +3496,7 @@ binaries, etc. can be put into place on the system. These are exactly the steps performed by the NetBSD package system, which is implemented as a series of targets in a central Makefile, pkgsrc/mk/bsd.pkg.mk. -12.1. Program location +13.1. Program location Before outlining the process performed by the NetBSD package system in the next section, here's a brief discussion on where programs are installed, and which @@ -3200,7 +3506,7 @@ The automatic variable PREFIX indicates where all files of the final program shall be installed. It is usually set to LOCALBASE (/usr/pkg), or CROSSBASE for pkgs in the "cross" category. The value of PREFIX needs to be put into the various places in the program's source where paths to these files are encoded. -See Section 7.3, "patches/*" and Section 13.3.1, "Shared libraries - libtool" +See Section 7.3, "patches/*" and Section 14.3.1, "Shared libraries - libtool" for more details. When choosing which of these variables to use, follow the following rules: @@ -3265,7 +3571,7 @@ When choosing which of these variables to use, follow the following rules: the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/ man. -12.2. Main targets +13.2. Main targets The main targets used during the build process defined in bsd.pkg.mk are: @@ -3384,7 +3690,7 @@ make patch make configure make build -12.3. Other helpful targets +13.3. Other helpful targets pre/post-* @@ -3620,66 +3926,63 @@ bulk-install Beware that this target may deinstall all packages installed on a system! -Chapter 13. Notes on fixes for packages +Chapter 14. Notes on fixes for packages Table of Contents -13.1. General operation - - 13.1.1. How to pull in variables from /etc/mk.conf - 13.1.2. Where to install documentation - 13.1.3. Restricted packages - 13.1.4. Handling dependencies - 13.1.5. Handling conflicts with other packages - 13.1.6. Packages that cannot or should not be built - 13.1.7. Packages which should not be deleted, once installed - 13.1.8. Handling packages with security problems - 13.1.9. How to handle compiler bugs - 13.1.10. How to handle incrementing versions when fixing an existing +14.1. General operation + + 14.1.1. How to pull in variables from /etc/mk.conf + 14.1.2. Where to install documentation + 14.1.3. Restricted packages + 14.1.4. Handling dependencies + 14.1.5. Handling conflicts with other packages + 14.1.6. Packages that cannot or should not be built + 14.1.7. Packages which should not be deleted, once installed + 14.1.8. Handling packages with security problems + 14.1.9. How to handle compiler bugs + 14.1.10. How to handle incrementing versions when fixing an existing package - 13.1.11. Portability of packages + 14.1.11. Portability of packages -13.2. Possible downloading issues +14.2. Possible downloading issues - 13.2.1. Packages whose distfiles aren't available for plain downloading - 13.2.2. How to handle modified distfiles with the 'old' name + 14.2.1. Packages whose distfiles aren't available for plain downloading + 14.2.2. How to handle modified distfiles with the 'old' name -13.3. Configuration gotchas +14.3. Configuration gotchas - 13.3.1. Shared libraries - libtool - 13.3.2. Using libtool on GNU packages that already support libtool - 13.3.3. GNU Autoconf/Automake + 14.3.1. Shared libraries - libtool + 14.3.2. Using libtool on GNU packages that already support libtool + 14.3.3. GNU Autoconf/Automake -13.4. Building considerations +14.4. Building considerations - 13.4.1. CPP defines + 14.4.1. CPP defines -13.5. Package specific actions +14.5. Package specific actions - 13.5.1. Package configuration files - 13.5.2. User interaction - 13.5.3. Handling licenses - 13.5.4. Creating an account from a package - 13.5.5. Installing score files - 13.5.6. Packages providing login shells - 13.5.7. Packages containing perl scripts - 13.5.8. Packages with hardcoded paths to other interpreters - 13.5.9. Packages installing perl modules - 13.5.10. Packages installing info files - 13.5.11. Packages installing GConf2 data files - 13.5.12. Packages installing scrollkeeper data files - 13.5.13. Packages installing X11 fonts - 13.5.14. Packages installing GTK2 modules - 13.5.15. Packages installing SGML or XML data - 13.5.16. Packages installing extensions to the MIME database - 13.5.17. Packages using intltool - 13.5.18. Packages installing startup scripts + 14.5.1. User interaction + 14.5.2. Handling licenses + 14.5.3. Installing score files + 14.5.4. Packages containing perl scripts + 14.5.5. Packages with hardcoded paths to other interpreters + 14.5.6. Packages installing perl modules + 14.5.7. Packages installing info files + 14.5.8. Packages installing GConf2 data files + 14.5.9. Packages installing scrollkeeper data files + 14.5.10. Packages installing X11 fonts + 14.5.11. Packages installing GTK2 modules + 14.5.12. Packages installing SGML or XML data + 14.5.13. Packages installing extensions to the MIME database + 14.5.14. Packages using intltool + 14.5.15. Packages installing startup scripts -13.6. Feedback to the author +14.6. Feedback to the author -13.1. General operation +14.1. General operation -13.1.1. How to pull in variables from /etc/mk.conf +14.1.1. How to pull in variables from /etc/mk.conf The problem with package-defined variables that can be overridden via MAKECONF or /etc/mk.conf is that make(1) expands a variable as it is used, but evaluates @@ -3706,13 +4009,13 @@ Using CFLAGS= (i.e. without the "+") may lead to problems with packages that need to add their own flags. Also, you may want to take a look at the devel/ cpuflags package if you're interested in optimization for the current CPU. -13.1.2. Where to install documentation +14.1.2. Where to install documentation Documentation should be installed into ${PREFIX}/share/doc/${PKGBASE} or $ {PREFIX}/share/doc/${PKGNAME} (the latter includes the version number of the package). -13.1.3. Restricted packages +14.1.3. Restricted packages Some licenses restrict how software may be re-distributed. In order to satisfy these restrictions, the package system defines five make variables that can be @@ -3751,7 +4054,7 @@ Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic make variables to denote restrictions is deprecated, because they unconditionally prevent users from generating binary packages! -13.1.4. Handling dependencies +14.1.4. Handling dependencies Your package may depend on some other package being present - and there are various ways of expressing this dependency. pkgsrc supports the BUILD_DEPENDS @@ -3831,7 +4134,7 @@ version numbers recognized by pkg_info(1). different versions of binary packages installed. For security fixes, please update the package vulnerabilities file as well - as setting RECOMMENDED, see Section 13.1.8, "Handling packages with + as setting RECOMMENDED, see Section 14.1.8, "Handling packages with security problems" for more information. 4. If your package needs some executable to be able to run correctly and if @@ -3866,7 +4169,7 @@ gettext package. The latter adds a build dependency on either an installed version of an older gettext package, or if it isn't, installs the devel/ gettext-m4 package. -13.1.5. Handling conflicts with other packages +14.1.5. Handling conflicts with other packages Your package may conflict with other packages a user might already have installed on his system, e.g. if your package installs the same set of files @@ -3888,7 +4191,7 @@ Packages will automatically conflict with other packages with the name prefix and a different version string. "Xaw3d-1.5" e.g. will automatically conflict with the older version "Xaw3d-1.3". -13.1.6. Packages that cannot or should not be built +14.1.6. Packages that cannot or should not be built There are several reasons why a package might be instructed to not build under certain circumstances. If the package builds and runs on most platforms, the @@ -3902,7 +4205,7 @@ PKG_FAIL_REASON to a descriptive message. IGNORE is deprecated because it didn't provide enough information to determine whether the build should fail. -13.1.7. Packages which should not be deleted, once installed +14.1.7. Packages which should not be deleted, once installed To ensure that a package may not be deleted, once it has been installed, the PKG_PRESERVE definition should be set in the package Makefile. This will be @@ -3910,7 +4213,7 @@ carried into any binary package that is made from this pkgsrc entry. A "preserved" package will not be deleted using pkg_delete(1) unless the "-f" option is used. -13.1.8. Handling packages with security problems +14.1.8. Handling packages with security problems When a vulnerability is found, this should be noted in localsrc/security/ advisories/pkg-vulnerabilities, and after the commit of that file, it should be @@ -3925,7 +4228,7 @@ BUILDLINK_* definitions. Also, if the fix should be applied to the stable pkgsrc branch, be sure to submit a pullup request! -13.1.9. How to handle compiler bugs +14.1.9. How to handle compiler bugs Some source files trigger bugs in the compiler, based on combinations of compiler version and architecture and almost always relation to optimisation @@ -3936,7 +4239,7 @@ Typically a workaround involves testing the MACHINE_ARCH and compiler version, disabling optimisation for that file/MACHINE_ARCH/compiler combination, and documenting it in pkgsrc/doc/HACKS. See that file for a number of examples! -13.1.10. How to handle incrementing versions when fixing an existing package +14.1.10. How to handle incrementing versions when fixing an existing package When making fixes to an existing package it can be useful to change the version number in PKGNAME. To avoid conflicting with future versions by the original @@ -3954,14 +4257,14 @@ like: DISTNAME= foo-17.43 -13.1.11. Portability of packages +14.1.11. Portability of packages One appealing feature of pkgsrc is that it runs on many different platforms. As a result, it is important to ensure, where possible, that packages in pkgsrc are portable. There are some particular details you should pay attention to while working on pkgsrc. -13.1.11.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ... +14.1.11.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ... The BSD-compatible install supplied with some operating systems will not perform more than one operation at a time. As such, you should call "${INSTALL} @@ -3970,9 +4273,9 @@ perform more than one operation at a time. As such, you should call "${INSTALL} ${INSTALL_DATA_DIR} ${PREFIX}/dir1 ${INSTALL_DATA_DIR} ${PREFIX}/dir2 -13.2. Possible downloading issues +14.2. Possible downloading issues -13.2.1. Packages whose distfiles aren't available for plain downloading +14.2.1. Packages whose distfiles aren't available for plain downloading If you need to download from a dynamic URL you can set DYNAMIC_MASTER_SITES and a make fetch will call files/getsite.sh with the name of each file to download @@ -3988,7 +4291,7 @@ packages use this: audio/realplayer, cad/simian, devel/ipv6socket, emulators/ vmware-module, fonts/acroread-jpnfont, sysutils/storage-manager, www/ ap-aolserver, www/openacs. Try to be consistent with them. -13.2.2. How to handle modified distfiles with the 'old' name +14.2.2. How to handle modified distfiles with the 'old' name Sometimes authors of a software package make some modifications after the software was released, and they put up a new distfile without changing the @@ -4005,9 +4308,9 @@ filenames. Furthermore, a mail to the package's authors seems appropriate telling them that changing distfiles after releases without changing the file names is not good practice. -13.3. Configuration gotchas +14.3. Configuration gotchas -13.3.1. Shared libraries - libtool +14.3.1. Shared libraries - libtool pkgsrc supports many different machines, with different object formats like a.out and ELF, and varying abilities to do shared library and dynamic loading @@ -4101,7 +4404,7 @@ Here's how to use libtool in a pkg in seven simple steps: 7. In your PLIST, include only the .la file (this is a change from previous behaviour). -13.3.2. Using libtool on GNU packages that already support libtool +14.3.2. Using libtool on GNU packages that already support libtool Add USE_LIBTOOL=yes to the package Makefile. This will override the package's own libtool in most cases. For older libtool using packages, libtool is made by @@ -4135,42 +4438,37 @@ in some circumstances. Some of the more common errors are: The function lt_dlinit() should be called and the macro LTDL_SET_PRELOADED_SYMBOLS included in executables. -13.3.3. GNU Autoconf/Automake +14.3.3. GNU Autoconf/Automake If a package needs GNU autoconf or automake to be executed to regenerate the configure script and Makefile.in makefile templates, then they should be -executed in a pre-configure target. Two Makefile fragments are provided in -pkgsrc/mk/autoconf.mk and pkgsrc/mk/automake.mk to help dealing with these -tools. See comments in these files for details. +executed in a pre-configure target. For packages that need only autoconf: -AUTOCONF_REQD= 2.50 # if default version is not good enough +AUTOCONF_REQD= 2.50 # if default version is not good enough +USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 ... pre-configure: - cd ${WRKSRC}; ${AUTOCONF} + cd ${WRKSRC}; autoconf ... -.include "../../mk/autoconf.mk" and for packages that need automake and autoconf: -AUTOMAKE_REQD= 1.7.1 # if default version is not good enough +AUTOMAKE_REQD= 1.7.1 # if default version is not good enough +USE_TOOLS+= automake # use "automake14" for autoconf-1.4 ... pre-configure: cd ${WRKSRC}; \ - ${ACLOCAL}; \ - ${AUTOHEADER}; \ - ${AUTOMAKE} -a --foreign -i; \ - ${AUTOCONF} + aclocal; autoheader; \ + automake -a --foreign -i; autoconf ... -.include "../mk/automake.mk" -Packages which use GNU Automake will almost certainly require GNU Make, but -that's automatically provided for you in mk/automake.mk. +Packages which use GNU Automake will almost certainly require GNU Make. There are times when the configure process makes additional changes to the generated files, which then causes the build process to try to re-execute the @@ -4178,9 +4476,9 @@ automake sequence. This is prevented by touching various files in the configure stage. If this causes problems with your package you can set AUTOMAKE_OVERRIDE= NO in the package Makefile. -13.4. Building considerations +14.4. Building considerations -13.4.1. CPP defines +14.4.1. CPP defines To port an application to NetBSD, it's usually necessary for the compiler to be able to judge the system on which it's compiling, and we use definitions so @@ -4201,36 +4499,9 @@ using this conditional: Please use the "__NetBSD__" definition sparingly - it should only apply to features of NetBSD that are not present in other 4.4-lite derived BSDs. -13.5. Package specific actions - -13.5.1. Package configuration files - -Packages should be taught to look for their configuration files in $ -{PKG_SYSCONFDIR}, which is passed through to the configure and build processes. -PKG_SYSCONFDIR may be customized in various ways by setting other make -variables: - - * PKG_SYSCONFBASE is the main config directory under which all package - configuration files are to be found. This defaults to ${PREFIX}/etc, but - may be overridden in /etc/mk.conf. - - * PKG_SYSCONFSUBDIR is the subdirectory of PKG_SYSCONFBASE under which the - configuration files for a particular package may be found, e.g. the Apache - configuration files may all be found under the httpd/ subdirectory of $ - {PKG_SYSCONFBASE}. This should be set in the package Makefile. +14.5. Package specific actions - * By default, PKG_SYSCONFDIR is set to ${PKG_SYSCONFBASE}/$ - {PKG_SYSCONFSUBDIR}, but this may be overridden by setting PKG_SYSCONFDIR.$ - {PKG_SYSCONFVAR} for a particular package, where PKG_SYSCONFVAR defaults to - ${PKGBASE}. This is not meant to be set by a package Makefile, but is - reserved for users who wish to override the PKG_SYSCONFDIR setting for a - particular package with a special location. - -The only variables that users should customize are PKG_SYSCONFBASE and -PKG_SYSCONFDIR.${PKG_SYSCONFVAR}. Users will typically want to set -PKG_SYSCONFBASE to /etc, or to accept the default location of ${PREFIX}/etc. - -13.5.2. User interaction +14.5.1. User interaction Occasionally, packages require interaction from the user, and this can be in a number of ways: @@ -4253,7 +4524,7 @@ Multiple interactive stages can be specified: INTERACTIVE_STAGE= configure install -13.5.3. Handling licenses +14.5.2. Handling licenses A package may underly a license which the user has or has not agreed to accept. Usually, packages that underly well-known Open Source licenses (e.g. the GNU @@ -4294,37 +4565,7 @@ If there is a really pressing need to accept all licenses at once, like when trying to download or mirror all distfiles or doing a bulk build to test if all packages in pkgsrc build, this can be done by setting _ACCEPTABLE=yes. -13.5.4. Creating an account from a package - -There are two make variables used to control the creation of package-specific -groups and users at pre-install time. The first is PKG_GROUPS, which is a list -of group[:groupid] elements, where the groupid is optional. The second is -PKG_USERS, which is a list of elements of the form: - -user:group[:[userid][:[description][:[home][:shell]]]] - -where only the user and group are required, the rest being optional. A simple -example is: - - PKG_GROUPS= foogroup - PKG_USERS= foouser:foogroup - -A more complex example is that creates two groups and two users is: - - PKG_GROUPS= group1 group2:1005 - PKG_USERS= first:group1::First\\ User \ - second:group2::Second\\ User:/home/second:${SH} - -By default, a new user will have home directory /nonexistent, and login shell / -sbin/nologin unless they are specified as part of the user element. - -The package Makefile must also set USE_PKGINSTALL=YES. This will cause the -users and groups to be created at pre-install time, and the admin will be -prompted to remove them at post-deinstall time. Automatic creation of the users -and groups can be toggled on and off by setting the PKG_CREATE_USERGROUP -variable prior to package installation. - -13.5.5. Installing score files +14.5.3. Installing score files Certain packages, most of them in the games category, install a score file that allows all users on the system to record their highscores. In order for this to @@ -4339,29 +4580,13 @@ SETGIDGAME=YES will set all the other variables accordingly. A package should therefor never hard code file ownership or access permissions but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly. -13.5.6. Packages providing login shells - -If the purpose of the package is to provide a login shell, the variable -PKG_SHELL should contain the full pathname of the shell executable installed by -this package. The package Makefile must also set USE_PKGINSTALL=YES to use the -automatically generated INSTALL/DEINSTALL scripts. - -An example taken from shells/zsh: - - USE_PKGINSTALL= YES - PKG_SHELL= ${PREFIX}/bin/zsh - -The shell is registered into /etc/shells file automatically in the post-install -target by the generated INSTALL script and removed in the deinstall target by -the DEINSTALL script. - -13.5.7. Packages containing perl scripts +14.5.4. Packages containing perl scripts If your package contains interpreted perl scripts, set REPLACE_PERL to ensure that the proper interpreter path is set. REPLACE_PERL should contain a list of scripts, relative to WRKSRC, that you want adjusted. -13.5.8. Packages with hardcoded paths to other interpreters +14.5.5. Packages with hardcoded paths to other interpreters Your package may also contain scripts with hardcoded paths to other interpreters besides (or as well as) perl. To correct the full pathname to the @@ -4374,7 +4599,7 @@ script interpreter, you need to set the following definitions in your Makefile _REPLACE_FILES.tcl= ...list of tcl scripts which need to be fixed, relative to ${WRKSRC}, just as in REPLACE_PERL -13.5.9. Packages installing perl modules +14.5.6. Packages installing perl modules Makefiles of packages providing perl5 modules should include the Makefile fragment ../../lang/perl5/module.mk. It provides a do-configure target for the @@ -4394,7 +4619,7 @@ three locations in which perl5 modules may be installed, and may be used by perl5 packages that don't have a packlist. These three variables are also substituted for in the PLIST. -13.5.10. Packages installing info files +14.5.7. Packages installing info files Some packages install info files or use the "makeinfo" or "install-info" commands. Each of the info files: @@ -4433,7 +4658,7 @@ message. The script overriding makeinfo logs a message and according to the value of USE_MAKEINFO and TEXINFO_REQD either run the appropriate makeinfo command or exit on error. -13.5.11. Packages installing GConf2 data files +14.5.8. Packages installing GConf2 data files If a package installs .schemas or .entries files, used by GConf2, you need to take some extra steps to make sure they get registered in the database: @@ -4449,8 +4674,8 @@ take some extra steps to make sure they get registered in the database: manually patch the package. 3. Check the PLIST and remove any entries under the etc/gconf directory, as - they will be handled automatically. See Section 6.14, "Configuration files - handling and placement" for more information. + they will be handled automatically. See Section 6.14, "How do I change the + location of configuration files?" for more information. 4. Define the GCONF2_SCHEMAS variable in your Makefile with a list of all .schemas files installed by the package, if any. Names must not contain any @@ -4460,7 +4685,7 @@ take some extra steps to make sure they get registered in the database: .entries files installed by the package, if any. Names must not contain any directories in them. -13.5.12. Packages installing scrollkeeper data files +14.5.9. Packages installing scrollkeeper data files If a package installs .omf files, used by scrollkeeper, you need to take some extra steps to make sure they get registered in the database: @@ -4476,7 +4701,7 @@ extra steps to make sure they get registered in the database: 3. Remove the share/omf directory from the PLIST. It will be handled by scrollkeeper. -13.5.13. Packages installing X11 fonts +14.5.10. Packages installing X11 fonts If a package installs font files, you will need to rebuild the fonts database in the directory where they get installed at installation and deinstallation @@ -4492,7 +4717,7 @@ Note that you should not create new directories for fonts; instead use the standard ones to avoid that the user needs to manually configure his X server to find them. -13.5.14. Packages installing GTK2 modules +14.5.11. Packages installing GTK2 modules If a package installs gtk2 immodules or loaders, you need to take some extra steps to get them registered in the GTK2 database properly: @@ -4515,7 +4740,7 @@ steps to get them registered in the GTK2 database properly: 5. Check the PLIST and remove any entries under the libdata/gtk-2.0 directory, as they will be handled automatically. -13.5.15. Packages installing SGML or XML data +14.5.12. Packages installing SGML or XML data If a package installs SGML or XML data files that need to be registered in system-wide catalogs (like DTDs, sub-catalogs, etc.), you need to take some @@ -4541,7 +4766,7 @@ extra steps: (specifically, arguments recognized by the 'add' action). Note that you will normally not use this variable. -13.5.16. Packages installing extensions to the MIME database +14.5.13. Packages installing extensions to the MIME database If a package provides extensions to the MIME database by installing .xml files inside ${PREFIX}/share/mime/packages, you need to take some extra steps to @@ -4562,7 +4787,7 @@ ensure that the database is kept consistent with respect to these new files: 3. Remove any share/mime/* directories from the PLIST. They will be handled by the shared-mime-info package. -13.5.17. Packages using intltool +14.5.14. Packages using intltool If a package uses intltool during its build, include the ../../textproc/ intltool/buildlink3.mk file, which forces it to use the intltool package @@ -4572,7 +4797,7 @@ This tracks intltool's build-time dependencies and uses the latest available version; this way, the package benefits of any bug fixes that may have appeared since it was released. -13.5.18. Packages installing startup scripts +14.5.15. Packages installing startup scripts If a package contains a rc.d script, it won't be copied into the startup directory by default, but you can enable it, by adding the option @@ -4580,7 +4805,7 @@ PKG_RCD_SCRIPTS=YES in /etc/mk.conf. This option will copy the scripts into / etc/rc.d when a package is installed, and it will automatically remove the scripts when the package is deinstalled. -13.6. Feedback to the author +14.6. Feedback to the author If you have found any bugs in the package you make available, if you had to do special steps to make it run under NetBSD or if you enhanced the software in @@ -4591,7 +4816,7 @@ win from your efforts. Support the idea of free software! -Chapter 14. Debugging +Chapter 15. Debugging To check out all the gotchas when building a package, here are the steps that I do in order to get a package working. Please note this is basically the same as @@ -4670,19 +4895,19 @@ what was explained in the previous sections, only with some debugging aids. # pkglint - * Submit (or commit, if you have cvs access); see Chapter 15, Submitting and + * Submit (or commit, if you have cvs access); see Chapter 16, Submitting and Committing. -Chapter 15. Submitting and Committing +Chapter 16. Submitting and Committing Table of Contents -15.1. Submitting your packages -15.2. Committing: Importing a package into CVS -15.3. Updating a package to a newer version -15.4. Moving a package in pkgsrc +16.1. Submitting your packages +16.2. Committing: Importing a package into CVS +16.3. Updating a package to a newer version +16.4. Moving a package in pkgsrc -15.1. Submitting your packages +16.1. Submitting your packages You have to separate between binary and "normal" (source) packages here: @@ -4698,7 +4923,7 @@ You have to separate between binary and "normal" (source) packages here: * packages First, check that your package is complete, compiles and runs well; see - Chapter 14, Debugging and the rest of this document. Next, generate an + Chapter 15, Debugging and the rest of this document. Next, generate an uuencoded gzipped tar(1) archive, preferably with all files in a single directory. Finally, send-pr with category "pkg", a synopsis which includes the package name and version number, a short description of your package @@ -4712,7 +4937,7 @@ You have to separate between binary and "normal" (source) packages here: work-in-progress"); see the homepage at http://pkgsrc-wip.sourceforge.net/ for details. -15.2. Committing: Importing a package into CVS +16.2. Committing: Importing a package into CVS This section is only of interest for pkgsrc developers with write access to the pkgsrc repository. Please remember that cvs imports files relative to the @@ -4741,7 +4966,7 @@ there. For new packages, "cvs import" is preferred to "cvs add" because the former gets everything with a single command, and provides a consistent tag. -15.3. Updating a package to a newer version +16.3. Updating a package to a newer version Please always put a concise, appropriate and relevant summary of the changes between old and new versions into the commit log when updating a package. There @@ -4766,7 +4991,7 @@ which pkgsrc is used. Please use your judgement about what should go into pkgsrc, and bear in mind that stability is to be preferred above new and possibly untested features. -15.4. Moving a package in pkgsrc +16.4. Moving a package in pkgsrc 1. Make a copy of the directory somewhere else. |