[pkgsrc/trunk]: pkgsrc/doc/guide/files Added a new chapter to the pkgsrc user...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/bc74b45a03d0
branches:  trunk
changeset: 518826:bc74b45a03d0
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Tue Sep 19 17:50:38 2006 +0000

description:
Added a new chapter to the pkgsrc user's guide, which describes the file
system layout of pkgsrc.

diffstat:

 doc/guide/files/Makefile     |    3 +-
 doc/guide/files/chapters.ent |    3 +-
 doc/guide/files/files.xml    |  143 +++++++++++++++++++++++++++++++++++++++++++
 doc/guide/files/pkgsrc.xml   |    5 +-
 4 files changed, 150 insertions(+), 4 deletions(-)

diffs (210 lines):

diff -r 263fdf089272 -r bc74b45a03d0 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile  Tue Sep 19 17:47:49 2006 +0000
+++ b/doc/guide/files/Makefile  Tue Sep 19 17:50:38 2006 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.11 2006/07/03 23:51:01 rillig Exp $
+# $NetBSD: Makefile,v 1.12 2006/09/19 17:50:38 rillig Exp $
 
 WEB_PREFIX?=   ${.CURDIR}/../htdocs
 
@@ -16,6 +16,7 @@
 SRCS+= editing.xml
 SRCS+= examples.xml
 SRCS+= faq.xml
+SRCS+= files.xml
 SRCS+= fixes.xml
 SRCS+= ftp-layout.xml
 SRCS+= getting.xml
diff -r 263fdf089272 -r bc74b45a03d0 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent      Tue Sep 19 17:47:49 2006 +0000
+++ b/doc/guide/files/chapters.ent      Tue Sep 19 17:50:38 2006 +0000
@@ -1,7 +1,7 @@
 <!--
        Creates entities for each chapter in the pkgsrc book.
 
-       $NetBSD: chapters.ent,v 1.15 2006/09/01 16:35:38 jmmv Exp $
+       $NetBSD: chapters.ent,v 1.16 2006/09/19 17:50:38 rillig Exp $
 -->
 
 <!ENTITY chap.intro                    SYSTEM "introduction.xml">
@@ -12,6 +12,7 @@
 <!ENTITY chap.using                    SYSTEM "using.xml">
 <!ENTITY chap.configuring              SYSTEM "configuring.xml">
 <!ENTITY chap.binary                   SYSTEM "binary.xml">
+<!ENTITY chap.files                    SYSTEM "files.xml">
 <!ENTITY chap.faq                      SYSTEM "faq.xml">
 
 <!-- developer's guide -->
