Index: files/Makefile =================================================================== RCS file: /cvsroot/pkgsrc/doc/guide/files/Makefile,v retrieving revision 1.2 diff -u -u -r1.2 Makefile --- files/Makefile 22 Nov 2004 16:25:47 -0000 1.2 +++ files/Makefile 1 Jun 2005 20:47:11 -0000 @@ -20,6 +21,7 @@ SRCS+= options.xml SRCS+= platforms.xml SRCS+= plist.xml +SRCS+= pkginstall.xml SRCS+= submit.xml SRCS+= using.xml Index: files/chapters.ent =================================================================== RCS file: /cvsroot/pkgsrc/doc/guide/files/chapters.ent,v retrieving revision 1.3 diff -u -u -r1.3 chapters.ent --- files/chapters.ent 10 May 2005 00:27:43 -0000 1.3 +++ files/chapters.ent 1 Jun 2005 20:47:11 -0000 @@ -23,4 +23,5 @@ + Index: files/faq.xml =================================================================== RCS file: /cvsroot/pkgsrc/doc/guide/files/faq.xml,v retrieving revision 1.12 diff -u -u -r1.12 faq.xml --- files/faq.xml 1 Jun 2005 15:49:44 -0000 1.12 +++ files/faq.xml 1 Jun 2005 20:47:11 -0000 @@ -458,98 +458,29 @@ -Configuration files handling and placement +How do I change the location of configuration files? -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: +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. - - - - 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. - - - - PKG_SYSCONFSUBDIR is the subdirectory of - PKG_SYSCONFBASE under which the configuration files - for a particular package may be found. Defaults to - ${SYSCONFBASE}. - - - - 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. - - - - 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: - -EGDIR= ${PREFIX}/share/doc/mutt/samples -CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc - -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. Index: files/fixes.xml =================================================================== RCS file: /cvsroot/pkgsrc/doc/guide/files/fixes.xml,v retrieving revision 1.17 diff -u -u -r1.17 fixes.xml --- files/fixes.xml 29 May 2005 09:10:42 -0000 1.17 +++ files/fixes.xml 1 Jun 2005 20:47:11 -0000 @@ -786,58 +786,6 @@ Package specific actions - - 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. - - - - - 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. - - User interaction Index: files/pkginstall.xml =================================================================== RCS file: files/pkginstall.xml diff -N files/pkginstall.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ files/pkginstall.xml 1 Jun 2005 20:47:11 -0000 @@ -0,0 +1,250 @@ + + + +The pkginstall framework + +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. + + + + Registration of system users and groups. + + + + Registration of system shells. + + + + +The following sections will 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 + + + + +Files and directories outside the installation prefix + +TODO + + + + + + +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. Therefore, they need special +treatment, most of which can be automated by using pkginstall. + +The main concept you must have 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. + + + + +How <varname>PKG_SYSCONFDIR</varname> 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: + + + + + If PKG_SYSCONFDIR.${PKG_SYSCONFVAR} is set, + its value is used. + + + + 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} + + + + Otherwise, it is set to + ${PKG_SYSCONFBASE}. + + + + + + + + + +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 easy to achieve during the +configuration stage. + +In case the package uses GNU Autoconf, it should be as easy as +doing: + +CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR} + + + + + + +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/${PKGNAME}/. 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: + + + + + CONF_FILES holds a list of file names pairs: + the first element of the couple specifies the file inside the examples + directory and the second element specifies the target file under the + configuration directory. + + + + CONF_FILES_PERMS is similar to + CONF_FILES, but it specifies the user and group of + the owner of the target file, as well as its permissions, in this + order. That is, an entry might look like: + + CONF_FILES_PERMS+= example_file config_file user group mode + + + + +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. + + + + + + +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. + + + + + + + + +System users and groups + +TODO + + + + + + +System shells + +TODO + + + + Index: files/pkgsrc.xml =================================================================== RCS file: /cvsroot/pkgsrc/doc/guide/files/pkgsrc.xml,v retrieving revision 1.7 diff -u -u -r1.7 pkgsrc.xml --- files/pkgsrc.xml 24 May 2005 12:39:00 -0000 1.7 +++ files/pkgsrc.xml 1 Jun 2005 20:47:11 -0000 @@ -74,6 +74,7 @@ &chap.makefile; &chap.plist; &chap.buildlink; + &chap.pkginstall; &chap.options; &chap.build; &chap.fixes;