diff options
author | rillig <rillig@pkgsrc.org> | 2006-10-21 20:39:24 +0000 |
---|---|---|
committer | rillig <rillig@pkgsrc.org> | 2006-10-21 20:39:24 +0000 |
commit | b9bf6caa6f2851c2f9922c9992bddde603e932c3 (patch) | |
tree | 2ba2cd5702f5101e2614dda6383e1303bae1b216 | |
parent | 278e980021f4837571f8da493cdb1f51f089d670 (diff) | |
download | pkgsrc-b9bf6caa6f2851c2f9922c9992bddde603e932c3.tar.gz |
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.
-rw-r--r-- | doc/guide/files/creating.xml | 253 |
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> + # $NetBSD$ + # + + 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> |