Differential D654 Diff 1329 en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml

Changeset View

Standalone View

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

Show All 28 Lines	<chapter xmlns="http://docbook.org/ns/docbook"
what options are present in <filename>make.conf</filename>, so		what options are present in <filename>make.conf</filename>, so
please avoid doing things such as using		please avoid doing things such as using
<literal>.error</literal> statements when (for instance) a		<literal>.error</literal> statements when (for 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 rather		<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		<filename>bsd.port.mk</filename> for the meaning of the 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)
will cause <command>make describe</command> to be run		will cause <command>make describe</command> to be run
automatically.</para>		automatically.</para>
</sect1>		</sect1>

<sect1 xml:id="testing-portlint">		<sect1 xml:id="testing-portlint">
<title>Portlint</title>		<title>Portlint</title>

<para>Do check your work with <link		<para>Do check the port with <link
linkend="porting-portlint"><command>portlint</command></link>		linkend="porting-portlint"><command>portlint</command></link>
before you submit or commit it. <command>portlint</command>		before submitting or committing it. <command>portlint</command>
warns you about many common errors, both functional and		warns about many common errors, both functional and
stylistic. For a new (or repocopied) port,		stylistic. For a new (or repocopied) port,
<command>portlint -A</command> is the most thorough; for an		<command>portlint -A</command> is the most thorough; for an
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 try to		<para>Since <command>portlint</command> uses heuristics to try to
figure out errors, it can produce false positive warnings. In		figure out errors, it can produce false positive warnings. In
addition, occasionally something that is flagged as a problem		addition, occasionally something that is flagged as a problem
really cannot be done in any other way due to limitations in the		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		ports framework. When in 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 <package role="port">ports-mgmt/porttools</package>		<para>The <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 a		help simplify the testing job. Whenever a new port or an update
new port or update an existing one, you can use		to an existing one needs testing, use
		wblockUnsubmitted Not Done Inline Actions s/to/to an/ wblock: s/to/to an/
<command>port test</command> to test your port, including the		<command>port test</command> to test the port, including the
<link		<link
linkend="testing-portlint"><command>portlint</command></link>		linkend="testing-portlint"><command>portlint</command></link>
checking. This command also detects and lists any files that		checking. This command also detects and lists any files that
are not listed in <filename>pkg-plist</filename>. See the		are not listed in <filename>pkg-plist</filename>. For
following example:</para>		example:</para>
		wblockUnsubmitted Not Done Inline Actions Nice! wblock: Nice!

<screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen>		<screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen>
</sect1>		</sect1>

<sect1 xml:id="porting-prefix">		<sect1 xml:id="porting-prefix">
<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 be		<para><varname>PREFIX</varname> determines where the port will be
installed. It defaults to <filename>/usr/local</filename>, but		installed. It defaults to <filename>/usr/local</filename>, 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 of		<filename>/opt</filename>. The port must respect the value 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>, and register with the		<filename>DESTDIR/PREFIX</filename>, and register with the
package database in <filename>DESTDIR/var/db/pkg</filename>. As		package database in <filename>DESTDIR/var/db/pkg</filename>. As
<varname>DESTDIR</varname> is handled automatically by the ports		<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
		wblockUnsubmitted Not Done Inline Actions infrastructure with &man.chroot.8;. There is no need for wblock: infrastructure with &man.chroot.8;. There is no need for
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>

<para>The value of <varname>PREFIX</varname> will be set to		<para>The value of <varname>PREFIX</varname> will be set to
<varname>LOCALBASE</varname> (defaulting to		<varname>LOCALBASE</varname> (defaulting to
<filename>/usr/local</filename>). If		<filename>/usr/local</filename>). If
<varname>USE_LINUX_PREFIX</varname> is set,		<varname>USE_LINUX_PREFIX</varname> is set,
<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 in		<para>Avoiding hard-coded <filename>/usr/local</filename> paths in
the source makes the port much more flexible and able to cater		the source makes the port much more flexible and able to cater
to the needs of other sites. Often, this can be accomplished by		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		in the port's various <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>

<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		<filename>/usr/local</filename> instead of
<varname>PREFIX</varname>. A quick test for such hard-coded		<varname>PREFIX</varname>. A quick test for such hard-coded
paths is:</para>		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		<para>If anything is installed outside of
<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 stage		<para>In addition, it is worth checking the same with the stage
directory support (see <xref linkend="staging"/>):</para>		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
		wblockUnsubmitted Not Done Inline Actions <para><buildtarget>check-plist</buildtarget> checks for wblock: <para><buildtarget>check-plist</buildtarget> checks for
		missing from the plist, and files in the plist that are not
		wblockUnsubmitted Not Done Inline Actions s/form/from/ wblock: s/form/from/
		installed by the port.</para>
		</listitem>

		<listitem>
		<para><buildtarget>stage-qa</buildtarget> checks for common
		problems like bad shebang, symlinks pointing outside the
		wblockUnsubmitted Not Done Inline Actions common problems like bad shebang, symlinks pointing wblock: common problems like bad shebang, symlinks pointing
		stage directory, setuid files, and non-stripped
		wblockUnsubmitted Not Done Inline Actions outside the stage directory, setuid files, and non-stripped wblock: 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		<para>These tests will not find hard-coded paths inside the port's
files, nor will it verify that <varname>LOCALBASE</varname> is		files, nor will it verify that <varname>LOCALBASE</varname> is
being used to correctly refer to files from other ports. The		being used to correctly refer 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> must be
tested for proper operation to make sure there are no problems		tested for proper operation to make sure there are no problems
with paths.</para>		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		port's <filename>Makefile</filename>. Users installing the port
may have set <varname>PREFIX</varname> to a custom location, and		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		<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 <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		to have the full pathname of <command>less</command>, do not use
a literal path of <filename>/usr/local/bin/less</filename>.		a literal path of <filename>/usr/local/bin/less</filename>.
Instead, use <literal>&dollar;{LOCALBASE}</literal>:</para>		Instead, use <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 to		<para>The path with <varname>LOCALBASE</varname> is more likely 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>

		<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>
		wblockUnsubmitted Not Done Inline Actions s/informations/information/ wblock: s/informations/information/
		</tip>
</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 take		<para>As an avid ports contributor, 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. You can install		powerful system for building and testing ports. Install
<application>Tinderbox</application> using		<application>Tinderbox</application> using
<package role="port">ports-mgmt/tinderbox</package> port. Be		<package role="port">ports-mgmt/tinderbox</package> port. Be
sure to read supplied documentation since the configuration is		sure to read supplied documentation since the configuration is
not trivial.</para>		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
website</link> for more details.</para>		website</link> for more details.</para>
</sect1>		</sect1>

<sect1 xml:id="testing-poudriere">		<sect1 xml:id="testing-poudriere">
<title>Poudriere</title>		<title>Poudriere</title>

<para>As a ports contributor, consider installing		<para>As a ports contributor, consider installing
<application>poudriere</application>. It is a powerful		<application>poudriere</application>. It is a powerful
system for building and testing ports.		system for building and testing ports.
<application>Poudriere</application> can be installed with		<application>Poudriere</application> can be installed with
<package role="port">ports-mgmt/poudriere</package>.</para>		<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		<para>Visit the <link
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>