Added a chapter "creating a pkgsrc package" that serves as an

introduction to the developer's guide.

4 files changed, 115 insertions, 4 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index 4cfaaab13aa..fdf034afe51 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.8 2006/05/24 07:55:59 mishka Exp $
+# $NetBSD: Makefile,v 1.9 2006/06/01 08:39:03 rillig Exp $
 
 WEB_PREFIX?=	${.CURDIR}/../htdocs
 
@@ -8,6 +8,7 @@ SRCS=	pkgsrc.xml
 SRCS+=	binary.xml
 SRCS+=	build.xml
 SRCS+=	buildlink.xml
+SRCS+=	creating.xml
 SRCS+=	components.xml
 SRCS+=	configuring.xml
 SRCS+=	debug.xml
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 6a9c76a0b15..b3dcfd499cb 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.11 2006/05/12 23:03:22 rillig Exp $
+	$NetBSD: chapters.ent,v 1.12 2006/06/01 08:39:03 rillig Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -15,6 +15,7 @@
 <!ENTITY chap.faq			SYSTEM "faq.xml">
 
 <!-- developer's guide -->
+<!ENTITY chap.creating			SYSTEM "creating.xml">
 <!ENTITY chap.components		SYSTEM "components.xml">
 <!ENTITY chap.makefile			SYSTEM "makefile.xml">
 <!ENTITY chap.plist			SYSTEM "plist.xml">
diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
new file mode 100644
index 00000000000..5606728d8ec
--- /dev/null
+++ b/doc/guide/files/creating.xml
@@ -0,0 +1,103 @@
+<!-- $NetBSD: creating.xml,v 1.1 2006/06/01 08:39:03 rillig Exp $ -->
+
+<chapter id="creating">
+<title>Creating a new pkgsrc package from scratch</title>
+
+	<para>When you find a package that is not yet in pkgsrc, you
+	most likely have a URL from where you can download the source
+	code. Starting with this URL, creating a package involves only a
+	few steps.</para>
+
+	<procedure>
+
+	<step><para>First, install the packages <filename
+	role="pkg">pkgtools/url2pkg</filename> and <filename
+	role="pkg">pkgtools/pkglint</filename>.</para></step>
+	
+	<step><para>Then, choose one of the top-level directories as the
+	category in which you want to place your package. You can also
+	create a directory of your own (maybe called
+	<filename>local</filename>). In that category directory, create
+	another directory for your package and change into
+	it.</para></step>
+
+	<step><para>Run the program <command>url2pkg</command>, which
+	will ask you for a URL. Enter the URL of the distribution file
+	(in most cases a <filename>.tar.gz</filename> file) and watch
+	how the basic ingredients of your package are created
+	automatically. The distribution file is extracted automatically
+	to fill in some details in the <filename>Makefile</filename>
+	that would otherwise have to be done manually.</para></step>
+
+	<step><para>Examine the extracted files to determine the
+	dependencies of your package. Ideally, this is mentioned in some
+	<filename>README</filename> file, but things may differ. For
+	each of these dependencies, look where it exists in pkgsrc, and
+	if there is a file called <filename>buildlink3.mk</filename> in
+	that directory, add a line to your package
+	<filename>Makefile</filename> which includes that file just
+	before the last line. If the <filename>buildlink3.mk</filename>
+	file does not exist, add a <varname>DEPENDS</varname> line to
+	the Makefile, which specifies the version of the dependency and
+	where it can be found in pkgsrc. This line should be placed in
+	the third paragraph. If the dependency is only needed for
+	building the package, but not when using it, use
+	<varname>BUILD_DEPENDS</varname> instead of
+	<varname>DEPENDS</varname>. Your package may then look like
+	this:</para>
+
+<programlisting>
+    [...]
+
+    BUILD_DEPENDS+= lua>=5.0:../../lang/lua
+    DEPENDS+=       screen-[0-9]*:../../misc/screen
+    DEPENDS+=       screen>=4.0:../../misc/screen
+
+    [...]
+
+    .include "../../<replaceable>category</replaceable>/<replaceable>package</replaceable>/buildlink3.mk"
+    .include "../../devel/glib2/buildlink3.mk"
+    .include "../../mk/bsd.pkg.mk"
+</programlisting>
+
+	</step>
+
+	<step><para>Run <command>pkglint</command> to see what things
+	still need to be done to make your package a <quote>good</quote>
+	one. If you don't know what pkglint's warnings want to tell you,
+	try <command>pkglint --explain</command> or <command>pkglint
+	-e</command>, which outputs additional
+	explanations.</para></step>
+
+	<step><para>Now, run <command>bmake</command> to build the
+	package. For the various things that can go wrong in this phase,
+	consult <xref linkend="fixes"/>.</para></step>
+
+	<step><para>When the package builds fine, the next step is to
+	install the package. Run <command>bmake install</command> and
+	hope that everything works.</para></step>
+
+	<step><para>Up to now, the file <filename>PLIST</filename>,
+	which contains a list of the files that are installed by the
+	package, is nearly empty. Run <command>bmake print-PLIST
+	&gt;PLIST</command> to generate a probably correct list. Check
+	the file using your preferred text editor to see if the list of
+	files looks plausible.</para></step>
+
+	<step><para>Run <command>pkglint</command> again to see if the
+	generated <filename>PLIST</filename> contains garbage or
+	not.</para></step>
+
+	<step><para>When you ran <command>bmake install</command>, the
+	package has been registered in the database of installed files,
+	but with an empty list of files. To fix this, run <command>bmake
+	deinstall</command> and <command>bmake install</command> again.
+	Now the package is registered with the list of files from
+	<filename>PLIST</filename>.</para></step>
+
+	<step><para>Run <command>bmake package</command> to create a
+	binary package from the set of installed files.</para></step>
+
+	</procedure>
+
+</chapter>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 098dab39d30..34dbe928cbe 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.18 2006/05/19 22:05:09 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.19 2006/06/01 08:39:03 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.18 2006/05/19 22:05:09 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.19 2006/06/01 08:39:03 rillig Exp $</pubdate>
 
     <abstract>
 
@@ -75,6 +75,12 @@
   <part id="developers-guide"> <?dbhtml filename="developers-guide.html"?>
     <title id="developers-guide.title">The pkgsrc developer's guide</title>
 
+	<partintro><para>This part of the book deals with creating and
+	modifying packages. It starts with a <quote>HOWTO</quote>-like
+	guide on creating a new package. The remaining chapters are more
+	like a reference manual for pkgsrc.</para></partintro>
+
+    &chap.creating;
     &chap.components;
     &chap.makefile;
     &chap.plist;