pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Add a new chapter describing the pkgin...
details: https://anonhg.NetBSD.org/pkgsrc/rev/e0019fd2e608
branches: trunk
changeset: 495145:e0019fd2e608
user: jmmv <jmmv%pkgsrc.org@localhost>
date: Fri Jun 03 12:27:48 2005 +0000
description:
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.
diffstat:
doc/guide/files/Makefile | 3 +-
doc/guide/files/chapters.ent | 3 +-
doc/guide/files/faq.xml | 109 +-------
doc/guide/files/fixes.xml | 119 +----------
doc/guide/files/pkginstall.xml | 477 +++++++++++++++++++++++++++++++++++++++++
doc/guide/files/pkgsrc.xml | 5 +-
6 files changed, 505 insertions(+), 211 deletions(-)
diffs (truncated from 816 to 300 lines):
diff -r a3c76af62ae2 -r e0019fd2e608 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile Fri Jun 03 10:29:23 2005 +0000
+++ b/doc/guide/files/Makefile Fri Jun 03 12:27:48 2005 +0000
@@ -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+= options.xml
SRCS+= platforms.xml
SRCS+= plist.xml
+SRCS+= pkginstall.xml
SRCS+= submit.xml
SRCS+= using.xml
diff -r a3c76af62ae2 -r e0019fd2e608 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent Fri Jun 03 10:29:23 2005 +0000
+++ b/doc/guide/files/chapters.ent Fri Jun 03 12:27:48 2005 +0000
@@ -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">
diff -r a3c76af62ae2 -r e0019fd2e608 doc/guide/files/faq.xml
--- a/doc/guide/files/faq.xml Fri Jun 03 10:29:23 2005 +0000
+++ b/doc/guide/files/faq.xml Fri Jun 03 12:27:48 2005 +0000
@@ -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 @@
<!-- ================================================================== -->
<sect1 id="faq.conf">
-<title>Configuration files handling and placement</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>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>
-
-<orderedlist>
+<title>How do I change the location of configuration files?</title>
- <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>
+<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>
- <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>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>
-<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>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>
-<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>
diff -r a3c76af62ae2 -r e0019fd2e608 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Fri Jun 03 10:29:23 2005 +0000
+++ b/doc/guide/files/fixes.xml Fri Jun 03 12:27:48 2005 +0000
@@ -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 @@
<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 @@
</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 @@
</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>
Home |
Main Index |
Thread Index |
Old Index