Date: Tue, 2 Sep 2014 09:48:26 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45542 - head/en_US.ISO8859-1/books/porters-handbook/testing Message-ID: <201409020948.s829mQE2027310@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409020948.s829mQE2027310>