svn commit: r45542 - head/en_US.ISO8859-1/books/porters-handbook/testing
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 2 09:48:26 UTC 2014
Author: mat (ports committer)
Date: Tue Sep 2 09:48:25 2014
New Revision: 45542
URL: http://svnweb.freebsd.org/changeset/doc/45542
Log:
- Minor wording fixes. (igor -y)
- Mention poudriere, and poudriere-devel.
- Explain what the test build targets will do.
Differential Revision: https://reviews.freebsd.org/D654
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml
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 @@
</note>
<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>bsd.port.mk</filename> for the meaning of the string
produced.</para>
@@ -47,10 +47,10 @@
<sect1 xml:id="testing-portlint">
<title>Portlint</title>
- <para>Do check your work with <link
+ <para>Do check the port with <link
linkend="porting-portlint"><command>portlint</command></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
<link
linkend="testing-portlint"><command>portlint</command></link>
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>
</sect1>
@@ -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>
<sect1 xml:id="testing-tinderbox">
<title>Tinderbox</title>
- <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
xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere
website</link> for more details.</para>
More information about the svn-doc-all
mailing list