Added an example section to the "creating a package" chapter, which

explains how I created a nontrivial package, www/nvu. It includes many
pitfalls that have never been documented before.

1 files changed, 252 insertions, 1 deletions

diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index ccda5a5f9ff..8f978885fb4 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.4 2006/10/21 11:58:18 rillig Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.5 2006/10/21 20:39:24 rillig Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -128,4 +128,255 @@ settings that are typical of KDE packages.</para>
 </sect2>
 
 </sect1>
+
+<sect1 id="creating.examples">
+<title>Examples</title>
+
+<sect2 id="creating.nvu">
+<title>How the www/nvu package came into pkgsrc</title>
+
+<sect3 id="creating.nvu.init">
+<title>The initial package</title>
+
+<para>Looking at the file <filename>pkgsrc/doc/TODO</filename>, I saw
+that the <quote>nvu</quote> package has not yet been imported into
+pkgsrc. As the description says it has to do with the web, the obvious
+choice for the category is <quote>www</quote>.</para>
+
+<programlisting>
+    &uprompt; mkdir www/nvu
+    &uprompt; cd www/nvu
+</programlisting>
+
+<para>The web site says that the sources are available as a tar file, so
+I fed that URL to the <command>url2pkg</command> program:</para>
+
+<programlisting>
+    &uprompt; url2pkg http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
+</programlisting>
+
+<para>My editor popped up, and I added a <varname>PKGNAME</varname> line
+below the <varname>DISTNAME</varname> line, as the package name should
+not have the word <quote>sources</quote> in it. I also filled in the
+<varname>MAINTAINER</varname>, <varname>HOMEPAGE</varname> and
+<varname>COMMENT</varname> fields. Then the package
+<filename>Makefile</filename> looked like that:</para>
+
+<programlisting>
+    # &#36;NetBSD&#36;
+    #
+
+    DISTNAME=       nvu-1.0-sources
+    PKGNAME=        nvu-1.0
+    CATEGORIES=     www
+    MASTER_SITES=   http://cvs.nvu.com/download/
+    EXTRACT_SUFX=   .tar.bz2
+
+    MAINTAINER=     rillig@NetBSD.org
+    HOMEPAGE=       http://cvs.nvu.com/
+    COMMENT=        Web Authoring System
+
+    # url2pkg-marker (please do not remove this line.)
+    .include "../../mk/bsd.pkg.mk"
+</programlisting>
+
+<para>Then, I quit the editor and watched pkgsrc downloading a large
+source archive:</para>
+
+<programlisting>
+    url2pkg> Running "make makesum" ...
+    => Required installed package digest>=20010302: digest-20060826 found
+    => Fetching nvu-1.0-sources.tar.bz2
+    Requesting http://cvs.nvu.com/download/nvu-1.0-sources.tar.bz2
+    100% |*************************************| 28992 KB  150.77 KB/s    00:00 ETA
+    29687976 bytes retrieved in 03:12 (150.77 KB/s)
+    url2pkg> Running "make extract" ...
+    => Required installed package digest>=20010302: digest-20060826 found
+    => Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+    => Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+    work.bacc -> /tmp/roland/pkgsrc/www/nvu/work.bacc
+    ===> Installing dependencies for nvu-1.0
+    ===> Overriding tools for nvu-1.0
+    ===> Extracting for nvu-1.0
+    url2pkg> Adjusting the Makefile.
+
+    Remember to correct CATEGORIES, HOMEPAGE, COMMENT, and DESCR when you're done!
+
+    Good luck! (See pkgsrc/doc/pkgsrc.txt for some more help :-)
+</programlisting>
+
+</sect3>
+
+<sect3 id="creating.nvu.problems">
+<title>Fixing all kinds of problems to make the package work</title>
+
+<para>Now that the package has been extracted, let's see what's inside
+it. The package has a <filename>README.txt</filename>, but that only
+says something about mozilla, so it's probably useless for seeing what
+dependencies this package has. But since there is a GNU configure script
+in the package, let's hope that it will complain about everything it
+needs.</para>
+
+<programlisting>
+    &uprompt; bmake
+    => Required installed package digest>=20010302: digest-20060826 found
+    => Checksum SHA1 OK for nvu-1.0-sources.tar.bz2
+    => Checksum RMD160 OK for nvu-1.0-sources.tar.bz2
+    ===> Patching for nvu-1.0
+    ===> Creating toolchain wrappers for nvu-1.0
+    ===> Configuring for nvu-1.0
+    [...]
+    configure: error: Perl 5.004 or higher is required.
+    [...]
+    WARNING: Please add USE_TOOLS+=perl to the package Makefile.
+    [...]
+</programlisting>
+
+<para>That worked quite well. So I opened the package Makefile in my
+editor, and since it already has a <varname>USE_TOOLS</varname> line, I
+just appended <quote>perl</quote> to it. Since the dependencies of the
+package have changed now, and since a perl wrapper is automatically
+installed in the <quote>tools</quote> phase, I need to build the package
+from scratch.</para>
+
+<programlisting>
+    &uprompt; bmake clean
+    ===> Cleaning for nvu-1.0
+    &uprompt; bmake
+    [...]
+    *** /tmp/roland/pkgsrc/www/nvu/work.bacc/.tools/bin/make is not \
+    GNU Make.  You will not be able to build Mozilla without GNU Make.
+    [...]
+</programlisting>
+
+<para>So I added <quote>gmake</quote> to the
+<varname>USE_TOOLS</varname> line and tried again (from scratch).</para>
+
+<programlisting>
+    [...]
+    checking for GTK - version >= 1.2.0... no
+    *** Could not run GTK test program, checking why...
+    [...]
+</programlisting>
+
+<para>Now to the other dependencies. The first question is: Where is the
+GTK package hidden in pkgsrc?</para>
+
+<programlisting>
+    &uprompt; echo ../../*/gtk*
+    [many packages ...]
+    &uprompt; echo ../../*/gtk
+    ../../x11/gtk
+    &uprompt; echo ../../*/gtk2
+    ../../x11/gtk2
+    &uprompt; echo ../../*/gtk2/bui*
+    ../../x11/gtk2/buildlink3.mk
+</programlisting>
+
+<para>The first try was definitely too broad. The second one had exactly
+one result, which is very good. But there is one pitfall with GNOME
+packages. Before GNOME 2 had been released, there were already many
+GNOME 1 packages in pkgsrc. To be able to continue to use these
+packages, the GNOME 2 packages were imported as separate packages, and
+their names usually have a <quote>2</quote> appended. So I checked
+whether this was the case here, and indeed it was.</para>
+
+<para>Since the GTK2 package has a <filename>buildlink3.mk</filename>
+file, adding the dependency is very easy. I just inserted an
+<literal>.include</literal> line before the last line of the package
+<filename>Makefile</filename>, so that it now looks like this:</para>
+
+<programlisting>
+    [...]
+    .include "../../x11/gtk2/buildlink3.mk"
+    .include "../../mk/bsd.pkg.mk
+</programlisting>
+
+<para>After another <command>bmake clean && bmake</command>, the answer
+was:</para>
+
+<programlisting>
+    [...]
+    checking for gtk-config... /home/roland/pkg/bin/gtk-config
+    checking for GTK - version >= 1.2.0... no
+    *** Could not run GTK test program, checking why...
+    *** The test program failed to compile or link. See the file config.log for the
+    *** exact error that occured. This usually means GTK was incorrectly installed
+    *** or that you have moved GTK since it was installed. In the latter case, you
+    *** may want to edit the gtk-config script: /home/roland/pkg/bin/gtk-config
+    configure: error: Test for GTK failed.
+    [...]
+</programlisting>
+
+<para>In this particular case, the assumption that <quote>every package
+prefers GNOME 2</quote> had been wrong. The first of the lines above
+told me that this package really wanted to have the GNOME 1 version of
+GTK. If the package had looked for GTK2, it would have looked for
+<command>pkg-config</command> instead of <command>gtk-config</command>.
+So I changed the <literal>x11/gtk2</literal> to
+<literal>x11/gtk</literal> in the package <filename>Makefile</filename>,
+and tried again.</para>
+
+<programlisting>
+    [...]
+    cc -o xpidl.o -c -DOSTYPE=\"NetBSD3\" -DOSARCH=\"NetBSD\"   -I../../../dist/include/xpcom -I../../../dist/include -I/tmp/roland/pkgsrc/www/nvu/work.bacc/mozilla/dist/include/nspr     -I/usr/X11R6/include   -fPIC -DPIC -I/home/roland/pkg/include -I/usr/include  -I/usr/X11R6/include -Wall -W -Wno-unused -Wpointer-arith -Wcast-align -Wno-long-long -pedantic -O2 -I/home/roland/pkg/include -I/usr/include -Dunix -pthread -pipe  -DDEBUG -D_DEBUG -DDEBUG_roland -DTRACING -g -I/home/roland/pkg/include/glib/glib-1.2 -I/home/roland/pkg/lib/glib/include -I/usr/pkg/include/orbit-1.0   -I/home/roland/pkg/include -I/usr/include  -I/usr/X11R6/include -include ../../../mozilla-config.h -DMOZILLA_CLIENT -Wp,-MD,.deps/xpidl.pp xpidl.c
+    In file included from xpidl.c:42:
+    xpidl.h:53:24: libIDL/IDL.h: No such file or directory
+    In file included from xpidl.c:42:
+    xpidl.h:132: error: parse error before "IDL_ns"
+    [...]
+</programlisting>
+
+<para>The package still does not find all of its dependencies. Now the
+question is: Which package provides the
+<filename>libIDL/IDL.h</filename> header file?</para>
+
+<programlisting>
+    &uprompt; echo ../../*/*idl*
+    ../../devel/py-idle ../../wip/idled ../../x11/acidlaunch
+    &uprompt; echo ../../*/*IDL*
+    ../../net/libIDL
+</programlisting>
+
+<para>Let's take the one from the second try. So I included the
+<filename>../../net/libIDL/buildlink3.mk</filename> file and tried
+again. But the error didn't change. After digging through some of the
+code, I concluded that the build process of the package was broken and
+couldn't have ever worked, but since the Mozilla source tree is quite
+large, I didn't want to fix it. So I added the following to the package
+<filename>Makefile</filename> and tried again:</para>
+
+<programlisting>
+    CPPFLAGS+=              -I${BUILDLINK_PREFIX.libIDL}/include/libIDL-2.0
+    BUILDLINK_TRANSFORM+=   -l:IDL:IDL-2
+</programlisting>
+
+<para>The latter line is needed because the package expects the library
+<filename>libIDL.so</filename>, but only
+<filename>libIDL-2.so</filename> is available. So I told the compiler
+wrapper to rewrite that on the fly.</para>
+
+<para>The next problem was related to a recent change of the FreeType
+interface. I looked up in <filename role="pkg">www/seamonkey</filename>
+which patch files were relevant for this issue and copied them to the
+<filename>patches</filename> directory. Then I retried, fixed the
+patches so that they applied cleanly and retried again. This time,
+everything worked.</para>
+
+</sect3>
+
+<sect3 id="creating.nvu.inst">
+<title>Installing the package</title>
+
+<programlisting>
+    &uprompt; bmake CHECK_FILES=no install
+    [...]
+    &uprompt; bmake print-PLIST >PLIST
+    &uprompt; bmake deinstall
+    &uprompt; bmake install
+</programlisting>
+
+</sect3>
+</sect2>
+</sect1>
 </chapter>