diff options
author | rillig <rillig> | 2006-06-01 08:39:03 +0000 |
---|---|---|
committer | rillig <rillig> | 2006-06-01 08:39:03 +0000 |
commit | 67d0bdf335eda3e4fd96c8e13911cb077765918a (patch) | |
tree | 77f7ab9e7716f103142ce3976fce6ee46c05948d /doc | |
parent | 6571f4e998e52553f39742c6c10387adf72a4c23 (diff) | |
download | pkgsrc-67d0bdf335eda3e4fd96c8e13911cb077765918a.tar.gz |
Added a chapter "creating a pkgsrc package" that serves as an
introduction to the developer's guide.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/guide/files/Makefile | 3 | ||||
-rw-r--r-- | doc/guide/files/chapters.ent | 3 | ||||
-rw-r--r-- | doc/guide/files/creating.xml | 103 | ||||
-rw-r--r-- | doc/guide/files/pkgsrc.xml | 10 |
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 + >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; |