Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files doc/guide: merge debug chapter into cr...
details: https://anonhg.NetBSD.org/pkgsrc/rev/39dc26a9cb77
branches: trunk
changeset: 434636:39dc26a9cb77
user: rillig <rillig%pkgsrc.org@localhost>
date: Sat Jun 20 05:31:10 2020 +0000
description:
doc/guide: merge debug chapter into creating
That chapter was not really about debugging pkgsrc but about creating a
package.
diffstat:
doc/guide/files/Makefile | 3 +-
doc/guide/files/creating.xml | 67 +++++++++++++++++----
doc/guide/files/debug.xml | 130 -------------------------------------------
doc/guide/files/pkgsrc.xml | 5 +-
doc/guide/files/submit.xml | 4 +-
5 files changed, 57 insertions(+), 152 deletions(-)
diffs (truncated from 313 to 300 lines):
diff -r a2bc18308d87 -r 39dc26a9cb77 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile Sat Jun 20 04:52:26 2020 +0000
+++ b/doc/guide/files/Makefile Sat Jun 20 05:31:10 2020 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.20 2020/01/04 12:14:22 ryoon Exp $
+# $NetBSD: Makefile,v 1.21 2020/06/20 05:31:10 rillig Exp $
WEB_PREFIX?= ${.CURDIR}/../htdocs
DBX_XML_CATALOG?= ${SGML_PREFIX}/docbook/4.5/catalog.xml
@@ -15,7 +15,6 @@
SRCS+= creating.xml
SRCS+= components.xml
SRCS+= configuring.xml
-SRCS+= debug.xml
SRCS+= devfaq.xml
SRCS+= editing.xml
SRCS+= examples.xml
diff -r a2bc18308d87 -r 39dc26a9cb77 doc/guide/files/creating.xml
--- a/doc/guide/files/creating.xml Sat Jun 20 04:52:26 2020 +0000
+++ b/doc/guide/files/creating.xml Sat Jun 20 05:31:10 2020 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.33 2020/04/29 23:24:43 gutteridge Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.34 2020/06/20 05:31:10 rillig Exp $ -->
<chapter id="creating">
<title>Creating a new pkgsrc package from scratch</title>
@@ -10,15 +10,30 @@
<procedure>
-<step><para>First, install the packages <filename
-role="pkg">pkgtools/url2pkg</filename> and <filename
-role="pkg">pkgtools/pkglint</filename>.</para></step>
+<step><para>In your &mk.conf;, set <code>PKG_DEVELOPER=yes</code> to
+enable the basic quality checks.</para></step>
+
+<step><para>Install the package <filename
+role="pkg">meta-pkgs/pkg_developer</filename>, which among others will
+install the utilities <command>url2pkg</command>,
+<command>pkglint</command>, <command>pkgvi</command> and
+<command>mkpatches</command>:</para>
+
+<screen>&uprompt; <userinput>cd /usr/pkgsrc</userinput>
+&uprompt; <userinput>(cd meta-pkgs/pkg_developer && bmake update)</userinput></screen>
-<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>
+
+<step><para>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>
+
+<screen>&uprompt; <userinput>mkdir <replaceable>category</replaceable>/<replaceable>package</replaceable></userinput>
+&uprompt; <userinput>cd <replaceable>category</replaceable>/<replaceable>package</replaceable></userinput></screen>
+
+</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
@@ -26,7 +41,11 @@
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>
+manually:</para>
+
+<screen>&uprompt; <userinput>url2pkg <replaceable>https://www.example.org/packages/package-1.0.tar.gz</replaceable></userinput></screen>
+
+</step>
<step><para>Examine the extracted files to determine the dependencies of
your package. Ideally, this is mentioned in some
@@ -77,9 +96,8 @@
<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>
+--explain</command> or <command>pkglint -e</command>, which outputs
+additional explanations.</para></step>
<step><para>In many cases the package is not yet ready to build. You can
find instructions for the most common cases in the next section, <xref
@@ -94,7 +112,17 @@
<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>
+linkend="fixes"/>.</para>
+
+<para>If the extracted files from the package need to be fixed, run multiple rounds of these commands:</para>
+
+<screen>&uprompt; <userinput>make</userinput>
+&uprompt; <userinput>pkgvi ${WRKSRC}/some/file/that/does/not/compile</userinput>
+&uprompt; <userinput>mkpatches</userinput>
+&uprompt; <userinput>make mps</userinput>
+&uprompt; <userinput>make clean</userinput></screen>
+
+</step>
<step><para>When the package builds fine, the next step is to install
the package. Run <command>bmake install</command> and hope that
@@ -111,7 +139,7 @@
<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
+had 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
@@ -120,6 +148,15 @@
<step><para>Run <command>bmake package</command> to create a binary
package from the set of installed files.</para></step>
+<step><para>Run <command>bmake clean update</command> to run everything
+from above again in a single step, making sure that the PLIST is correct
+and the whole package is created as intended.</para></step>
+
+<step><para>Run <command>pkglint</command> to see if there's anything left to do.</para></step>
+
+<step><para>Commit the package to pkgsrc-wip or main pkgsrc; see <xref
+linkend="submit"/>.</para></step>
+
</procedure>
<sect1 id="creating.common">
diff -r a2bc18308d87 -r 39dc26a9cb77 doc/guide/files/debug.xml
--- a/doc/guide/files/debug.xml Sat Jun 20 04:52:26 2020 +0000
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,130 +0,0 @@
-<!-- $NetBSD: debug.xml,v 1.8 2020/02/24 21:13:56 rillig Exp $ -->
-
-<chapter id="debug">
- <title>Debugging</title>
-
- <para>To check out all the gotchas when building a package, here are
- the steps that I do in order to get a package working. Please note
- this is basically the same as what was explained in the previous
- sections, only with some debugging aids.</para>
-
- <itemizedlist>
- <listitem>
- <para>Be sure to set <varname>PKG_DEVELOPER=yes</varname> in &mk.conf;.</para>
- </listitem>
-
- <listitem>
- <para>Install <filename role="pkg">pkgtools/url2pkg</filename>,
- create a directory for a new package, change into it, then run
- <command>url2pkg</command>:</para>
-
- <screen>&cprompt; <userinput>mkdir /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput>
-&cprompt; <userinput>cd /usr/pkgsrc/<replaceable>category</replaceable>/<replaceable>examplepkg</replaceable></userinput>
-&cprompt; <userinput>url2pkg https://www.example.com/path/to/distfile.tar.gz</userinput></screen>
- </listitem>
-
- <listitem>
- <para>Edit the <filename>Makefile</filename> as requested.</para>
- </listitem>
-
- <listitem>
- <para>Fill in the <filename>DESCR</filename> file</para>
- </listitem>
-
- <listitem>
- <para>Run <command>make configure</command></para>
- </listitem>
-
- <listitem>
- <para>Add any dependencies glimpsed from documentation and the
- configure step to the package's
- <filename>Makefile</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Make the package compile, doing multiple rounds of</para>
-
- <screen>&cprompt; <userinput>make</userinput>
-&cprompt; <userinput>pkgvi ${WRKSRC}/some/file/that/does/not/compile</userinput>
-&cprompt; <userinput>mkpatches</userinput>
-&cprompt; <userinput>patchdiff</userinput>
-&cprompt; <userinput>mv ${WRKDIR}/.newpatches/* patches</userinput>
-&cprompt; <userinput>make mps</userinput>
-&cprompt; <userinput>make clean</userinput></screen>
-
- <para>Doing this step as non-root user will ensure that no files
- are modified that shouldn't be, especially during the build
- phase. <command>mkpatches</command>,
- <command>patchdiff</command> and <command>pkgvi</command> are
- from the <filename role="pkg">pkgtools/pkgdiff</filename>
- package.</para>
- </listitem>
-
- <listitem>
- <para>Look at the <filename>Makefile</filename>, fix if
- necessary; see <xref linkend="components.Makefile"/>.</para>
- </listitem>
-
- <listitem>
- <para>Generate a <filename>PLIST</filename>:</para>
-
- <screen>&rprompt; <userinput>make install</userinput>
-&rprompt; <userinput>make print-PLIST >PLIST</userinput>
-&rprompt; <userinput>make deinstall</userinput>
-&rprompt; <userinput>make install</userinput>
-&rprompt; <userinput>make deinstall</userinput></screen>
-
- <para>You usually need to be <username>root</username> to do
- this. Look if there are any files left:</para>
-
- <screen>&rprompt; <userinput>make print-PLIST</userinput></screen>
-
- <para>If this reveals any files that are missing in
- <filename>PLIST</filename>, add them.</para>
- </listitem>
-
- <listitem>
- <para>Now that the <filename>PLIST</filename> is OK, install the
- package again and make a binary package:</para>
-
- <screen>&rprompt; <userinput>make reinstall</userinput>
-&rprompt; <userinput>make package</userinput></screen>
- </listitem>
-
- <listitem>
- <para>Delete the installed package:</para>
-
- <screen>&rprompt; <userinput>pkg_delete <replaceable>examplepkg</replaceable></userinput></screen>
- </listitem>
-
- <listitem>
- <para>Repeat the above <command>make print-PLIST</command>
- command, which shouldn't find anything now:</para>
-
- <screen>&rprompt; <userinput>make print-PLIST</userinput></screen>
- </listitem>
-
- <listitem>
- <para>Reinstall the binary package:</para>
-
- <screen>&rprompt; <userinput>pkg_add .../<replaceable>examplepkg</replaceable>.tgz</userinput></screen>
- </listitem>
-
- <listitem>
- <para>Play with it. Make sure everything works.</para>
- </listitem>
-
- <listitem>
- <para>Run <command>pkglint</command> from <filename
- role="pkg">pkgtools/pkglint</filename>, and fix the problems it
- reports:</para>
-
- <screen>&rprompt; <userinput>pkglint</userinput></screen>
- </listitem>
-
- <listitem>
- <para>Submit (or commit, if you have cvs access); see <xref
- linkend="submit"/>.</para>
- </listitem>
- </itemizedlist>
-</chapter>
diff -r a2bc18308d87 -r 39dc26a9cb77 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml Sat Jun 20 04:52:26 2020 +0000
+++ b/doc/guide/files/pkgsrc.xml Sat Jun 20 05:31:10 2020 +0000
@@ -1,5 +1,5 @@
<?xml version="1.0"?>
-<!-- $NetBSD: pkgsrc.xml,v 1.37 2020/06/20 04:52:26 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $ -->
<!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.5-Based DocBook Extension//EN" [
@@ -47,7 +47,7 @@
<holder role="mailto:www%NetBSD.org@localhost";>The NetBSD Foundation, Inc</holder>
</copyright>
- <pubdate>$NetBSD: pkgsrc.xml,v 1.37 2020/06/20 04:52:26 rillig Exp $</pubdate>
+ <pubdate>$NetBSD: pkgsrc.xml,v 1.38 2020/06/20 05:31:10 rillig Exp $</pubdate>
<abstract>
@@ -97,7 +97,6 @@
&chap.pkginstall;
&chap.fixes;
&chap.gnome;
- &chap.debug;
&chap.submit;
&chap.devfaq;
</part>
diff -r a2bc18308d87 -r 39dc26a9cb77 doc/guide/files/submit.xml
--- a/doc/guide/files/submit.xml Sat Jun 20 04:52:26 2020 +0000
+++ b/doc/guide/files/submit.xml Sat Jun 20 05:31:10 2020 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: submit.xml,v 1.36 2020/04/29 23:09:48 gutteridge Exp $ -->
Home |
Main Index |
Thread Index |
Old Index