svn commit: r45542 - head/en_US.ISO8859-1/books/porters-handbook/testing

Mathieu Arnold mat at
Tue Sep 2 09:48:26 UTC 2014

Author: mat (ports committer)
Date: Tue Sep  2 09:48:25 2014
New Revision: 45542

  - Minor wording fixes. (igor -y)
  - Mention poudriere, and poudriere-devel.
  - Explain what the test build targets will do.
  Differential Revision:
  Reviewed by:	wblock
  Sponsored by:	Absolight


Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml
--- head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml	Tue Sep  2 08:44:01 2014	(r45541)
+++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml	Tue Sep  2 09:48:25 2014	(r45542)
@@ -34,7 +34,7 @@
     <para>If <command>make describe</command> produces a string rather
-      than an error message, you are probably safe.  See
+      than an error message, everything is probably safe.  See
       <filename></filename> for the meaning of the string
@@ -47,10 +47,10 @@
   <sect1 xml:id="testing-portlint">
-    <para>Do check your work with <link
+    <para>Do check the port with <link
-      before you submit or commit it.  <command>portlint</command>
-      warns you about many common errors, both functional and
+      before submitting or committing it.  <command>portlint</command>
+      warns about many common errors, both functional and
       stylistic.  For a new (or repocopied) port,
       <command>portlint -A</command> is the most thorough; for an
       existing port, <command>portlint -C</command> is
@@ -71,14 +71,14 @@
       program is part of the Ports Collection.</para>
     <para><command>port</command> is the front-end script, which can
-      help you simplify the testing job.  Whenever you want to test a
-      new port or update an existing one, you can use
-      <command>port test</command> to test your port, including the
+      help simplify the testing job.  Whenever a new port or an update
+      to an existing one needs testing, use
+      <command>port test</command> to test the port, including the
       checking.  This command also detects and lists any files that
-      are not listed in <filename>pkg-plist</filename>.  See the
-      following example:</para>
+      are not listed in <filename>pkg-plist</filename>.  For
+      example:</para>
     <screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen>
@@ -90,7 +90,7 @@
     <para><varname>PREFIX</varname> determines where the port will be
       installed.  It defaults to <filename>/usr/local</filename>, but
       can be set by the user to a custom path like
-      <filename>/opt</filename>.  Your port must respect the value of
+      <filename>/opt</filename>.  The port must respect the value of
       this variable.</para>
     <para><varname>DESTDIR</varname>, if set by the user, determines
@@ -100,7 +100,7 @@
       <filename>DESTDIR/PREFIX</filename>, and register with the
       package database in <filename>DESTDIR/var/db/pkg</filename>.  As
       <varname>DESTDIR</varname> is handled automatically by the ports
-      infrastructure with &man.chroot.8;, you do not need any
+      infrastructure with &man.chroot.8;.  There is no need for
       modifications or any extra care to write
       <varname>DESTDIR</varname>-compliant ports.</para>
@@ -114,18 +114,18 @@
     <para>Avoiding hard-coded <filename>/usr/local</filename> paths in
       the source makes the port much more flexible and able to cater
       to the needs of other sites.  Often, this can be accomplished by
-      simply replacing occurrences of <filename>/usr/local</filename>
+      replacing occurrences of <filename>/usr/local</filename>
       in the port's various <filename>Makefile</filename>s with
       <literal>${PREFIX}</literal>.  This variable is
       automatically passed down to every stage of the build and
       install processes.</para>
-    <para>Make sure your application is not installing things in
+    <para>Make sure the application is not installing things in
       <filename>/usr/local</filename> instead of
       <varname>PREFIX</varname>.  A quick test for such hard-coded
       paths is:</para>
-    <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>
+    <screen>&prompt.user; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen>
     <para>If anything is installed outside of
       <varname>PREFIX</varname>, the package creation process will
@@ -134,24 +134,39 @@
     <para>In addition, it is worth checking the same with the stage
       directory support (see <xref linkend="staging"/>):</para>
-    <screen>&prompt.root; <userinput>make stage && make check-orphans && make package</userinput></screen>
+    <screen>&prompt.user; <userinput>make stage && make check-plist && make stage-qa && make package</userinput></screen>
+    <itemizedlist>
+      <listitem>
+	<para><buildtarget>check-plist</buildtarget> checks for files
+	  missing from the plist, and files in the plist that are not
+	  installed by the port.</para>
+      </listitem>
+      <listitem>
+	<para><buildtarget>stage-qa</buildtarget> checks for common
+	  problems like bad shebang, symlinks pointing outside the
+	  stage directory, setuid files, and non-stripped
+	  libraries...</para>
+      </listitem>
+    </itemizedlist>
     <para>These tests will not find hard-coded paths inside the port's
       files, nor will it verify that <varname>LOCALBASE</varname> is
       being used to correctly refer to files from other ports.  The
       temporarily-installed port in
-      <filename>/var/tmp/`make -V PORTNAME`</filename> should be
+      <filename>/var/tmp/`make -V PORTNAME`</filename> must be
       tested for proper operation to make sure there are no problems
       with paths.</para>
-    <para><varname>PREFIX</varname> should not be set explicitly in a
+    <para><varname>PREFIX</varname> must not be set explicitly in a
       port's <filename>Makefile</filename>.  Users installing the port
       may have set <varname>PREFIX</varname> to a custom location, and
-      the port should respect that setting.</para>
+      the port must respect that setting.</para>
     <para>Refer to programs and files from other ports with the
       variables mentioned above, not explicit pathnames.  For
-      instance, if your port requires a macro <literal>PAGER</literal>
+      instance, if the port requires a macro <literal>PAGER</literal>
       to have the full pathname of <command>less</command>, do not use
       a literal path of <filename>/usr/local/bin/less</filename>.
       Instead, use <literal>${LOCALBASE}</literal>:</para>
@@ -161,14 +176,23 @@
     <para>The path with <varname>LOCALBASE</varname> is more likely to
       still work if the system administrator has moved the whole
       <filename>/usr/local</filename> tree somewhere else.</para>
+    <tip>
+      <para>All these tests are done automatically when running
+	<command>poudriere testport</command> or <command>poudriere
+	  bulk -t</command>.  It is highly recommended that every
+	ports contributor install it, and tests all his ports with it.
+	See <xref linkend="testing-poudriere"/> for more
+	information.</para>
+    </tip>
   <sect1 xml:id="testing-tinderbox">
-    <para>If you are an avid ports contributor, you might want to take
+    <para>As an avid ports contributor, take
       a look at <application>Tinderbox</application>.  It is a
-      powerful system for building and testing ports.  You can install
+      powerful system for building and testing ports.  Install
       <application>Tinderbox</application> using
       <package role="port">ports-mgmt/tinderbox</package> port.  Be
       sure to read supplied documentation since the configuration is
@@ -188,6 +212,11 @@
       <application>Poudriere</application> can be installed with
       <package role="port">ports-mgmt/poudriere</package>.</para>
+    <para>There is also a <package
+	role="port">ports-mgmt/poudriere-devel</package> that often
+      has newer features that are mostly helpful when testing
+      ports.</para>
     <para>Visit the <link
 	website</link> for more details.</para>

More information about the svn-doc-all mailing list