Whitespace-only fixes, translators please ignore.
This commit is contained in:
Warren Block
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
|
|
@ -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">
|
||||
<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>
|
||||
|
||||
<sect1 xml:id="make-describe">
|
||||
<title>Running <command>make describe</command></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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>
|
||||
<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>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><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>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>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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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.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>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><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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
<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>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>
|
||||
<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>
|
||||
<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>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue