pkgsrc-Changes archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
CVS commit: pkgsrc/doc/guide/files
Module Name: pkgsrc
Committed By: dholland
Date: Fri May 12 07:13:58 UTC 2023
Modified Files:
pkgsrc/doc/guide/files: pkginstall.xml
Log Message:
guide: rework sections 20.1-2 about the config files framework
Prompted by PR 41784 (from mspo) and includes the suggestion there,
but broader because the prior structure was inadequate to the task.
To generate a diff of this commit:
cvs rdiff -u -r1.22 -r1.23 pkgsrc/doc/guide/files/pkginstall.xml
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: pkgsrc/doc/guide/files/pkginstall.xml
diff -u pkgsrc/doc/guide/files/pkginstall.xml:1.22 pkgsrc/doc/guide/files/pkginstall.xml:1.23
--- pkgsrc/doc/guide/files/pkginstall.xml:1.22 Thu May 19 23:48:53 2022
+++ pkgsrc/doc/guide/files/pkginstall.xml Fri May 12 07:13:57 2023
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkginstall.xml,v 1.22 2022/05/19 23:48:53 khorben Exp $ -->
+<!-- $NetBSD: pkginstall.xml,v 1.23 2023/05/12 07:13:57 dholland Exp $ -->
<chapter id="pkginstall"> <?dbhtml filename="pkginstall.html"?>
<title>The pkginstall framework</title>
@@ -137,10 +137,10 @@ MAKE_DIRS_PERMS+= ${VARBASE}/foo/p
<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
+To overcome this problem, the only solution is to extract the file in a
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
+generated by pkginstall). We will call the former the <emphasis>reference
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>
@@ -148,37 +148,54 @@ installation prefix:</para>
<itemizedlist>
<listitem>
- <para><varname>CONF_FILES</varname> and
- <varname>REQD_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>REQD_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>
+ <para><varname>REQD_FILES</varname> is a list of pairs of reference
+ and target files. At installation time, the reference file is copied
+ to the target if and only if the latter does not exist. Upon
+ deinstallation, the reference file is removed provided that it was
+ not modified by the installation.</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>REQD_FILES_PERMS</varname> contains tuples describing
+ reference files and targets, including owner, group, and numeric
+ permissions that should be set. For example:</para>
<programlisting>
REQD_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile \
${REAL_ROOT_USER} ${REAL_ROOT_GROUP} 0700
</programlisting>
- <para>The difference between the two is exactly the same as their
- non-<varname>PERMS</varname> counterparts.</para>
</listitem>
+ <listitem>
+ <para><varname>CONF_FILES</varname> and
+ <varname>CONF_FILES_PERMS</varname> have the same syntax as
+ <varname>REQD_FILES</varname> and
+ <varname>REQD_FILES_PERMS</varname> respectively. The difference
+ is that these variables are specifically intended for handling
+ configuration files, for which additional conventions and
+ constraints apply. See <xref linkend="conf-files" /> for further
+ discussion. Note in particular that while handling of
+ configuration files can be disabled by the user (see <xref
+ linkend="conf-files-disable" />), this setting does not affect
+ <varname>REQD_FILES</varname> and
+ <varname>REQD_FILES_PERMS</varname>.</para>
+ </listitem>
+
+<!--
+ I can find no evidence for this behavior. If anything, it's the
+ other way around. - dholland 20230511
+
+ <para>The difference between the two variable sets is that the
+ <varname>REQD</varname> versions prompt the administrator to
+ remove any files that may be left after deinstallation (because
+ they were not empty), while the former does not.</para>
+-->
</itemizedlist>
+ <para>To install an empty file, one can use these macros and
+ <filename>/dev/null</filename> as the reference file.</para>
+
</sect2>
</sect1>
@@ -188,15 +205,41 @@ REQD_FILES_PERMS+= ${PREFIX}/share/
<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 configuration files 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 lose any custom changes they may have made.</para>
+<para>There are two principles that govern the handling of
+configuration files in pkgsrc: first, the user's configuration must
+not be lost or overwritten by upgrades or reinstallations; and second,
+the default configuration should always be available for reference.
+To that end, pkgsrc has a framework specifically for handling
+configuration files. In general, configuration files are installed
+into <filename>${PREFIX}/share/examples</filename>, and copied from
+there to the pertinent <filename>etc</filename> directory as a
+separate step and only as needed.</para>
+
+<para>To make this work, there are three things that need to happen,
+any of which may require patching. First, the package must be told to
+read its configuration from the correct place at runtime; this place
+is <filename>${PKG_SYSCONFDIR}</filename> (or possibly a subdirectory
+of it) which is often but not always
+<filename>${PREFIX}/etc</filename>. Second, the package must be
+taught to install its default configuration files in
+<filename>${PREFIX}/share/examples/${PKGBASE}</filename>; this is the
+point at which patching often becomes required because it is not the
+same place as the runtime location. Third, the configuration files
+need to be declared in the package makefile; this is the easy part.
+</para>
+
+<para>With those elements in place, the right things will happen: the
+package install phase and resulting binary package will not touch
+<filename>${PKG_SYSCONFDIR}</filename>, and the default configuration
+will be copied into place by the pkgsrc framework only if not already
+present. Similarly, upon deinstall the configuration will not be
+removed if it has been modified. (This means that in the case of
+reinstallation and upgrades, unmodified configuration files are
+updated but modifications are never discarded.)</para>
+
+<para>The following sections describe how to make these things happen
+and document other relevant knobs available in the pkgsrc
+infrastructure.</para>
<!-- ================================================================== -->
@@ -212,7 +255,7 @@ set based upon the following variables:<
<listitem>
<para><varname>PKG_SYSCONFBASE</varname>: The configuration's root
directory. Defaults to <filename>${PREFIX}/etc</filename> although it may
- be overridden by the user to point to his preferred location (e.g.,
+ be overridden by the user to point to their preferred location (e.g.,
<filename>/etc</filename>, <filename>/etc/pkg</filename>, etc.).
Packages must not use it directly.</para>
</listitem>
@@ -250,7 +293,7 @@ set based upon the following variables:<
<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
+variable that may be used within a package to refer to its configuration
directory. The algorithm used to set its value is basically the
following:</para>
@@ -276,10 +319,12 @@ following:</para>
</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. This does not apply to
-subdirectories of <filename>${PKG_SYSCONFDIR}</filename>, they still have to
-be created with OWN_DIRS or MAKE_DIRS.</para>
+automatically added to <filename>OWN_DIRS</filename>. This causes it
+to be automatically created if needed. See <xref
+linkend="dirs-outside-prefix" /> for further details. This does not apply to
+subdirectories of <filename>${PKG_SYSCONFDIR}</filename>; they must be manually
+created with <varname>OWN_DIRS</varname> or
+<varname>MAKE_DIRS</varname>.</para>
</sect2>
@@ -289,30 +334,30 @@ be created with OWN_DIRS or MAKE_DIRS.</
<title>Telling the software where 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 it shall 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>
+known place, you need to teach each package where to 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 for packages using GNU
+autoconf:</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>
+for</emphasis> its configuration files, not where they will be installed.
+Fortunately, there is a different way to specify the latter, as seen
+in the next seection, although the combination is rather confusing at
+first glance.</para>
</sect2>
<!-- ================================================================== -->
<sect2 id="conf-files-patching">
-<title>Patching installations</title>
+<title>Patching installation</title>
-<para>As said before, pkginstall automatically handles configuration files.
-This means that <emphasis role="strong">the packages themselves must not
+<para>As discussed above, <emphasis role="strong">packages themselves must not
touch the contents of <filename>${PKG_SYSCONFDIR}</filename>
directly</emphasis>. Bad news is that many software installation scripts
will, out of the box, mess with the contents of that directory. So what is
@@ -324,22 +369,54 @@ install any configuration files under th
<filename>PLIST</filename> registers them and the administrator always
has the original copies available.</para>
+<para>It turns out that for packages using GNU autoconf it is possible
+to create the desired effect by setting <varname>sysconfdir</varname>
+on the make command line at install time. Consider this example taken
+from <filename role="pkg">mail/mutt</filename>:</para>
+
+<programlisting>
+EGDIR= ${PREFIX}/share/examples/mutt
+INSTALL_MAKE_FLAGS= ${MAKE_FLAGS} sysconfdir=${EGDIR}
+</programlisting>
+
+<para>Note that the <varname>EGDIR</varname> variable, though commonly
+used for this purpose, is local to that package and has no meaning
+outside it.</para>
+
+</sect2>
+
+<!-- ================================================================== -->
+
+<sect2 id="conf-files-declare">
+<title>Declaring configuration files</title>
+
<para>Once the required configuration files are in place (i.e., under the
-examples hierarchy), the pkginstall framework can use them as master copies
+examples hierarchy), the pkginstall framework can use them as reference 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
-<filename role="pkg">mail/mutt</filename> package:</para>
+used. Check out <xref linkend="files-outside-prefix" /> for further
+information about their syntax and their purpose. Here is an example,
+taken from the <filename role="pkg">mail/mutt</filename> package:</para>
<programlisting>
-EGDIR= ${PREFIX}/share/doc/mutt/samples
-CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
+EGDIR= ${PREFIX}/share/examples/mutt
+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>
+<para>Note that (as in the previous section's example) the
+<varname>EGDIR</varname> variable is specific to the package and has
+no meaning outside it.</para>
+
+<para>For reference, the complete example from Mutt is as follows:</para>
+
+<programlisting>
+CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
+EGDIR= ${PREFIX}/share/examples/mutt
+CONF_FILES= ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
+INSTALLATION_DIRS+= ${EGDIR}
+INSTALL_MAKE_FLAGS= ${MAKE_FLAGS} sysconfdir=${EGDIR}
+</programlisting>
</sect2>
@@ -411,7 +488,7 @@ script in an automated fashion:</para>
<listitem>
<para>Copy the script from the files directory to the examples
hierarchy, <filename>${PREFIX}/share/examples/rc.d/</filename>. Note
- that this master file must be explicitly registered in the
+ that this reference file must be explicitly registered in the
<filename>PLIST</filename>.</para>
</listitem>
Home |
Main Index |
Thread Index |
Old Index