CVS commit: pkgsrc/doc/guide/files

["Roland Illig" <rillig%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   rillig
Date:           Sat Jun 20 05:31:10 UTC 2020

Modified Files:
        pkgsrc/doc/guide/files: Makefile creating.xml pkgsrc.xml submit.xml
Removed Files:
        pkgsrc/doc/guide/files: debug.xml

Log Message:
doc/guide: merge debug chapter into creating

That chapter was not really about debugging pkgsrc but about creating a
package.


To generate a diff of this commit:
cvs rdiff -u -r1.20 -r1.21 pkgsrc/doc/guide/files/Makefile
cvs rdiff -u -r1.33 -r1.34 pkgsrc/doc/guide/files/creating.xml
cvs rdiff -u -r1.8 -r0 pkgsrc/doc/guide/files/debug.xml
cvs rdiff -u -r1.37 -r1.38 pkgsrc/doc/guide/files/pkgsrc.xml
cvs rdiff -u -r1.36 -r1.37 pkgsrc/doc/guide/files/submit.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/files/Makefile
diff -u pkgsrc/doc/guide/files/Makefile:1.20 pkgsrc/doc/guide/files/Makefile:1.21
--- pkgsrc/doc/guide/files/Makefile:1.20        Sat Jan  4 12:14:22 2020
+++ pkgsrc/doc/guide/files/Makefile     Sat Jun 20 05:31:10 2020
@@ -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+=        bulk.xml
 SRCS+= creating.xml
 SRCS+= components.xml
 SRCS+= configuring.xml
-SRCS+= debug.xml
 SRCS+= devfaq.xml
 SRCS+= editing.xml
 SRCS+= examples.xml

Index: pkgsrc/doc/guide/files/creating.xml
diff -u pkgsrc/doc/guide/files/creating.xml:1.33 pkgsrc/doc/guide/files/creating.xml:1.34
--- pkgsrc/doc/guide/files/creating.xml:1.33    Wed Apr 29 23:24:43 2020
+++ pkgsrc/doc/guide/files/creating.xml Sat Jun 20 05:31:10 2020
@@ -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 @@ 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>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 &amp;&amp; bmake update)</userinput></screen>
+
+</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 @@ you for a URL. Enter the URL of the dist
 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 @@ DEPENDS+=       screen>=4.0:../../misc/s
 <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 @@ directory, which may become wrong after 
 
 <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 @@ files looks plausible.</para></step>
 <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 @@ registered with the list of files from
 <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">

Index: pkgsrc/doc/guide/files/pkgsrc.xml
diff -u pkgsrc/doc/guide/files/pkgsrc.xml:1.37 pkgsrc/doc/guide/files/pkgsrc.xml:1.38
--- pkgsrc/doc/guide/files/pkgsrc.xml:1.37      Sat Jun 20 04:52:26 2020
+++ pkgsrc/doc/guide/files/pkgsrc.xml   Sat Jun 20 05:31:10 2020
@@ -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>

Index: pkgsrc/doc/guide/files/submit.xml
diff -u pkgsrc/doc/guide/files/submit.xml:1.36 pkgsrc/doc/guide/files/submit.xml:1.37
--- pkgsrc/doc/guide/files/submit.xml:1.36      Wed Apr 29 23:09:48 2020
+++ pkgsrc/doc/guide/files/submit.xml   Sat Jun 20 05:31:10 2020
@@ -1,4 +1,4 @@
-<!-- $NetBSD: submit.xml,v 1.36 2020/04/29 23:09:48 gutteridge Exp $ -->
+<!-- $NetBSD: submit.xml,v 1.37 2020/06/20 05:31:10 rillig Exp $ -->
 
 <chapter id="submit"> <?dbhtml filename="submit.html"?>
 <title>Submitting and Committing</title>
@@ -20,7 +20,7 @@
 <title>Submitting source packages (for non-NetBSD-developers)</title>
 
        <para>First, check that your package is complete, compiles and
-       runs well; see <xref linkend="debug"/> and the rest of this
+       runs well; see <xref linkend="creating"/> and the rest of this
        document. Next, generate an uuencoded gzipped &man.tar.1;
        archive that contains all files that make up the package.
        Finally, send this package to the pkgsrc bug tracking system,