diff -r 263fdf089272 -r bc74b45a03d0 doc/guide/files/files.xml
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/files.xml Tue Sep 19 17:50:38 2006 +0000
@@ -0,0 +1,143 @@
+<!-- $NetBSD: files.xml,v 1.1 2006/09/19 17:50:38 rillig Exp $ -->
+
+<chapter id="files">
+<title>Directory layout of the installed files</title>
+
+<para>The files that are installed by pkgsrc are organized in a way that
+is similar to what you find in the <filename>/usr</filename> directory
+of the base system. But some details are different. This is because
+pkgsrc initially came from FreeBSD and had adopted its file system
+hierarchy. Later it was largely influenced by NetBSD. But no matter
+which operating system you are using pkgsrc with, you can expect the
+same layout for pkgsrc.</para>
+
+<para>There are mainly three root directories for pkgsrc:</para>
+
+<itemizedlist>
+
+<listitem><para><varname>LOCALBASE</varname> corresponds to the
+<filename>/usr</filename> directory in the base system. It is the
+<quote>main</quote> directory where the files are installed and contains
+the well-known subdirectories like <filename>bin</filename>,
+<filename>include</filename>, <filename>lib</filename>,
+<filename>share</filename> and
+<filename>sbin</filename>.</para></listitem>
+
+<listitem><para><varname>VARBASE</varname> corresponds to
+<filename>/var</filename> in the base system. Some programs (especially
+games, network daemons) need write access to it during normal
+operation.</para></listitem>
+
+<listitem><para><varname>PKG_SYSCONFDIR</varname> corresponds to
+<filename>/etc</filename> in the base system. It contains configuration
+files of the packages, as well as pkgsrc's <filename>mk.conf</filename>
+itself.</para></listitem>
+
+</itemizedlist>
+
+<sect1 id="files.localbase">
+<title>File system layout in <literal>${PREFIX}</literal></title>
+
+<para>The following directories exist in a typical pkgsrc installation
+in <filename>${PREFIX}</filename>.</para>
+
+<variablelist>
+
+<varlistentry><term><filename>bin</filename></term>
+<listitem><para>Contains executable programs that are intended to be
+directly used by the end user.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>emul</filename></term>
+<listitem><para>Contains files for the emulation layers of various other
+operating systems, especially for
+NetBSD.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>etc</filename> (the usual location of
+<filename>${PKG_SYSCONFDIR}</filename>)</term><listitem><para>Contains
+the configuration files.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>include</filename></term>
+<listitem><para>Contains headers for the C and C++ programming
+languages.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>info</filename></term>
+<listitem><para>Contains GNU info files of various
+packages.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>lib</filename></term>
+<listitem><para>Contains shared and static
+libraries.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>libdata</filename></term>
+<listitem><para>Contains data files that don't change after
+installation. Other data files belong into
+<filename>${VARBASE}</filename>.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>libexec</filename></term>
+<listitem><para>Contains programs that are not intended to be used by
+end users, such as helper programs or network
+daemons.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>libexec/cgi-bin</filename></term>
+<listitem><para>Contains programs that are intended to be executed as
+CGI scripts by a web server.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>man</filename> (the usual value of
+<filename>${PKGMANDIR}</filename>)</term><listitem><para>Contains brief
+documentation in form of manual pages.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>sbin</filename></term>
+<listitem><para>Contains programs that are intended to be used only by
+the super-user.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>share</filename></term>
+<listitem><para>Contains platform-independent data files that don't
+change after installation.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>share/doc</filename></term>
+<listitem><para>Contains documentation files provided by the
+packages.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>share/examples</filename></term>
+<listitem><para>Contains example files provided by the packages. Among
+others, the original configuration files are saved here and copied to
+<filename>${PKG_SYSCONFDIR}</filename> during
+installation.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>share/examples/rc.d</filename></term>
+<listitem><para>Contains the original files for rc.d
+scripts.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>var</filename> (the usual location of
+<filename>${VARBASE}</filename>)</term> <listitem><para>Contains files
+that may be modified after
+installation.</para></listitem></varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="files.varbase">
+<title>File system layout in <literal>${VARBASE}</literal></title>
+
+<variablelist>
+
+<varlistentry><term><filename>db/pkg</filename> (the usual location of
+<filename>${PKG_DBDIR}</filename>)</term><listitem><para>Contains
+information about the currently installed
+packages.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>games</filename></term>
+<listitem><para>Contains highscore
+files.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>log</filename></term>
+<listitem><para>Contains log files.</para></listitem></varlistentry>
+
+<varlistentry><term><filename>run</filename></term>
+<listitem><para>Contains informational files about daemons that are
+currently running.</para></listitem></varlistentry>
+
+</variablelist>
+
+</sect1>
+</chapter>
diff -r 263fdf089272 -r bc74b45a03d0 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml        Tue Sep 19 17:47:49 2006 +0000
+++ b/doc/guide/files/pkgsrc.xml        Tue Sep 19 17:50:38 2006 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.22 2006/09/01 16:35:39 jmmv Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.23 2006/09/19 17:50:38 rillig Exp $ -->
 
 
 <?xml version="1.0"?>
@@ -45,7 +45,7 @@
       <holder role="mailto:www%NetBSD.org@localhost";>The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.22 2006/09/01 16:35:39 jmmv Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.23 2006/09/19 17:50:38 rillig Exp $</pubdate>
 
     <abstract>
 
@@ -68,6 +68,7 @@
     &chap.using;
     &chap.configuring;
     &chap.binary;
+    &chap.files;
     &chap.faq;
   </part>