svn commit: r43957 - head/en_US.ISO8859-1/books/porters-handbook/testing
Warren Block
wblock at FreeBSD.org
Sun Feb 16 03:32:26 UTC 2014
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>
More information about the svn-doc-all
mailing list