Added a new chapter to the pkgsrc user's guide, which describes the file

system layout of pkgsrc.

4 files changed, 150 insertions, 4 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index e0986e7ef09..1f0b650281d 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -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+=	devfaq.xml
 SRCS+=	editing.xml
 SRCS+=	examples.xml
 SRCS+=	faq.xml
+SRCS+=	files.xml
 SRCS+=	fixes.xml
 SRCS+=	ftp-layout.xml
 SRCS+=	getting.xml
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index e0321a1345b..dd47e7d89e7 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -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 --git a/doc/guide/files/files.xml b/doc/guide/files/files.xml
new file mode 100644
index 00000000000..fd68ea73217
--- /dev/null
+++ b/doc/guide/files/files.xml
@@ -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 --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 09216d85897..9f89de6de9f 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -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">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>