Added a new chapter to the developer's guide that explains how to port

pkgsrc to new operating systems, how to add support for a compiler, and
maybe more.

3 files changed, 87 insertions, 3 deletions

diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 8900e6d6f95..ef751a7bcad 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.7 2006/01/13 17:42:33 reed Exp $
+	$NetBSD: chapters.ent,v 1.8 2006/02/18 01:46:43 rillig Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -26,6 +26,7 @@
 <!ENTITY chap.fixes			SYSTEM "fixes.xml">
 <!ENTITY chap.debug			SYSTEM "debug.xml">
 <!ENTITY chap.submit			SYSTEM "submit.xml">
+<!ENTITY chap.porting			SYSTEM "porting.xml">
 
 <!-- appendix -->
 <!ENTITY chap.examples			SYSTEM "examples.xml">
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 1bff11ad75f..fb5ddd4eced 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.11 2006/01/13 17:42:33 reed Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.12 2006/02/18 01:46:43 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.11 2006/01/13 17:42:33 reed Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.12 2006/02/18 01:46:43 rillig Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -82,6 +82,7 @@
     &chap.fixes;
     &chap.debug;
     &chap.submit;
+    &chap.porting;
   </part>
 
   <!-- appendix -->
diff --git a/doc/guide/files/porting.xml b/doc/guide/files/porting.xml
new file mode 100644
index 00000000000..80f501a98f5
--- /dev/null
+++ b/doc/guide/files/porting.xml
@@ -0,0 +1,82 @@
+<!-- $NetBSD: porting.xml,v 1.1 2006/02/18 01:46:43 rillig Exp $ -->
+
+<chapter id="porting">
+<title>Porting pkgsrc</title>
+
+	<para>The pkgsrc system has already been ported to many
+	operating systems, hardware architectures and compilers. This
+	chapter explains the necessary steps to make pkgsrc even more
+	portable.</para>
+
+<sect1 id="porting.opsys">
+<title>Porting pkgsrc to a new operating system</title>
+
+	<para>To port pkgsrc to a new operating system (called
+	<literal>MyOS</literal> in this example), you need to touch the
+	following files:</para>
+
+	<variablelist>
+
+	<varlistentry><term><filename>bootstrap/mods/mk/<replaceable>MyOS</replaceable>.sys.mk</filename></term>
+	<listitem><para>This file contains some basic definitions, for
+	example the name of the C
+	compiler.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/bsd.prefs.mk</filename></term>
+	<listitem><para>Insert code that defines the variables
+	<varname>OPSYS</varname>, <varname>OS_VERSION</varname>,
+	<varname>LOWER_OS_VERSION</varname>,
+	<varname>LOWER_VENDOR</varname>,
+	<varname>MACHINE_ARCH</varname>, <varname>OBJECT_FMT</varname>,
+	<varname>APPEND_ELF</varname>, and the other variables that
+	appear in this file.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/platform/MyOS.mk</filename></term>
+	<listitem><para>This file contains the platform-specific
+	definitions that are used by pkgsrc. Start by copying one of the
+	other files and edit it to your
+	needs.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/platform/MyOS.pkg.dist</filename></term>
+	<listitem><para>This file contains a list of directories,
+	together with their permission bits and ownership. These
+	directories will be created automatically with every package
+	that does not explicitly set <varname>NO_MTREE</varname>. There
+	have been some discussions about whether this file is needed at
+	all, but with no result.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/platform/MyOS.x11.dist</filename></term>
+	<listitem><para>Just copy one of the pre-existing x11.dist files
+	to your
+	<filename><replaceable>MyOS</replaceable>.x11.dist</filename>.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/tools/bootstrap.mk</filename></term>
+	<listitem><para>On some operating systems, the tools that are
+	provided with the base system are not good enough for pkgsrc.
+	For example, there are many versions of &man.sed.1; that have a
+	narrow limit on the line length they can process. Therefore
+	pkgsrc brings its own tools, which can be enabled
+	here.</para></listitem></varlistentry>
+
+	<varlistentry><term><filename>mk/tools/<replaceable>MyOS</replaceable>.mk</filename></term>
+	<listitem><para>This file defines the paths to all the tools
+	that are needed by one or the other package in pkgsrc, as well
+	as by pkgsrc itself. Find out where these tools are on your
+	platform and add them.</para></listitem></varlistentry>
+
+	</variablelist>
+
+	<para>Now, you should be able to build some basic packages, like
+	<filename role="pkg">lang/perl5</filename>, <filename
+	role="pkg">shells/bash</filename>.</para>
+
+</sect1>
+
+<sect1 id="porting.compiler">
+<title>Adding support for a new compiler</title>
+
+	<para>TODO</para>
+
+</sect1>
+
+</chapter>