os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes, translators please ignore.

Browse source
This commit is contained in:
Warren Block 2014-02-16 03:32:26 +00:00
parent 5dd073a3cb
commit f30d0c5ba0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43957
1 changed files with 155 additions and 161 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml
View file

@ -4,7 +4,9 @@
$FreeBSD$ $FreeBSD$
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="testing"> <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> <title>Testing the Port</title>
@ -13,10 +15,9 @@
<para>Several of the &os; port maintenance tools, such as <para>Several of the &os; port maintenance tools, such as
&man.portupgrade.1;, rely on a database called &man.portupgrade.1;, rely on a database called
<filename>/usr/ports/INDEX</filename> which keeps track of <filename>/usr/ports/INDEX</filename> which keeps track of such
such items as port dependencies. <filename>INDEX</filename> items as port dependencies. <filename>INDEX</filename> is
is created by the top-level created by the top-level <filename>ports/Makefile</filename> via
<filename>ports/Makefile</filename> via
<command>make index</command>, which descends into each port <command>make index</command>, which descends into each port
subdirectory and executes <command>make describe</command> subdirectory and executes <command>make describe</command>
there. Thus, if <command>make describe</command> fails in any there. Thus, if <command>make describe</command> fails in any
@ -24,18 +25,18 @@
people will quickly become unhappy.</para> people will quickly become unhappy.</para>
<note> <note>
<para>It is important to be able to generate this file no <para>It is important to be able to generate this file no matter
matter what options are present in what options are present in <filename>make.conf</filename>, so
<filename>make.conf</filename>, so please avoid doing things please avoid doing things such as using
such as using <literal>.error</literal> statements when (for <literal>.error</literal> statements when (for instance) a
instance) a dependency is not satisfied. (See dependency is not satisfied. (See
<xref linkend="dads-dot-error"/>.)</para> <xref linkend="dads-dot-error"/>.)</para>
</note> </note>
<para>If <command>make describe</command> produces a string <para>If <command>make describe</command> produces a string rather
rather than an error message, you are probably safe. See than an error message, you are probably safe. See
<filename>bsd.port.mk</filename> for the meaning of the <filename>bsd.port.mk</filename> for the meaning of the string
string produced.</para> produced.</para>
<para>Also note that running a recent version of <para>Also note that running a recent version of
<command>portlint</command> (as specified in the next section) <command>portlint</command> (as specified in the next section)
@ -55,24 +56,23 @@
existing port, <command>portlint -C</command> is existing port, <command>portlint -C</command> is
sufficient.</para> sufficient.</para>
<para>Since <command>portlint</command> uses heuristics to <para>Since <command>portlint</command> uses heuristics to try to
try to figure out errors, it can produce false positive figure out errors, it can produce false positive warnings. In
warnings. In addition, occasionally something that is addition, occasionally something that is flagged as a problem
flagged as a problem really cannot be done in any other really cannot be done in any other way due to limitations in the
way due to limitations in the ports framework. When in ports framework. When in doubt, the best thing to do is ask on
doubt, the best thing to do is ask on &a.ports;.</para> &a.ports;.</para>
</sect1> </sect1>
<sect1 xml:id="testing-porttools"> <sect1 xml:id="testing-porttools">
<title>Port Tools</title> <title>Port Tools</title>
<para>The <para>The <package role="port">ports-mgmt/porttools</package>
<package role="port">ports-mgmt/porttools</package>
program is part of the Ports Collection.</para> program is part of the Ports Collection.</para>
<para><command>port</command> is the front-end script, which can <para><command>port</command> is the front-end script, which can
help you simplify the testing job. Whenever you want to test help you simplify the testing job. Whenever you want to test a
a new port or update an existing one, you can use new port or update an existing one, you can use
<command>port test</command> to test your port, including the <command>port test</command> to test your port, including the
<link <link
linkend="testing-portlint"><command>portlint</command></link> linkend="testing-portlint"><command>portlint</command></link>
@ -87,21 +87,20 @@
<title><varname>PREFIX</varname> and <title><varname>PREFIX</varname> and
<varname>DESTDIR</varname></title> <varname>DESTDIR</varname></title>
<para><varname>PREFIX</varname> determines where the port will <para><varname>PREFIX</varname> determines where the port will be
be installed. It defaults to <filename>/usr/local</filename>, installed. It defaults to <filename>/usr/local</filename>, but
but can be set by the user to a custom path like can be set by the user to a custom path like
<filename>/opt</filename>. Your port must respect the value <filename>/opt</filename>. Your port must respect the value of
of this variable.</para> this variable.</para>
<para><varname>DESTDIR</varname>, if set by the user, determines <para><varname>DESTDIR</varname>, if set by the user, determines
the complete alternative environment, usually a jail or an the complete alternative environment, usually a jail or an
installed system mounted somewhere other than installed system mounted somewhere other than
<filename>/</filename>. A port will actually install into <filename>/</filename>. A port will actually install into
<filename>DESTDIR/PREFIX</filename>, <filename>DESTDIR/PREFIX</filename>, and register with the
and register with the package database in package database in <filename>DESTDIR/var/db/pkg</filename>. As
<filename>DESTDIR/var/db/pkg</filename>. <varname>DESTDIR</varname> is handled automatically by the ports
As <varname>DESTDIR</varname> is handled automatically by the infrastructure with &man.chroot.8;, you do not need any
ports infrastructure with &man.chroot.8;, you do not need any
modifications or any extra care to write modifications or any extra care to write
<varname>DESTDIR</varname>-compliant ports.</para> <varname>DESTDIR</varname>-compliant ports.</para>
@ -112,12 +111,11 @@
<varname>PREFIX</varname> will be <varname>LINUXBASE</varname> <varname>PREFIX</varname> will be <varname>LINUXBASE</varname>
(defaulting to <filename>/compat/linux</filename>).</para> (defaulting to <filename>/compat/linux</filename>).</para>
<para>Avoiding hard-coded <filename>/usr/local</filename> paths <para>Avoiding hard-coded <filename>/usr/local</filename> paths in
in the source makes the port much more flexible and able to the source makes the port much more flexible and able to cater
cater to the needs of other sites. Often, this can be to the needs of other sites. Often, this can be accomplished by
accomplished by simply replacing occurrences of simply replacing occurrences of <filename>/usr/local</filename>
<filename>/usr/local</filename> in the port's various in the port's various <filename>Makefile</filename>s with
<filename>Makefile</filename>s with
<literal>&dollar;{PREFIX}</literal>. This variable is <literal>&dollar;{PREFIX}</literal>. This variable is
automatically passed down to every stage of the build and automatically passed down to every stage of the build and
install processes.</para> install processes.</para>
@ -133,51 +131,48 @@
<varname>PREFIX</varname>, the package creation process will <varname>PREFIX</varname>, the package creation process will
complain that it cannot find the files.</para> complain that it cannot find the files.</para>
<para>In addition, it is worth checking the same with the <para>In addition, it is worth checking the same with the stage
stage directory support (see directory support (see <xref linkend="staging"/>):</para>
<xref linkend="staging"/>):</para>
<screen>&prompt.root; <userinput>make stage &amp;&amp; make check-orphans &amp;&amp; make package</userinput></screen> <screen>&prompt.root; <userinput>make stage &amp;&amp; make check-orphans &amp;&amp; make package</userinput></screen>
<para>These tests will not find hard-coded paths inside the <para>These tests will not find hard-coded paths inside the port's
port's files, nor will it verify that files, nor will it verify that <varname>LOCALBASE</varname> is
<varname>LOCALBASE</varname> is being used to correctly refer being used to correctly refer to files from other ports. The
to files from other ports. The temporarily-installed port in temporarily-installed port in
<filename>/var/tmp/`make -V PORTNAME`</filename> should be <filename>/var/tmp/`make -V PORTNAME`</filename> should be
tested for proper operation to make sure there tested for proper operation to make sure there are no problems
are no problems with paths.</para> with paths.</para>
<para><varname>PREFIX</varname> should not be set explicitly <para><varname>PREFIX</varname> should not be set explicitly in a
in a port's <filename>Makefile</filename>. Users installing port's <filename>Makefile</filename>. Users installing the port
the port may have set <varname>PREFIX</varname> to a custom may have set <varname>PREFIX</varname> to a custom location, and
location, and the port should respect that setting.</para> the port should respect that setting.</para>
<para>Refer to programs and files from other ports with the <para>Refer to programs and files from other ports with the
variables mentioned above, not explicit pathnames. For variables mentioned above, not explicit pathnames. For
instance, if your port requires a macro instance, if your port requires a macro <literal>PAGER</literal>
<literal>PAGER</literal> to have the full pathname of to have the full pathname of <command>less</command>, do not use
<command>less</command>, do not use a literal path of a literal path of <filename>/usr/local/bin/less</filename>.
<filename>/usr/local/bin/less</filename>. Instead, use Instead, use <literal>&dollar;{LOCALBASE}</literal>:</para>
<literal>&dollar;{LOCALBASE}</literal>:</para>
<programlisting>-DPAGER=\"&dollar;{LOCALBASE}/bin/less\"</programlisting> <programlisting>-DPAGER=\"&dollar;{LOCALBASE}/bin/less\"</programlisting>
<para>The path with <varname>LOCALBASE</varname> is more likely <para>The path with <varname>LOCALBASE</varname> is more likely to
to still work if the system administrator has moved the whole still work if the system administrator has moved the whole
<filename>/usr/local</filename> tree somewhere else.</para> <filename>/usr/local</filename> tree somewhere else.</para>
</sect1> </sect1>
<sect1 xml:id="testing-tinderbox"> <sect1 xml:id="testing-tinderbox">
<title>Tinderbox</title> <title>Tinderbox</title>
<para>If you are an avid ports contributor, you might want to <para>If you are an avid ports contributor, you might want to take
take a look at <application>Tinderbox</application>. It is a a look at <application>Tinderbox</application>. It is a
powerful system for building and testing ports. powerful system for building and testing ports. You can install
You can <application>Tinderbox</application> using
install <application>Tinderbox</application> using <package role="port">ports-mgmt/tinderbox</package> port. Be
<package role="port">ports-mgmt/tinderbox</package> port. sure to read supplied documentation since the configuration is
Be sure to read supplied documentation since the configuration not trivial.</para>
is not trivial.</para>
<para>Visit the <para>Visit the
<link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox <link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox
@ -197,5 +192,4 @@
xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere xlink:href="http://fossil.etoilebsd.net/poudriere">Poudriere
website</link> for more details.</para> website</link> for more details.</para>
</sect1> </sect1>
</chapter> </chapter>