Add a new chapter describing the pkginstall framework.
As a side effect, a question in the FAQ is simplified and several sections from the "fixes" chapter are removed.
This commit is contained in:
jmmv
parent
625b87ac7c
commit
6e1112e58c
6 changed files with 505 additions and 211 deletions
|
|
@ -1,4 +1,4 @@
|
|||
# $NetBSD: Makefile,v 1.2 2004/11/22 16:25:47 wiz Exp $
|
||||
# $NetBSD: Makefile,v 1.3 2005/06/03 12:27:48 jmmv Exp $
|
||||
|
||||
WEB_PREFIX?= ${.CURDIR}/../htdocs
|
||||
|
||||
|
|
@ -20,6 +20,7 @@ SRCS+= logs.xml
|
|||
SRCS+= options.xml
|
||||
SRCS+= platforms.xml
|
||||
SRCS+= plist.xml
|
||||
SRCS+= pkginstall.xml
|
||||
SRCS+= submit.xml
|
||||
SRCS+= using.xml
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<!--
|
||||
Creates entities for each chapter in the pkgsrc book.
|
||||
|
||||
$NetBSD: chapters.ent,v 1.3 2005/05/10 00:27:43 rillig Exp $
|
||||
$NetBSD: chapters.ent,v 1.4 2005/06/03 12:27:48 jmmv Exp $
|
||||
-->
|
||||
|
||||
<!-- users-guide -->
|
||||
|
|
@ -23,4 +23,5 @@
|
|||
<!ENTITY chap.ftp-layout SYSTEM "ftp-layout.xml">
|
||||
<!ENTITY chap.editing SYSTEM "editing.xml">
|
||||
<!ENTITY chap.platform SYSTEM "platforms.xml">
|
||||
<!ENTITY chap.pkginstall SYSTEM "pkginstall.xml">
|
||||
<!ENTITY chap.makefile SYSTEM "makefile.xml">
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<!-- $NetBSD: faq.xml,v 1.12 2005/06/01 15:49:44 jmmv Exp $ -->
|
||||
<!-- $NetBSD: faq.xml,v 1.13 2005/06/03 12:27:48 jmmv Exp $ -->
|
||||
|
||||
<chapter id="faq"> <?dbhtml filename="faq.html"?>
|
||||
<title>Frequently Asked Questions</title>
|
||||
|
|
@ -458,98 +458,29 @@ SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c
|
|||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="faq.conf">
|
||||
<title>Configuration files handling and placement</title>
|
||||
<title>How do I change the location of configuration files?</title>
|
||||
|
||||
<para>The global variable <varname>PKG_SYSCONFBASE</varname> (and some
|
||||
others) can be set by the system administrator in
|
||||
<filename>/etc/mk.conf</filename> 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
|
||||
<filename>$PREFIX/share</filename> should go there.</para>
|
||||
<para>As the system administrator, you can choose where configuration files
|
||||
are installed. The default settings make all these files go into
|
||||
<filename>${PREFIX}/etc</filename> or some of its subdirectories; this may
|
||||
be suboptimal depending on your expectations (e.g., a read-only,
|
||||
NFS-exported <varname>PREFIX</varname> with a need of per-machine
|
||||
configuration of the provided packages).</para>
|
||||
|
||||
<para>We will take a look at available variables first
|
||||
(<filename>bsd.pkg.mk</filename> contains more information).
|
||||
<varname>PKG_SYSCONFDIR</varname> is where the configuration files for a
|
||||
package may be found (that is, the full path, e.g.
|
||||
<filename>/etc</filename> or <filename>/usr/pkg/etc</filename>). This value
|
||||
may be customized in various ways:</para>
|
||||
<para>In order to change the defaults, you can modify the
|
||||
<varname>PKG_SYSCONFBASE</varname> variable (in
|
||||
<filename>/etc/mk.conf</filename>) to point to your preferred configuration
|
||||
directory; some common examples include <filename>/etc</filename> or
|
||||
<filename>/etc/pkg</filename>.</para>
|
||||
|
||||
<orderedlist>
|
||||
<para>Furthermore, you can change this value on a per-package basis by
|
||||
setting the <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> variable.
|
||||
<varname>PKG_SYSCONFVAR</varname>'s value usually matches the name of the
|
||||
package you would like to modify, that is, the contents of
|
||||
<varname>PKGBASE</varname>.</para>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFBASE</varname> is the main config directory
|
||||
under which all package configuration files are to be found. Users will
|
||||
typically want to set it to <filename>/etc</filename>, or accept the
|
||||
default location of <filename>$PREFIX/etc</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFSUBDIR</varname> is the subdirectory of
|
||||
<varname>PKG_SYSCONFBASE</varname> under which the configuration files
|
||||
for a particular package may be found. Defaults to
|
||||
<varname>${SYSCONFBASE}</varname>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFVAR</varname> is the special suffix used to
|
||||
distinguish any overriding values for a particular package (see next
|
||||
item). It defaults to <varname>${PKGBASE}</varname>, but for a
|
||||
collection of related packages that should all have the same
|
||||
<varname>PKG_SYSCONFDIR</varname> value, it can be set in each of the
|
||||
package Makefiles to a common value.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> overrides the
|
||||
value of <varname>${PKG_SYSCONFDIR}</varname> for packages with the
|
||||
same value for <varname>PKG_SYSCONFVAR</varname>.</para>
|
||||
|
||||
<para>As an example, all the various KDE packages may want to set
|
||||
<varname>PKG_SYSCONFVAR</varname> to <quote>kde</quote> so admins can
|
||||
set <varname>PKG_SYSCONFDIR.kde</varname> in
|
||||
<filename>/etc/mk.conf</filename> to define where to install KDE config
|
||||
files.</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>Programs' configuration directory should be defined during the
|
||||
configure stage. Packages that use GNU autoconf can usually do this by
|
||||
using the <quote>--sysconfdir</quote> 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
|
||||
<filename>share/examples/${PKGNAME}</filename> so
|
||||
<filename>PLIST</filename> can register them.</para>
|
||||
|
||||
<para>Once you have the required configuration files in place (under the
|
||||
<filename>share/examples</filename> directory) the variable
|
||||
<varname>CONF_FILES</varname> should be set to copy them into
|
||||
<varname>PKG_SYSCONFDIR</varname>. 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 <filename>PLIST</filename>)
|
||||
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
|
||||
<filename>INSTALL</filename>/<filename>DEINSTALL</filename> scripts which
|
||||
are created automatically. The package <filename>Makefile</filename> must
|
||||
also set <varname>USE_PKGINSTALL=YES</varname> to use these automatically
|
||||
generated scripts. The automatic copying of config files can be toggled by
|
||||
setting the environment variable <varname>PKG_CONFIG</varname> prior to
|
||||
package installation.</para>
|
||||
|
||||
<para>Here is an example, taken from
|
||||
<filename>mail/mutt/Makefile</filename>:</para>
|
||||
|
||||
<programlisting>EGDIR= ${PREFIX}/share/doc/mutt/samples
|
||||
CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc</programlisting>
|
||||
|
||||
<para>As you can see, this package installs configuration files inside
|
||||
<varname>EGDIR</varname>, which are registered by
|
||||
<filename>PLIST</filename>. After that, the variable
|
||||
<varname>CONF_FILES</varname> lists the installed file first and then the
|
||||
target file. Users will also get an automatic message when files are
|
||||
installed using this method.</para>
|
||||
<para>Note that, after changing these settings, you must rebuild and
|
||||
reinstall any affected packages.</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<!-- $NetBSD: fixes.xml,v 1.18 2005/06/01 22:49:59 jlam Exp $ -->
|
||||
<!-- $NetBSD: fixes.xml,v 1.19 2005/06/03 12:27:48 jmmv Exp $ -->
|
||||
|
||||
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
|
||||
<title>Notes on fixes for packages</title>
|
||||
|
|
@ -779,58 +779,6 @@ pre-configure:
|
|||
<sect1 id="package-specific-actions">
|
||||
<title>Package specific actions</title>
|
||||
|
||||
<sect2 id="package-configuration-files">
|
||||
<title>Package configuration files</title>
|
||||
|
||||
<para> Packages should be taught to look for their configuration
|
||||
files in <varname>${PKG_SYSCONFDIR}</varname>, which is passed
|
||||
through to the configure and build processes.
|
||||
<varname>PKG_SYSCONFDIR</varname> may be customized in various
|
||||
ways by setting other make variables: </para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para> <varname>PKG_SYSCONFBASE</varname> is the main config
|
||||
directory under which all package configuration files are
|
||||
to be found. This defaults to
|
||||
<filename>${PREFIX}/etc</filename>, but may be overridden
|
||||
in <filename>/etc/mk.conf</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para> <varname>PKG_SYSCONFSUBDIR</varname> is the subdirectory of
|
||||
<varname>PKG_SYSCONFBASE</varname> under which the
|
||||
configuration files for a particular package may be found, e.g.
|
||||
the Apache configuration files may all be found under the
|
||||
<filename>httpd/</filename> subdirectory of
|
||||
<varname>${PKG_SYSCONFBASE}</varname>. This should be set in
|
||||
the package Makefile.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para> By default,
|
||||
<varname>PKG_SYSCONFDIR</varname> is set to
|
||||
<varname>${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</varname>,
|
||||
but this may be overridden by setting
|
||||
<varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> for a
|
||||
particular package, where <varname>PKG_SYSCONFVAR</varname>
|
||||
defaults to <varname>${PKGBASE}</varname>. This is not meant to
|
||||
be set by a package Makefile, but is reserved for users who wish
|
||||
to override the <varname>PKG_SYSCONFDIR</varname> setting for
|
||||
a particular package with a special location.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para> The only variables that users should customize are
|
||||
<varname>PKG_SYSCONFBASE</varname> and <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname>.
|
||||
Users will typically want to set
|
||||
<varname>PKG_SYSCONFBASE</varname> to
|
||||
<filename>/etc</filename>, or to accept the default location
|
||||
of <filename>${PREFIX}/etc</filename>. </para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="user-interaction">
|
||||
<title>User interaction</title>
|
||||
|
||||
|
|
@ -928,46 +876,6 @@ pre-configure:
|
|||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="creating-accounts">
|
||||
<title>Creating an account from a package</title>
|
||||
|
||||
<para> There are two make variables used to control the creation
|
||||
of package-specific groups and users at pre-install time. The
|
||||
first is <varname>PKG_GROUPS</varname>, which is a list of
|
||||
group[:groupid] elements, where the groupid is optional. The
|
||||
second is <varname>PKG_USERS</varname>, which is a list of
|
||||
elements of the form: </para>
|
||||
|
||||
<programlisting>user:group[:[userid][:[description][:[home][:shell]]]]</programlisting>
|
||||
|
||||
<para> where only the user and group are required, the rest being
|
||||
optional. A simple example is: </para>
|
||||
|
||||
<programlisting> PKG_GROUPS= foogroup
|
||||
PKG_USERS= foouser:foogroup</programlisting>
|
||||
|
||||
<para> A more complex example is that creates two groups and two
|
||||
users is: </para>
|
||||
|
||||
<programlisting> PKG_GROUPS= group1 group2:1005
|
||||
PKG_USERS= first:group1::First\\ User \
|
||||
second:group2::Second\\ User:/home/second:${SH}</programlisting>
|
||||
|
||||
<para> By default, a new user will have home directory
|
||||
<filename>/nonexistent</filename>, and login shell
|
||||
<filename>/sbin/nologin</filename> unless they are specified as
|
||||
part of the user element. </para>
|
||||
|
||||
<para> The package <filename>Makefile</filename> must also set
|
||||
<varname>USE_PKGINSTALL=YES</varname>. 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 <varname>PKG_CREATE_USERGROUP</varname> variable
|
||||
prior to package installation. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="installing-score-files">
|
||||
<title>Installing score files</title>
|
||||
|
||||
|
|
@ -993,31 +901,6 @@ pre-configure:
|
|||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="login-shells">
|
||||
<title>Packages providing login shells</title>
|
||||
|
||||
<para> If the purpose of the package is to provide a login shell,
|
||||
the variable <varname>PKG_SHELL</varname> should contain the
|
||||
full pathname of the shell executable installed by this
|
||||
package. The package <filename>Makefile</filename> must also
|
||||
set <varname>USE_PKGINSTALL=YES</varname> to use the
|
||||
automatically generated
|
||||
<filename>INSTALL</filename>/<filename>DEINSTALL</filename>
|
||||
scripts. </para>
|
||||
|
||||
<para> An example taken from shells/zsh: </para>
|
||||
|
||||
<programlisting> USE_PKGINSTALL= YES
|
||||
PKG_SHELL= ${PREFIX}/bin/zsh</programlisting>
|
||||
|
||||
<para>
|
||||
The shell is registered into <filename>/etc/shells</filename>
|
||||
file automatically in the post-install target by the generated
|
||||
<filename>INSTALL</filename> script and removed in the deinstall
|
||||
target by the <filename>DEINSTALL</filename> script. </para>
|
||||
</sect2>
|
||||
|
||||
|
||||
<sect2 id="perl-scripts">
|
||||
<title>Packages containing perl scripts</title>
|
||||
|
||||
|
|
|
|||
477
doc/guide/files/pkginstall.xml
Normal file
477
doc/guide/files/pkginstall.xml
Normal file
|
|
@ -0,0 +1,477 @@
|
|||
<!-- $NetBSD: pkginstall.xml,v 1.1 2005/06/03 12:27:48 jmmv Exp $ -->
|
||||
|
||||
<chapter id="pkginstall"> <?dbhtml filename="pkginstall.html"?>
|
||||
<title>The pkginstall framework</title>
|
||||
|
||||
<para>This chapter describes the framework known as
|
||||
<literal>pkginstall</literal>, whose key features are:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para>Generic installation and manipulation of directories and files
|
||||
outside the pkgsrc-handled tree, <varname>LOCALBASE</varname>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Automatic handling of configuration files during installation,
|
||||
provided that packages are correctly designed.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Generation and installation of system startup scripts.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Registration of system users and groups.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Registration of system shells.</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
<para>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 <filename>Makefile</filename>:</para>
|
||||
|
||||
<programlisting>USE_PKGINSTALL=YES</programlisting>
|
||||
|
||||
<para>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
|
||||
(<literal>post-install</literal>). <emphasis>This is incorrect</emphasis>,
|
||||
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.</para>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="files-and-dirs-outside-prefix">
|
||||
<title>Files and directories outside the installation prefix</title>
|
||||
|
||||
<para>As you already know, the <filename>PLIST</filename> file holds a list
|
||||
of files and directories that belong to a package. The names used in it
|
||||
are relative to the installation prefix (<filename>${PREFIX}</filename>),
|
||||
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
|
||||
<filename>${VARBASE}</filename> or
|
||||
<filename>${PKG_SYSCONFDIR}</filename>.</para>
|
||||
|
||||
<para>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
|
||||
<filename>Makefile</filename>. The rest of this section describes which
|
||||
these variables are.</para>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="dirs-outside-prefix">
|
||||
<title>Directory manipulation</title>
|
||||
|
||||
<para>The following variables can be set to request the creation of
|
||||
directories anywhere in the filesystem:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para><varname>MAKE_DIRS</varname> and <varname>OWN_DIRS</varname>
|
||||
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.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>MAKE_DIRS_PERMS</varname> and
|
||||
<varname>OWN_DIRS_PERMS</varname> 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:</para>
|
||||
|
||||
<programlisting>MAKE_DIRS_PERMS+= ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700</programlisting>
|
||||
|
||||
<para>The difference between the two is exactly the same as their
|
||||
non-<varname>PERMS</varname> counterparts.</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="files-outside-prefix">
|
||||
<title>File manipulation</title>
|
||||
|
||||
<para>Creating non-empty files outside the installation prefix is tricky
|
||||
because the <filename>PLIST</filename> 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 <emphasis>master
|
||||
file</emphasis> in the following paragraphs, which describe the variables
|
||||
that can be used to automatically and consistently handle files outside the
|
||||
installation prefix:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para><varname>CONF_FILES</varname> and
|
||||
<varname>SUPPORT_FILES</varname> 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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>CONF_FILES_PERMS</varname> and
|
||||
<varname>SUPPORT_FILES_PERMS</varname> 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:</para>
|
||||
|
||||
<programlisting>SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700</programlisting>
|
||||
|
||||
<para>The difference between the two is exactly the same as their
|
||||
non-<varname>PERMS</varname> counterparts.</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="conf-files">
|
||||
<title>Configuration files</title>
|
||||
|
||||
<para>Configuration files are special in the sense that they are installed
|
||||
in their own specific directory, <varname>PKG_SYSCONFDIR</varname>, 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 <varname>PKG_SYSCONFDIR</varname>) during installation <emphasis>if
|
||||
and only if</emphasis> 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.</para>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="conf-files-sysconfdir">
|
||||
<title>How <varname>PKG_SYSCONFDIR</varname> is set</title>
|
||||
|
||||
<para>As said before, the <varname>PKG_SYSCONFDIR</varname> variable
|
||||
specifies where configuration files shall be installed. Its contents are
|
||||
set based upon the following variables:</para>
|
||||
|
||||
<itemizedlist>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFBASE</varname>: The configuration's root
|
||||
directory. Defaults to <filename>${PREFIX}/etc</filename> although may
|
||||
be overridden by the user to point to his preferred location (e.g.,
|
||||
<filename>/etc</filename>, <filename>/etc/pkg</filename>, etc.).
|
||||
Packages must not use it directly.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFSUBDIR</varname>: A subdirectory of
|
||||
<varname>PKG_SYSCONFBASE</varname> 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
|
||||
<filename>Makefile</filename> (i.e., it is not user
|
||||
customizable).</para>
|
||||
|
||||
<para>As an example, consider the Apache package,
|
||||
<pkg>www/apache2</pkg>, which places its configuration files under the
|
||||
<filename>httpd/</filename> subdirectory of
|
||||
<varname>PKG_SYSCONFBASE</varname>. This should be set in the package
|
||||
Makefile.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFVAR</varname>: Specifies the name of the
|
||||
variable that holds this package's configuration directory (if
|
||||
different from <varname>PKG_SYSCONFBASE</varname>). It defaults to
|
||||
<varname>PKGBASE</varname>'s value, and is always prefixed with
|
||||
<literal>PKG_SYSCONFDIR</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname>: Holds the
|
||||
directory where the configuration files for the package identified by
|
||||
<varname>PKG_SYSCONFVAR</varname>'s shall be placed.</para>
|
||||
</listitem>
|
||||
|
||||
</itemizedlist>
|
||||
|
||||
<para>Based on the above variables, pkginstall determines the value of
|
||||
<varname>PKG_SYSCONFDIR</varname>, which is the <emphasis>only</emphasis>
|
||||
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:</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>If <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> is set,
|
||||
its value is used.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If the previous variable is not defined but
|
||||
<varname>PKG_SYSCONFSUBDIR</varname> is set in the package's
|
||||
<filename>Makefile</filename>, the resulting value is
|
||||
<filename>${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Otherwise, it is set to
|
||||
<filename>${PKG_SYSCONFBASE}</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>It is worth mentioning that <filename>${PKG_SYSCONFDIR}</filename> is
|
||||
automatically added to <filename>OWN_DIRS</filename>. See <xref
|
||||
linkend="dirs-outside-prefix" /> what this means.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="conf-files-configure">
|
||||
<title>Telling the software were configuration files are</title>
|
||||
|
||||
<para>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:</para>
|
||||
|
||||
<programlisting>CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}</programlisting>
|
||||
|
||||
<para>Note that this specifies where the package has to <emphasis>look
|
||||
for</emphasis> its configuration files, not where they will be originally
|
||||
installed (although the difference is never explicit,
|
||||
unfortunately).</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="conf-files-patching">
|
||||
<title>Patching installations</title>
|
||||
|
||||
<para>As said before, pkginstall automatically handles configuration files.
|
||||
This means that <emphasis role="strong">the packages themselves must not
|
||||
touch the contents of <filename>${PKG_SYSCONFDIR}</filename>
|
||||
directly</emphasis>. 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?</para>
|
||||
|
||||
<para>You must teach the package (usually by manually patching it) to
|
||||
install any configuration files under the examples hierarchy,
|
||||
<filename>share/examples/${PKGBASE}/</filename>. This way, the
|
||||
<filename>PLIST</filename> registers them and the administrator always
|
||||
has the original copies available.</para>
|
||||
|
||||
<para>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
|
||||
<filename>${PKG_SYSCONFDIR}</filename>. To achieve this, the variables
|
||||
<varname>CONF_FILES</varname> and <varname>CONF_FILES_PERMS</varname> are
|
||||
used. Check out <xref linkend="files-outside-prefix" /> for information
|
||||
about their syntax and their purpose. Here is an example, taken from the
|
||||
<pkg>mail/mutt</pkg> package:</para>
|
||||
|
||||
<programlisting>EGDIR= ${PREFIX}/share/doc/mutt/samples
|
||||
CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc</programlisting>
|
||||
|
||||
<para>Note that the <varname>EGDIR</varname> variable is specific to that
|
||||
package and has no meaning outside it.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="conf-files-disable">
|
||||
<title>Disabling handling of configuration files</title>
|
||||
|
||||
<!-- XXX This doesn't really belong here -->
|
||||
|
||||
<para>The automatic copying of config files can be toggled by setting the
|
||||
environment variable <varname>PKG_CONFIG</varname> prior to package
|
||||
installation.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="rcd-scripts">
|
||||
<title>System startup scripts</title>
|
||||
|
||||
<para>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 <xref
|
||||
linkend="files-and-dirs-outside-prefix" /> apply, and the same solutions
|
||||
can be used. However, pkginstall provides a specific mechanism to handle
|
||||
these files, given that they are special.</para>
|
||||
|
||||
<para>In order to provide system startup scripts, the package has
|
||||
to:</para>
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>Store the script inside <filename>${FILESDIR}</filename>, with
|
||||
the <literal>.sh</literal> suffix appended. Considering the
|
||||
<pkg>print/cups</pkg> package as an example, it has the
|
||||
<filename>cupsd.sh</filename> in its files directory.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Tell pkginstall to handle it, appending the name of the script,
|
||||
without its extension, to the <varname>RCD_SCRIPTS</varname> variable.
|
||||
Continuing the previous example:</para>
|
||||
|
||||
<programlisting>RCD_SCRIPTS+= cupsd</programlisting>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<para>Once this is done, pkginstall will do the following steps for each
|
||||
script in an automated fashion:</para>
|
||||
|
||||
<!-- XXX We should probably have a chapter describing how rc.d scripts are
|
||||
written. -->
|
||||
|
||||
<orderedlist>
|
||||
|
||||
<listitem>
|
||||
<para>Process the file found in the files directory applying all the
|
||||
substitutions described in the <filename>FILES_SUBST</filename>
|
||||
variable.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Copy the script from the files directory to the examples
|
||||
hierarchy, <filename>${PREFIX}/share/examples/rc.d/</filename>. Note
|
||||
that the master file must be explicitly registered in the
|
||||
<filename>PLIST</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Add code to the installation scripts to copy the startup script
|
||||
from the examples hierarchy into the system-wide startup scripts
|
||||
directory.</para>
|
||||
</listitem>
|
||||
|
||||
</orderedlist>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="rcd-scripts-disable">
|
||||
<title>Disabling handling of system startup scripts</title>
|
||||
|
||||
<!-- XXX This doesn't really belong here -->
|
||||
|
||||
<para>The automatic copying of config files can be toggled by setting the
|
||||
environment variable <varname>PKG_RCD_SCRIPTS</varname> prior to package
|
||||
installation. Note that the scripts will be always copied inside the
|
||||
examples hierarchy, <filename>${PREFIX}/share/examples/rc.d/</filename>, no
|
||||
matter what the value of this variable is.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="users-and-groups">
|
||||
<title>System users and groups</title>
|
||||
|
||||
<para>If a package needs to create special users and/or groups during
|
||||
installation, it can do so by using the pkginstall framework.</para>
|
||||
|
||||
<para>Users can be created by adding entries to the
|
||||
<varname>PKG_USERS</varname> variable. Each entry has the following
|
||||
syntax, which mimics <filename>/etc/passwd</filename>:</para>
|
||||
|
||||
<programlisting>user:group[:[userid][:[descr][:[home][:shell]]]]</programlisting>
|
||||
|
||||
<para>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
|
||||
<filename>/nonexistent</filename>, and login shell
|
||||
<filename>/sbin/nologin</filename> 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:</para>
|
||||
|
||||
<programlisting>foo:foogrp::The\\ Foomister</programlisting>
|
||||
|
||||
<para>Similarly, groups can be created using the
|
||||
<varname>PKG_GROUPS</varname> variable, whose syntax is:</para>
|
||||
|
||||
<programlisting>group[:groupid]</programlisting>
|
||||
|
||||
<para>As before, only the group name is required; the numeric identifier is
|
||||
optional.</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect1 id="shells">
|
||||
<title>System shells</title>
|
||||
|
||||
<para>Packages that install system shells should register them in the shell
|
||||
database, <filename>/etc/shells</filename>, 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.</para>
|
||||
|
||||
<para>When a package provides a shell interpreter, it has to set the
|
||||
<varname>PKG_SHELL</varname> variable to its absolute file name. This will
|
||||
add some hooks to the installation scripts to handle it. Consider the
|
||||
following example, taken from <pkg>shells/zsh</pkg>:</para>
|
||||
|
||||
<programlisting>USE_PKGINSTALL= YES
|
||||
PKG_SHELL= ${PREFIX}/bin/zsh</programlisting>
|
||||
|
||||
<!-- ================================================================== -->
|
||||
|
||||
<sect2 id="shells-disable">
|
||||
<title>Disabling handling of configuration files</title>
|
||||
|
||||
<!-- XXX This doesn't really belong here -->
|
||||
|
||||
<para>The automatic registration of shell interpreters can be disabled by
|
||||
the administrator by setting the <filename>PKG_REGISTER_SHELLS</filename>
|
||||
environment variable to <literal>NO</literal>.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
<!-- $NetBSD: pkgsrc.xml,v 1.7 2005/05/24 12:39:00 wiz Exp $ -->
|
||||
<!-- $NetBSD: pkgsrc.xml,v 1.8 2005/06/03 12:27:48 jmmv Exp $ -->
|
||||
|
||||
|
||||
<?xml version="1.0"?>
|
||||
|
|
@ -45,7 +45,7 @@
|
|||
<holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
|
||||
</copyright>
|
||||
|
||||
<pubdate>$NetBSD: pkgsrc.xml,v 1.7 2005/05/24 12:39:00 wiz Exp $</pubdate>
|
||||
<pubdate>$NetBSD: pkgsrc.xml,v 1.8 2005/06/03 12:27:48 jmmv Exp $</pubdate>
|
||||
|
||||
<abstract>
|
||||
<para>Information about using the NetBSD package system (pkgsrc)
|
||||
|
|
@ -74,6 +74,7 @@
|
|||
&chap.makefile;
|
||||
&chap.plist;
|
||||
&chap.buildlink;
|
||||
&chap.pkginstall;
|
||||
&chap.options;
|
||||
&chap.build;
|
||||
&chap.fixes;
|
||||
|
|
|
|||
Loading…
Reference in a new issue