Date: Sun, 16 Feb 2014 03:32:26 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43957 - head/en_US.ISO8859-1/books/porters-handbook/testing Message-ID: <201402160332.s1G3WQ9I079422@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Feb 16 03:32:26 2014 New Revision: 43957 URL: http://svnweb.freebsd.org/changeset/doc/43957 Log: Whitespace-only fixes, translators please ignore. 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 Sun Feb 16 03:25:22 2014 (r43956) +++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Sun Feb 16 03:32:26 2014 (r43957) @@ -4,198 +4,192 @@ $FreeBSD$ --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="testing"> - - <title>Testing the Port</title> - - <sect1 xml:id="make-describe"> - <title>Running <command>make describe</command></title> - - <para>Several of the &os; port maintenance tools, such as - &man.portupgrade.1;, rely on a database called - <filename>/usr/ports/INDEX</filename> which keeps track of - such items as port dependencies. <filename>INDEX</filename> - is created by the top-level - <filename>ports/Makefile</filename> via - <command>make index</command>, which descends into each port - subdirectory and executes <command>make describe</command> - there. Thus, if <command>make describe</command> fails in any - port, no one can generate <filename>INDEX</filename>, and many - people will quickly become unhappy.</para> - - <note> - <para>It is important to be able to generate this file no - matter what options are present in - <filename>make.conf</filename>, so please avoid doing things - such as using <literal>.error</literal> statements when (for - instance) a dependency is not satisfied. (See - <xref linkend="dads-dot-error"/>.)</para> - </note> - - <para>If <command>make describe</command> produces a string - rather than an error message, you are probably safe. See - <filename>bsd.port.mk</filename> for the meaning of the - string produced.</para> - - <para>Also note that running a recent version of - <command>portlint</command> (as specified in the next section) - will cause <command>make describe</command> to be run - automatically.</para> - </sect1> - - <sect1 xml:id="testing-portlint"> - <title>Portlint</title> - - <para>Do check your work 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 - stylistic. For a new (or repocopied) port, - <command>portlint -A</command> is the most thorough; for an - existing port, <command>portlint -C</command> is - sufficient.</para> - - <para>Since <command>portlint</command> uses heuristics to - try to figure out errors, it can produce false positive - warnings. In addition, occasionally something that is - flagged as a problem really cannot be done in any other - way due to limitations in the ports framework. When in - doubt, the best thing to do is ask on &a.ports;.</para> - </sect1> - - <sect1 xml:id="testing-porttools"> - <title>Port Tools</title> - - <para>The - <package role="port">ports-mgmt/porttools</package> - 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 - <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> - - <screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen> - </sect1> - - <sect1 xml:id="porting-prefix"> - <title><varname>PREFIX</varname> and - <varname>DESTDIR</varname></title> - - <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 this variable.</para> - - <para><varname>DESTDIR</varname>, if set by the user, determines - the complete alternative environment, usually a jail or an - installed system mounted somewhere other than - <filename>/</filename>. A port will actually install into - <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 - modifications or any extra care to write - <varname>DESTDIR</varname>-compliant ports.</para> - - <para>The value of <varname>PREFIX</varname> will be set to - <varname>LOCALBASE</varname> (defaulting to - <filename>/usr/local</filename>). If - <varname>USE_LINUX_PREFIX</varname> is set, - <varname>PREFIX</varname> will be <varname>LINUXBASE</varname> - (defaulting to <filename>/compat/linux</filename>).</para> - - <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> 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 - <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> - - <para>If anything is installed outside of - <varname>PREFIX</varname>, the package creation process will - complain that it cannot find the files.</para> - - <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> - - <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 - 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 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> - - <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> 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> - - <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - - <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> - </sect1> - - <sect1 xml:id="testing-tinderbox"> - <title>Tinderbox</title> - - <para>If you are an avid ports contributor, you might want to - take a look at <application>Tinderbox</application>. It is a - powerful system for building and testing ports. - You can - install <application>Tinderbox</application> using - <package role="port">ports-mgmt/tinderbox</package> port. - Be sure to read supplied documentation since the configuration - is not trivial.</para> - - <para>Visit the - <link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox - website</link> for more details.</para> - </sect1> - - <sect1 xml:id="testing-poudriere"> - <title>Poudriere</title> - - <para>As a ports contributor, consider installing - <application>poudriere</application>. It is a powerful - system for building and testing ports. - <application>Poudriere</application> can be installed with - <package role="port">ports-mgmt/poudriere</package>.</para> - - <para>Visit the <link - xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere - website</link> for more details.</para> - </sect1> - </chapter> - +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="testing"> + + <title>Testing the Port</title> + + <sect1 xml:id="make-describe"> + <title>Running <command>make describe</command></title> + + <para>Several of the &os; port maintenance tools, such as + &man.portupgrade.1;, rely on a database called + <filename>/usr/ports/INDEX</filename> which keeps track of such + items as port dependencies. <filename>INDEX</filename> is + created by the top-level <filename>ports/Makefile</filename> via + <command>make index</command>, which descends into each port + subdirectory and executes <command>make describe</command> + there. Thus, if <command>make describe</command> fails in any + port, no one can generate <filename>INDEX</filename>, and many + people will quickly become unhappy.</para> + + <note> + <para>It is important to be able to generate this file no matter + what options are present in <filename>make.conf</filename>, so + please avoid doing things such as using + <literal>.error</literal> statements when (for instance) a + dependency is not satisfied. (See + <xref linkend="dads-dot-error"/>.)</para> + </note> + + <para>If <command>make describe</command> produces a string rather + than an error message, you are probably safe. See + <filename>bsd.port.mk</filename> for the meaning of the string + produced.</para> + + <para>Also note that running a recent version of + <command>portlint</command> (as specified in the next section) + will cause <command>make describe</command> to be run + automatically.</para> + </sect1> + + <sect1 xml:id="testing-portlint"> + <title>Portlint</title> + + <para>Do check your work 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 + stylistic. For a new (or repocopied) port, + <command>portlint -A</command> is the most thorough; for an + existing port, <command>portlint -C</command> is + sufficient.</para> + + <para>Since <command>portlint</command> uses heuristics to try to + figure out errors, it can produce false positive warnings. In + addition, occasionally something that is flagged as a problem + really cannot be done in any other way due to limitations in the + ports framework. When in doubt, the best thing to do is ask on + &a.ports;.</para> + </sect1> + + <sect1 xml:id="testing-porttools"> + <title>Port Tools</title> + + <para>The <package role="port">ports-mgmt/porttools</package> + 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 + <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> + + <screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen> + </sect1> + + <sect1 xml:id="porting-prefix"> + <title><varname>PREFIX</varname> and + <varname>DESTDIR</varname></title> + + <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 + this variable.</para> + + <para><varname>DESTDIR</varname>, if set by the user, determines + the complete alternative environment, usually a jail or an + installed system mounted somewhere other than + <filename>/</filename>. A port will actually install into + <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 + modifications or any extra care to write + <varname>DESTDIR</varname>-compliant ports.</para> + + <para>The value of <varname>PREFIX</varname> will be set to + <varname>LOCALBASE</varname> (defaulting to + <filename>/usr/local</filename>). If + <varname>USE_LINUX_PREFIX</varname> is set, + <varname>PREFIX</varname> will be <varname>LINUXBASE</varname> + (defaulting to <filename>/compat/linux</filename>).</para> + + <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> + 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 + <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> + + <para>If anything is installed outside of + <varname>PREFIX</varname>, the package creation process will + complain that it cannot find the files.</para> + + <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> + + <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 + 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 + 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> + + <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> + 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> + + <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> + + <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> + </sect1> + + <sect1 xml:id="testing-tinderbox"> + <title>Tinderbox</title> + + <para>If you are an avid ports contributor, you might want to take + a look at <application>Tinderbox</application>. It is a + powerful system for building and testing ports. You can install + <application>Tinderbox</application> using + <package role="port">ports-mgmt/tinderbox</package> port. Be + sure to read supplied documentation since the configuration is + not trivial.</para> + + <para>Visit the + <link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox + website</link> for more details.</para> + </sect1> + + <sect1 xml:id="testing-poudriere"> + <title>Poudriere</title> + + <para>As a ports contributor, consider installing + <application>poudriere</application>. It is a powerful + system for building and testing ports. + <application>Poudriere</application> can be installed with + <package role="port">ports-mgmt/poudriere</package>.</para> + + <para>Visit the <link + xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere + website</link> for more details.</para> + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402160332.s1G3WQ9I079422>