Changeset View
Standalone View
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
<?xml version="1.0" encoding="iso-8859-1"?> | <?xml version="1.0" encoding="iso-8859-1"?> | ||||
<!-- | <!-- | ||||
The FreeBSD Documentation Project | The FreeBSD Documentation Project | ||||
$FreeBSD$ | $FreeBSD$ | ||||
--> | --> | ||||
<chapter xmlns="http://docbook.org/ns/docbook" | <chapter xmlns="http://docbook.org/ns/docbook" | ||||
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" | xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" | ||||
xml:id="special"> | xml:id="special"> | ||||
<title>Special Considerations</title> | <title>Special Considerations</title> | ||||
<para>There are some more things you have to take into account | <para>This section explains the most common things to consider when | ||||
wblock: <para>This section explains the most common things to consider when creating a port.</para> | |||||
when you create a port. This section explains the most common | creating a port.</para> | ||||
of those.</para> | |||||
<sect1 xml:id="staging"> | <sect1 xml:id="staging"> | ||||
<title>Staging</title> | <title>Staging</title> | ||||
<para><filename>bsd.port.mk</filename> expects ports to work | <para><filename>bsd.port.mk</filename> expects ports to work | ||||
with a <quote>stage directory</quote>. This means that a port | with a <quote>stage directory</quote>. This means that a port | ||||
should not install files directly to the regular destination | must not install files directly to the regular destination | ||||
directories (that is, under <varname>PREFIX</varname>, for | directories (that is, under <varname>PREFIX</varname>, for | ||||
example) but instead into a separate directory from which the | example) but instead into a separate directory from which the | ||||
package is then built. In many cases, this does not require | package is then built. In many cases, this does not require | ||||
root privileges, making it possible to build packages as an | root privileges, making it possible to build packages as an | ||||
unprivileged user. With staging, the port is built and | unprivileged user. With staging, the port is built and | ||||
installed into the stage directory, | installed into the stage directory, | ||||
<varname>STAGEDIR</varname>. A package is created from the | <varname>STAGEDIR</varname>. A package is created from the | ||||
stage directory and then installed on the system. Automake | stage directory and then installed on the system. Automake | ||||
tools refer to this concept as <varname>DESTDIR</varname>, but | tools refer to this concept as <varname>DESTDIR</varname>, but | ||||
in &os;, <varname>DESTDIR</varname> has a different meaning | in &os;, <varname>DESTDIR</varname> has a different meaning | ||||
(see <xref linkend="porting-prefix"/>).</para> | (see <xref linkend="porting-prefix"/>).</para> | ||||
<para>When a port still requires system-wide privileges in order | <para>When a port still requires system-wide privileges in order | ||||
to run the <buildtarget>stage</buildtarget> and | to run the <buildtarget>stage</buildtarget> and | ||||
<buildtarget>package</buildtarget> targets, this line must be | <buildtarget>package</buildtarget> targets, this line must be | ||||
added to the | added to the | ||||
<filename>Makefile</filename>:</para> | <filename>Makefile</filename>:</para> | ||||
<programlisting>NEED_ROOT= yes</programlisting> | <programlisting>NEED_ROOT= yes</programlisting> | ||||
<note> | <note> | ||||
<para>The vast majority of ports do not <emphasis>really | <para>The vast majority of ports do not <emphasis>really | ||||
need</emphasis> to be root. You can mostly avoid it by | need</emphasis> to be root. It can mostly be avoided by | ||||
Not Done Inline Actionss/mostly/mostly be/ wblock: s/mostly/mostly be/ | |||||
using <link | using <link | ||||
linkend="uses-uidfix"><literal>USES=uidfix</literal></link>, | linkend="uses-uidfix"><literal>USES=uidfix</literal></link>, | ||||
and from time to time by slightly patching the port's | and from time to time by slightly patching the port's | ||||
<filename>Makefiles</filename>.</para> | <filename>Makefiles</filename>.</para> | ||||
</note> | </note> | ||||
<para>Meta ports, or ports that do not install files themselves | <para>Meta ports, or ports that do not install files themselves | ||||
but only depend on other ports, should avoid needlessly | but only depend on other ports, must avoid needlessly | ||||
extracting the &man.mtree.8; to the stage directory. This is | extracting the &man.mtree.8; to the stage directory. This is | ||||
the basic directory layout of the package, and these empty | the basic directory layout of the package, and these empty | ||||
directories will be seen as orphans. To prevent | directories will be seen as orphans. To prevent | ||||
&man.mtree.8; extraction, add this line:</para> | &man.mtree.8; extraction, add this line:</para> | ||||
<programlisting>NO_MTREE= yes</programlisting> | <programlisting>NO_MTREE= yes</programlisting> | ||||
<para>Staging is enabled by prepending the | <para>Staging is enabled by prepending | ||||
<varname>STAGEDIR</varname> variable to paths used in the | <varname>STAGEDIR</varname> to paths used in the | ||||
<buildtarget>pre-install</buildtarget>, | <buildtarget>pre-install</buildtarget>, | ||||
<buildtarget>do-install</buildtarget>, and | <buildtarget>do-install</buildtarget>, and | ||||
<buildtarget>post-install</buildtarget> targets (see the | <buildtarget>post-install</buildtarget> targets (see the | ||||
examples through the book). Typically, this includes | examples through the book). Typically, this includes | ||||
<varname>PREFIX</varname>, <varname>ETCDIR</varname>, | <varname>PREFIX</varname>, <varname>ETCDIR</varname>, | ||||
<varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>, | <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>, | ||||
<varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and | <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and | ||||
so on. Directories should be created as part of the | so on. Directories should be created as part of the | ||||
Not Done Inline ActionsThis one actually needs "should". It's a recommendation on when to create directories. wblock: This one actually needs "should". It's a recommendation on when to create directories. | |||||
<buildtarget>post-install</buildtarget> target. Avoid using | <buildtarget>post-install</buildtarget> target. Avoid using | ||||
absolute paths whenever possible.</para> | absolute paths whenever possible.</para> | ||||
<para>When creating a symlink, <varname>STAGEDIR</varname> | <para>When creating a symlink, <varname>STAGEDIR</varname> | ||||
should be prepended to the target path only. For | is prepended to the target path only. For | ||||
Not Done Inline Actionss/has to be/is/ wblock: s/has to be/is/ | |||||
example:</para> | example:</para> | ||||
<programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting> | <programlisting>${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting> | ||||
<para>The source path | <para>The source path | ||||
<filename>${PREFIX}/lib/libfoo.so.42</filename> looks fine but | <filename>${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable></filename> looks fine but | ||||
could, in fact, be incorrect. Absolute paths can point to a | could, in fact, be incorrect. Absolute paths can point to a | ||||
wrong location, like when a remote file system has been | wrong location, like when a remote file system has been | ||||
mounted with <acronym>NFS</acronym> under a non-root mount | mounted with <acronym>NFS</acronym> under a non-root mount | ||||
point. Relative paths are less fragile, and often much | point. Relative paths are less fragile, and often much | ||||
shorter.</para> | shorter.</para> | ||||
<para>Ports that install kernel modules must prepend the | <para>Ports that install kernel modules must prepend | ||||
<varname>STAGEDIR</varname> variable to | <varname>STAGEDIR</varname> to | ||||
their destination, by default | their destination, by default | ||||
<filename>/boot/modules</filename>.</para> | <filename>/boot/modules</filename>.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="bundled-libs"> | <sect1 xml:id="bundled-libs"> | ||||
<title>Bundled Libraries</title> | <title>Bundled Libraries</title> | ||||
<para>This section explains why bundled dependencies are | <para>This section explains why bundled dependencies are | ||||
considered bad and what to do about them.</para> | considered bad and what to do about them.</para> | ||||
<sect2 xml:id="bundled-libs-why-bad"> | <sect2 xml:id="bundled-libs-why-bad"> | ||||
<title>Why Bundled Libraries Are Bad</title> | <title>Why Bundled Libraries Are Bad</title> | ||||
<para>Some software requires the porter to locate third-party | <para>Some software requires the porter to locate third-party | ||||
libraries and add the required dependencies to the port. | libraries and add the required dependencies to the port. | ||||
Other software bundles all necessary libraries into the | Other software bundles all necessary libraries into the | ||||
distribution file. The second approach seems easier at | distribution file. The second approach seems easier at | ||||
first, but there are some serious drawbacks:</para> | first, but there are some serious drawbacks:</para> | ||||
<para>The following list is loosely based on the <link | <para>This list is loosely based on the <link | ||||
xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link> | xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link> | ||||
and <link | and <link | ||||
xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link> | xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link> | ||||
wikis, both licensed under the <link | wikis, both licensed under the <link | ||||
xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA | xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA | ||||
3.0</link> license.</para> | 3.0</link> license.</para> | ||||
<variablelist> | <variablelist> | ||||
▲ Show 20 Lines • Show All 97 Lines • ▼ Show 20 Lines | </varlistentry> | ||||
<sect2 xml:id="bundled-libs-practices"> | <sect2 xml:id="bundled-libs-practices"> | ||||
<title>What to do About Bundled Libraries</title> | <title>What to do About Bundled Libraries</title> | ||||
<para>Whenever possible, use the unbundled version of the | <para>Whenever possible, use the unbundled version of the | ||||
library by adding a <varname>LIB_DEPENDS</varname> to the | library by adding a <varname>LIB_DEPENDS</varname> to the | ||||
port. If such a port does not exist yet, consider creating | port. If such a port does not exist yet, consider creating | ||||
it.</para> | it.</para> | ||||
<para>Bundled libraries should only be used if upstream has a | <para>Only use bundled libraries if the upstream has a | ||||
Not Done Inline Actionss/upstream/the upstream/ wblock: s/upstream/the upstream/ | |||||
good track record on security and using unbundled versions | good track record on security and using unbundled versions | ||||
leads to overly complex patches.</para> | leads to overly complex patches.</para> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="porting-shlibs"> | <sect1 xml:id="porting-shlibs"> | ||||
<title>Shared Libraries</title> | <title>Shared Libraries</title> | ||||
<para>If your port installs one or more shared libraries, define | <para>If the port installs one or more shared libraries, define | ||||
a <varname>USE_LDCONFIG</varname> make variable, which will | a <varname>USE_LDCONFIG</varname> make variable, which will | ||||
instruct a <filename>bsd.port.mk</filename> to run | instruct a <filename>bsd.port.mk</filename> to run | ||||
<literal>${LDCONFIG} -m</literal> on the directory | <literal>${LDCONFIG} -m</literal> on the directory | ||||
where the new library is installed (usually | where the new library is installed (usually | ||||
<filename>PREFIX/lib</filename>) during | <filename>PREFIX/lib</filename>) during | ||||
<buildtarget>post-install</buildtarget> target to register it | <buildtarget>post-install</buildtarget> target to register it | ||||
into the shared library cache. This variable, when defined, | into the shared library cache. This variable, when defined, | ||||
will also facilitate addition of an appropriate | will also facilitate addition of an appropriate | ||||
<literal>@exec /sbin/ldconfig -m</literal> and | <literal>@exec /sbin/ldconfig -m</literal> and | ||||
<literal>@unexec /sbin/ldconfig -R</literal> pair into your | <literal>@unexec /sbin/ldconfig -R</literal> pair into | ||||
<filename>pkg-plist</filename> file, so that a user who | <filename>pkg-plist</filename>, so that a user who | ||||
installed the package can start using the shared library | installed the package can start using the shared library | ||||
immediately and de-installation will not cause the system to | immediately and de-installation will not cause the system to | ||||
still believe the library is there.</para> | still believe the library is there.</para> | ||||
<programlisting>USE_LDCONFIG= yes</programlisting> | <programlisting>USE_LDCONFIG= yes</programlisting> | ||||
<para>If you need, you can override the default directory by | <para>The default directory can be overridden by | ||||
setting the <varname>USE_LDCONFIG</varname> value to a list of | setting <varname>USE_LDCONFIG</varname> to a list of | ||||
Not Done Inline Actionssetting <varname>USE_LDCONFIG</varname> to a list of wblock: setting <varname>USE_LDCONFIG</varname> to a list of | |||||
directories into which shared libraries are to be installed. | directories into which shared libraries are to be installed. | ||||
For example if your port installs shared libraries into | For example, if the port installs shared libraries into | ||||
Not Done Inline Actionss/example/example,/ wblock: s/example/example,/ | |||||
<filename>PREFIX/lib/foo</filename> and | <filename>PREFIX/lib/foo</filename> and | ||||
<filename>PREFIX/lib/bar</filename> | <filename>PREFIX/lib/bar</filename> | ||||
Not Done Inline Actions<filename>PREFIX/lib/bar</filename>, wblock: <filename>PREFIX/lib/bar</filename>, | |||||
directories you could use the following in your | use this in | ||||
<filename>Makefile</filename>:</para> | <filename>Makefile</filename>:</para> | ||||
<programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting> | <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting> | ||||
<para>Please double-check, often this is not necessary at all or | <para>Please double-check, often this is not necessary at all or | ||||
can be avoided through <literal>-rpath</literal> or setting | can be avoided through <literal>-rpath</literal> or setting | ||||
<envar>LD_RUN_PATH</envar> during linking (see | <envar>LD_RUN_PATH</envar> during linking (see | ||||
<package role="port">lang/moscow_ml</package> for an | <package role="port">lang/moscow_ml</package> for an | ||||
example), or through a shell-wrapper which sets | example), or through a shell-wrapper which sets | ||||
<varname>LD_LIBRARY_PATH</varname> before invoking the binary, | <varname>LD_LIBRARY_PATH</varname> before invoking the binary, | ||||
like <package role="port">www/seamonkey</package> | like <package role="port">www/seamonkey</package> | ||||
does.</para> | does.</para> | ||||
<para>When installing 32-bit libraries on 64-bit system, use | <para>When installing 32-bit libraries on 64-bit system, use | ||||
<varname>USE_LDCONFIG32</varname> instead.</para> | <varname>USE_LDCONFIG32</varname> instead.</para> | ||||
<para>If the software you are porting uses <link | <para>If the software uses <link | ||||
linkend="using-autotools">autotools</link>, and specifically | linkend="using-autotools">autotools</link>, and specifically | ||||
<command>libtool</command>, you should add <link | <command>libtool</command>, add <link | ||||
linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para> | linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para> | ||||
<para>When the major library version number increments in the | <para>When the major library version number increments in the | ||||
update to the new port version, all other ports that link to | update to the new port version, all other ports that link to | ||||
the affected library should have their | the affected library must have their | ||||
<varname>PORTREVISION</varname> incremented, to force | <varname>PORTREVISION</varname> incremented, to force | ||||
recompilation with the new library version.</para> | recompilation with the new library version.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="porting-restrictions"> | <sect1 xml:id="porting-restrictions"> | ||||
<title>Ports with Distribution Restrictions or Legal | <title>Ports with Distribution Restrictions or Legal | ||||
Concerns</title> | Concerns</title> | ||||
<para>Licenses vary, and some of them place restrictions on how | <para>Licenses vary, and some of them place restrictions on how | ||||
the application can be packaged, whether it can be sold for | the application can be packaged, whether it can be sold for | ||||
profit, and so on.</para> | profit, and so on.</para> | ||||
<important> | <important> | ||||
<para>It is your responsibility as a porter to read the | <para>It is the responsibility of a porter to read the | ||||
licensing terms of the software and make sure that the | licensing terms of the software and make sure that the | ||||
&os; project will not be held accountable for violating | &os; project will not be held accountable for violating | ||||
them by redistributing the source or compiled binaries | them by redistributing the source or compiled binaries | ||||
either via FTP/HTTP or CD-ROM. If in doubt, please contact | either via FTP/HTTP or CD-ROM. If in doubt, please contact | ||||
the &a.ports;.</para> | the &a.ports;.</para> | ||||
</important> | </important> | ||||
<para>In situations like this, the variables described in the | <para>In situations like this, the variables described in the | ||||
following sections can be set.</para> | next sections can be set.</para> | ||||
<sect2 xml:id="porting-restrictions-no_package"> | <sect2 xml:id="porting-restrictions-no_package"> | ||||
<title><varname>NO_PACKAGE</varname></title> | <title><varname>NO_PACKAGE</varname></title> | ||||
<para>This variable indicates that we may not generate a | <para>This variable indicates that we may not generate a | ||||
binary package of the application. For instance, the | binary package of the application. For instance, the | ||||
license may disallow binary redistribution, or it may | license may disallow binary redistribution, or it may | ||||
prohibit distribution of packages created from patched | prohibit distribution of packages created from patched | ||||
sources.</para> | sources.</para> | ||||
<para>However, the port's <varname>DISTFILES</varname> may be | <para>However, the port's <varname>DISTFILES</varname> may be | ||||
freely mirrored on FTP/HTTP. They may also be distributed | freely mirrored on FTP/HTTP. They may also be distributed | ||||
on a CD-ROM (or similar media) unless | on a CD-ROM (or similar media) unless | ||||
<varname>NO_CDROM</varname> is set as well.</para> | <varname>NO_CDROM</varname> is set as well.</para> | ||||
<para><varname>NO_PACKAGE</varname> should also be used if the | <para>If the | ||||
binary package is not generally useful, and the application | binary package is not generally useful, and the application | ||||
should always be compiled from the source code. For | must always be compiled from the source code, use | ||||
<varname>NO_PACKAGE</varname>. For | |||||
Not Done Inline Actionss/has to/must/ wblock: s/has to/must/ | |||||
example, if the application has configuration information | example, if the application has configuration information | ||||
that is site specific hard coded in to it at compile time, | that is site specific hard coded into it at compile time, | ||||
Not Done Inline Actionss/in to/into/ wblock: s/in to/into/ | |||||
set <varname>NO_PACKAGE</varname>.</para> | set <varname>NO_PACKAGE</varname>.</para> | ||||
<para><varname>NO_PACKAGE</varname> should be set to a string | <para>Set <varname>NO_PACKAGE</varname> to a string | ||||
describing the reason why the package should not be | describing the reason why the package cannot be | ||||
Not Done Inline Actionss/cannot not be/cannot be/ wblock: s/cannot not be/cannot be/ | |||||
generated.</para> | generated.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-no_cdrom"> | <sect2 xml:id="porting-restrictions-no_cdrom"> | ||||
<title><varname>NO_CDROM</varname></title> | <title><varname>NO_CDROM</varname></title> | ||||
<para>This variable alone indicates that, although we are | <para>This variable alone indicates that, although we are | ||||
allowed to generate binary packages, we may put neither | allowed to generate binary packages, we may put neither | ||||
those packages nor the port's <varname>DISTFILES</varname> | those packages nor the port's <varname>DISTFILES</varname> | ||||
onto a CD-ROM (or similar media) for resale. However, the | onto a CD-ROM (or similar media) for resale. However, the | ||||
binary packages and the port's <varname>DISTFILES</varname> | binary packages and the port's <varname>DISTFILES</varname> | ||||
will still be available via FTP/HTTP.</para> | will still be available via FTP/HTTP.</para> | ||||
<para> If this variable is set along with | <para> If this variable is set along with | ||||
<varname>NO_PACKAGE</varname>, then only the port's | <varname>NO_PACKAGE</varname>, then only the port's | ||||
<varname>DISTFILES</varname> will be available, and only via | <varname>DISTFILES</varname> will be available, and only via | ||||
FTP/HTTP.</para> | FTP/HTTP.</para> | ||||
<para><varname>NO_CDROM</varname> should be set to a string | <para>Set <varname>NO_CDROM</varname> to a string | ||||
describing the reason why the port cannot be redistributed | describing the reason why the port cannot be redistributed | ||||
on CD-ROM. For instance, this should be used if the port's | on CD-ROM. For instance, use this if the port's | ||||
license is for <quote>non-commercial</quote> use | license is for <quote>non-commercial</quote> use | ||||
only.</para> | only.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-nofetchfiles"> | <sect2 xml:id="porting-restrictions-nofetchfiles"> | ||||
<title><varname>NOFETCHFILES</varname></title> | <title><varname>NOFETCHFILES</varname></title> | ||||
<para>Files defined in the <varname>NOFETCHFILES</varname> | <para>Files defined in <varname>NOFETCHFILES</varname> | ||||
variable are not fetchable from any of the | are not fetchable from any of | ||||
<varname>MASTER_SITES</varname>. An example of such a file | <varname>MASTER_SITES</varname>. An example of such a file | ||||
is when the file is supplied on CD-ROM by the vendor.</para> | is when the file is supplied on CD-ROM by the vendor.</para> | ||||
<para>Tools which check for the availability of these files | <para>Tools which check for the availability of these files | ||||
on the <varname>MASTER_SITES</varname> should ignore these | on <varname>MASTER_SITES</varname> have to ignore these | ||||
files and not report about them.</para> | files and not report about them.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-restricted"> | <sect2 xml:id="porting-restrictions-restricted"> | ||||
<title><varname>RESTRICTED</varname></title> | <title><varname>RESTRICTED</varname></title> | ||||
<para>Set this variable alone if the application's license | <para>Set this variable alone if the application's license | ||||
permits neither mirroring the application's | permits neither mirroring the application's | ||||
<varname>DISTFILES</varname> nor distributing the binary | <varname>DISTFILES</varname> nor distributing the binary | ||||
package in any way.</para> | package in any way.</para> | ||||
<para><varname>NO_CDROM</varname> or | <para>Do not set <varname>NO_CDROM</varname> or | ||||
<varname>NO_PACKAGE</varname> should not be set along with | <varname>NO_PACKAGE</varname> along with | ||||
<varname>RESTRICTED</varname> since the latter variable | <varname>RESTRICTED</varname>, since the latter variable | ||||
Not Done Inline Actions<varname>RESTRICTED</varname>, since the latter variable wblock: <varname>RESTRICTED</varname>, since the latter variable | |||||
implies the former ones.</para> | implies the former ones.</para> | ||||
<para><varname>RESTRICTED</varname> should be set to a string | <para>Set <varname>RESTRICTED</varname> to a string | ||||
describing the reason why the port cannot be redistributed. | describing the reason why the port cannot be redistributed. | ||||
Typically, this indicates that the port contains proprietary | Typically, this indicates that the port contains proprietary | ||||
software and that the user will need to manually download | software and that the user will need to manually download | ||||
the <varname>DISTFILES</varname>, possibly after registering | the <varname>DISTFILES</varname>, possibly after registering | ||||
for the software or agreeing to accept the terms of an | for the software or agreeing to accept the terms of an | ||||
<acronym>EULA</acronym>.</para> | <acronym>EULA</acronym>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-restricted_files"> | <sect2 xml:id="porting-restrictions-restricted_files"> | ||||
<title><varname>RESTRICTED_FILES</varname></title> | <title><varname>RESTRICTED_FILES</varname></title> | ||||
<para>When <varname>RESTRICTED</varname> or | <para>When <varname>RESTRICTED</varname> or | ||||
<varname>NO_CDROM</varname> is set, this variable defaults | <varname>NO_CDROM</varname> is set, this variable defaults | ||||
to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise | to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise | ||||
it is empty. If only some of the distribution files are | it is empty. If only some of the distribution files are | ||||
restricted, then set this variable to list them.</para> | restricted, then set this variable to list them.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-legal_text"> | <sect2 xml:id="porting-restrictions-legal_text"> | ||||
<title><varname>LEGAL_TEXT</varname></title> | <title><varname>LEGAL_TEXT</varname></title> | ||||
<para>If the port has legal concerns not addressed by the | <para>If the port has legal concerns not addressed by the | ||||
above variables, the variable <varname>LEGAL_TEXT</varname> | above variables, set <varname>LEGAL_TEXT</varname> | ||||
should be set to a string explaining the concern. For | to a string explaining the concern. For | ||||
example, if special permission was obtained for &os; to | example, if special permission was obtained for &os; to | ||||
redistribute the binary, this variable should indicate | redistribute the binary, this variable must indicate | ||||
so.</para> | so.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="porting-restrictions-legal"> | <sect2 xml:id="porting-restrictions-legal"> | ||||
<title><filename>/usr/ports/LEGAL</filename> and | <title><filename>/usr/ports/LEGAL</filename> and | ||||
<varname>LEGAL</varname></title> | <varname>LEGAL</varname></title> | ||||
<para>A port which sets any of the above variables must also | <para>A port which sets any of the above variables must also | ||||
▲ Show 20 Lines • Show All 62 Lines • ▼ Show 20 Lines | <literal>fmake</literal> there.</para> | ||||
<para><varname>MAKE_CMD</varname> can be used to reference the | <para><varname>MAKE_CMD</varname> can be used to reference the | ||||
specific command configured by the <literal>USES</literal> | specific command configured by the <literal>USES</literal> | ||||
setting in the port's <filename>Makefile</filename>. In | setting in the port's <filename>Makefile</filename>. In | ||||
rare cases when more than one <literal>make</literal> | rare cases when more than one <literal>make</literal> | ||||
implementation is listed in <literal>USES</literal>, the | implementation is listed in <literal>USES</literal>, the | ||||
variables <varname>GMAKE</varname> (for the | variables <varname>GMAKE</varname> (for the | ||||
<acronym>GNU</acronym> version) or <varname>FMAKE</varname> | <acronym>GNU</acronym> version) or <varname>FMAKE</varname> | ||||
(for the legacy &os; version) are available. Most ports | (for the legacy &os; version) are available. | ||||
should only use <varname>MAKE_CMD</varname> within the | Only use <varname>MAKE_CMD</varname> within the | ||||
application <filename>Makefile</filename>s in | application <filename>Makefile</filename>s in | ||||
<varname>WRKSRC</varname> to call the | <varname>WRKSRC</varname> to call the | ||||
<command>make</command> implementation expected by the | <command>make</command> implementation expected by the | ||||
ported software.</para> | ported software.</para> | ||||
<para>If the port is an X application that uses | <para>If the port is an X application that uses | ||||
<application>imake</application> to create | <application>imake</application> to create | ||||
<filename>Makefile</filename>s from | <filename>Makefile</filename>s from | ||||
<filename>Imakefile</filename>s, set <literal>USES= | <filename>Imakefile</filename>s, set <literal>USES= | ||||
imake</literal>.. See the <link | imake</literal>.. See the <link | ||||
linkend="uses-imake"><literal>USES=imake</literal></link> | linkend="uses-imake"><literal>USES=imake</literal></link> | ||||
section of <xref linkend="uses"/> for more details.</para> | section of <xref linkend="uses"/> for more details.</para> | ||||
<para>If your port's source <filename>Makefile</filename> has | <para>If the port's source <filename>Makefile</filename> has | ||||
something else than <buildtarget>all</buildtarget> as the | something other than <buildtarget>all</buildtarget> as the | ||||
Not Done Inline Actionss/else/other/ wblock: s/else/other/ | |||||
main build target, set <varname>ALL_TARGET</varname> | main build target, set <varname>ALL_TARGET</varname> | ||||
accordingly. Same goes for | accordingly. The same goes for | ||||
Not Done Inline Actionss/Same/The same/ wblock: s/Same/The same/ | |||||
<buildtarget>install</buildtarget> and | <buildtarget>install</buildtarget> and | ||||
<varname>INSTALL_TARGET</varname>.</para> | <varname>INSTALL_TARGET</varname>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-configure"> | <sect2 xml:id="using-configure"> | ||||
<title><command>configure</command> Script</title> | <title><command>configure</command> Script</title> | ||||
<para>If your port uses the <command>configure</command> | <para>If the port uses the <command>configure</command> | ||||
script to generate <filename>Makefile</filename> files from | script to generate <filename>Makefile</filename> from | ||||
<filename>Makefile.in</filename> files, set | <filename>Makefile.in</filename>, set | ||||
<literal>GNU_CONFIGURE=yes</literal>. If you want to give | <literal>GNU_CONFIGURE=yes</literal>. To give | ||||
extra arguments to the <command>configure</command> script | extra arguments to the <command>configure</command> script | ||||
(the default argument is <literal>--prefix=${PREFIX} | (the default argument is <literal>--prefix=${PREFIX} | ||||
--infodir=${PREFIX}/${INFO_PATH} | --infodir=${PREFIX}/${INFO_PATH} | ||||
--mandir=${MANPREFIX}/man | --mandir=${MANPREFIX}/man | ||||
--build=${CONFIGURE_TARGET}</literal>), set those | --build=${CONFIGURE_TARGET}</literal>), set those | ||||
extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra | extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra | ||||
environment variables can be passed using | environment variables can be passed using | ||||
<varname>CONFIGURE_ENV</varname> variable.</para> | <varname>CONFIGURE_ENV</varname>.</para> | ||||
<table frame="none" xml:id="using-configure-variables"> | <table frame="none" xml:id="using-configure-variables"> | ||||
<title>Variables for Ports That Use | <title>Variables for Ports That Use | ||||
<command>configure</command></title> | <command>configure</command></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
▲ Show 20 Lines • Show All 88 Lines • ▼ Show 20 Lines | <literal>${CONFIGURE_ENV}</literal>.</entry> | ||||
<entry>Path to the source directory. Default is | <entry>Path to the source directory. Default is | ||||
<literal>${WRKSRC}</literal>.</entry> | <literal>${WRKSRC}</literal>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<table frame="none" xml:id="using-cmake-user-variables"> | <table frame="none" xml:id="using-cmake-user-variables"> | ||||
<title>Variables the Users can define for | <title>Variables the Users Can Define for | ||||
<command>cmake</command> builds</title> | <command>cmake</command> Builds</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Variable</entry> | <entry>Variable</entry> | ||||
<entry>Means</entry> | <entry>Means</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
Show All 11 Lines | <varname>PACKAGE_BUILDING</varname> are set.</entry> | ||||
<entry>Disables colour build output. Default not set, | <entry>Disables colour build output. Default not set, | ||||
unless <varname>BATCH</varname> or | unless <varname>BATCH</varname> or | ||||
<varname>PACKAGE_BUILDING</varname> are set.</entry> | <varname>PACKAGE_BUILDING</varname> are set.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para><application>CMake</application> supports the following | <para><application>CMake</application> supports these | ||||
build profiles: <literal>Debug</literal>, | build profiles: <literal>Debug</literal>, | ||||
<literal>Release</literal>, | <literal>Release</literal>, | ||||
<literal>RelWithDebInfo</literal> and | <literal>RelWithDebInfo</literal> and | ||||
<literal>MinSizeRel</literal>. <literal>Debug</literal> and | <literal>MinSizeRel</literal>. <literal>Debug</literal> and | ||||
<literal>Release</literal> profiles respect system | <literal>Release</literal> profiles respect system | ||||
<literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal> | <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal> | ||||
and <literal>MinSizeRel</literal> will set | and <literal>MinSizeRel</literal> will set | ||||
<varname>CFLAGS</varname> to <literal>-O2 -g</literal> and | <varname>CFLAGS</varname> to <literal>-O2 -g</literal> and | ||||
<literal>-Os -DNDEBUG</literal> correspondingly. The | <literal>-Os -DNDEBUG</literal> correspondingly. The | ||||
lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is | lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is | ||||
exported to the <varname>PLIST_SUB</varname> and should be | exported to <varname>PLIST_SUB</varname> and must be | ||||
used if port installs <literal>*.cmake</literal> files | used if the port installs <filename><replaceable>*</replaceable>.cmake</filename> | ||||
Not Done Inline Actionss/if port/if the port/ wblock: s/if port/if the port/ | |||||
depending on the build type (see | depending on the build type (see | ||||
<package role="port">deskutils/strigi</package> for an | <package role="port">deskutils/strigi</package> for an | ||||
example). Please note that some projects may define their | example). Please note that some projects may define their | ||||
own build profiles and/or force particular build type by | own build profiles and/or force particular build type by | ||||
setting <literal>CMAKE_BUILD_TYPE</literal> in | setting <literal>CMAKE_BUILD_TYPE</literal> in | ||||
<filename>CMakeLists.txt </filename> files. In order to | <filename>CMakeLists.txt</filename>. To | ||||
make a port for such a project respect | make a port for such a project respect | ||||
<varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>, | <varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>, | ||||
the <literal>CMAKE_BUILD_TYPE</literal> definitions must be | the <literal>CMAKE_BUILD_TYPE</literal> definitions must be | ||||
removed from those files.</para> | removed from those files.</para> | ||||
<para>Most <application>CMake</application>-based projects | <para>Most <application>CMake</application>-based projects | ||||
support an out-of-source method of building. The | support an out-of-source method of building. The | ||||
out-of-source build for a port can be requested by using the | out-of-source build for a port can be requested by using the | ||||
<literal>:outsource</literal> suffix. When enabled, | <literal>:outsource</literal> suffix. When enabled, | ||||
<varname>CONFIGURE_WRKSRC</varname>, | <varname>CONFIGURE_WRKSRC</varname>, | ||||
<varname>BUILD_WRKSRC</varname> and | <varname>BUILD_WRKSRC</varname> and | ||||
<varname>INSTALL_WRKSRC</varname> will be set to | <varname>INSTALL_WRKSRC</varname> will be set to | ||||
<literal>${WRKDIR}/.build</literal> and this | <literal>${WRKDIR}/.build</literal> and this | ||||
directory will be used to keep all files generated during | directory will be used to keep all files generated during | ||||
configuration and build stages, leaving the source directory | configuration and build stages, leaving the source directory | ||||
intact.</para> | intact.</para> | ||||
<example xml:id="using-cmake-example"> | <example xml:id="using-cmake-example"> | ||||
<title><literal>USES= cmake</literal> Example</title> | <title><literal>USES= cmake</literal> Example</title> | ||||
<para>The following snippet demonstrates the use of | <para>This snippet demonstrates the use of | ||||
<application>CMake</application> for a port. | <application>CMake</application> for a port. | ||||
<varname>CMAKE_SOURCE_PATH</varname> is not usually | <varname>CMAKE_SOURCE_PATH</varname> is not usually | ||||
required, but can be set when the sources are not located | required, but can be set when the sources are not located | ||||
in the top directory, or if only a subset of the project | in the top directory, or if only a subset of the project | ||||
is intended to be built by the port.</para> | is intended to be built by the port.</para> | ||||
<programlisting>USES= cmake:outsource | <programlisting>USES= cmake:outsource | ||||
CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> | CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-scons"> | <sect2 xml:id="using-scons"> | ||||
<title>Using <command>scons</command></title> | <title>Using <command>scons</command></title> | ||||
<para>If your port uses <application>SCons</application>, | <para>If the port uses <application>SCons</application>, | ||||
define <literal>USE_SCONS=yes</literal>.</para> | define <literal>USE_SCONS=yes</literal>.</para> | ||||
<table frame="none" xml:id="using-scons-variables"> | <table frame="none" xml:id="using-scons-variables"> | ||||
<title>Variables for Ports That Use | <title>Variables for Ports That Use | ||||
<command>scons</command></title> | <command>scons</command></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
Show All 29 Lines | <varname>MAKE_TARGET</varname>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>To make third party <filename>SConstruct</filename> | <para>To make third party <filename>SConstruct</filename> | ||||
respect everything that is passed to SCons in | respect everything that is passed to SCons in | ||||
<varname>SCONS_ENV</varname> (that is, most importantly, | <varname>SCONS_ENV</varname> (that is, most importantly, | ||||
<varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the | <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch | ||||
<filename>SConstruct</filename> so build | <filename>SConstruct</filename> so build | ||||
<literal>Environment</literal> is constructed like | <literal>Environment</literal> is constructed like | ||||
this:</para> | this:</para> | ||||
<programlisting>env = Environment(**ARGUMENTS)</programlisting> | <programlisting>env = Environment(**ARGUMENTS)</programlisting> | ||||
<para>It may be then modified with | <para>It may be then modified with | ||||
<literal>env.Append</literal> and | <literal>env.Append</literal> and | ||||
▲ Show 20 Lines • Show All 72 Lines • ▼ Show 20 Lines | CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> | ||||
optional operations for this tool.</para> | optional operations for this tool.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-autoconf"> | <sect2 xml:id="using-autoconf"> | ||||
<title><command>autoconf</command> and | <title><command>autoconf</command> and | ||||
<command>autoheader</command></title> | <command>autoheader</command></title> | ||||
<para>Some ports do not contain a configure script, but do | <para>Some ports do not contain a configure script, but do | ||||
contain an autoconf template in the | contain an autoconf template in | ||||
<filename>configure.ac</filename> file. You can use the | <filename>configure.ac</filename>. Use these | ||||
following assignments to let <command>autoconf</command> | assignments to let <command>autoconf</command> | ||||
create the configure script, and also have | create the configure script, and also have | ||||
<command>autoheader</command> create template headers for | <command>autoheader</command> create template headers for | ||||
use by the configure script.</para> | use by the configure script.</para> | ||||
<programlisting>USE_AUTOTOOLS= autoconf[:env]</programlisting> | <programlisting>USE_AUTOTOOLS= autoconf[:env]</programlisting> | ||||
<para>and</para> | <para>and</para> | ||||
Show All 11 Lines | CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> | ||||
details.</para> | details.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-automake"> | <sect2 xml:id="using-automake"> | ||||
<title><command>automake</command> and | <title><command>automake</command> and | ||||
<command>aclocal</command></title> | <command>aclocal</command></title> | ||||
<para>Some packages only contain | <para>Some packages only contain | ||||
<filename>Makefile.am</filename> files. These have to be | <filename>Makefile.am</filename>. These have to be | ||||
converted into <filename>Makefile.in</filename> files using | converted into <filename>Makefile.in</filename> using | ||||
<command>automake</command>, and the further processed by | <command>automake</command>, and the further processed by | ||||
<command>configure</command> to generate an actual | <command>configure</command> to generate an actual | ||||
<filename>Makefile</filename>.</para> | <filename>Makefile</filename>.</para> | ||||
<para>Similarly, packages occasionally do not ship with | <para>Similarly, packages occasionally do not ship with | ||||
included <filename>aclocal.m4</filename> files, again | an included <filename>aclocal.m4</filename>, again | ||||
Not Done Inline Actionss/^/an / wblock: s/^/an / | |||||
required to build the software. This can be achieved with | required to build the software. This can be achieved with | ||||
<command>aclocal</command>, which scans | <command>aclocal</command>, which scans | ||||
<filename>configure.ac</filename> or | <filename>configure.ac</filename> or | ||||
<filename>configure.in</filename>.</para> | <filename>configure.in</filename>.</para> | ||||
<para><command>aclocal</command> has a similar relationship to | <para><command>aclocal</command> has a similar relationship to | ||||
<command>automake</command> as <command>autoheader</command> | <command>automake</command> as <command>autoheader</command> | ||||
does to <command>autoconf</command>, described in the | does to <command>autoconf</command>, described in the | ||||
Show All 18 Lines | CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-gettext"> | <sect1 xml:id="using-gettext"> | ||||
<title>Using GNU <literal>gettext</literal></title> | <title>Using GNU <literal>gettext</literal></title> | ||||
<sect2 xml:id="using-gettext-basic"> | <sect2 xml:id="using-gettext-basic"> | ||||
<title>Basic Usage</title> | <title>Basic Usage</title> | ||||
<para>If your port requires <literal>gettext</literal>, set | <para>If the port requires <literal>gettext</literal>, set | ||||
<literal>USES= gettext</literal>, and your port will inherit | <literal>USES= gettext</literal>, and the port will inherit | ||||
a dependency on <filename>libintl.so</filename> from | a dependency on <filename>libintl.so</filename> from | ||||
<package role="port">devel/gettext</package>. Other | <package role="port">devel/gettext</package>. Other | ||||
values for <literal>gettext</literal> usage are listed in | values for <literal>gettext</literal> usage are listed in | ||||
<link | <link | ||||
linkend="uses-gettext"><literal>USES=gettext</literal></link>.</para> | linkend="uses-gettext"><literal>USES=gettext</literal></link>.</para> | ||||
<para>A rather common case is a port using | <para>A rather common case is a port using | ||||
<literal>gettext</literal> and <command>configure</command>. | <literal>gettext</literal> and <command>configure</command>. | ||||
Show All 13 Lines | |||||
LDFLAGS+= -L${LOCALBASE}/lib | LDFLAGS+= -L${LOCALBASE}/lib | ||||
GNU_CONFIGURE= yes</programlisting> | GNU_CONFIGURE= yes</programlisting> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-gettext-optional"> | <sect2 xml:id="using-gettext-optional"> | ||||
<title>Optional Usage</title> | <title>Optional Usage</title> | ||||
<para>Some software products allow for disabling NLS, e.g., | <para>Some software products allow for disabling <acronym>NLS</acronym>. For example, | ||||
Not Done Inline ActionsBreak sentence at NLS. Also use <acronym> tags on NLS. wblock: Break sentence at NLS. Also use <acronym> tags on NLS. | |||||
through passing <option>--disable-nls</option> to | through passing <option>--disable-nls</option> to | ||||
<command>configure</command>. In that case, your port | <command>configure</command>. In that case, the port | ||||
should use <literal>gettext</literal> conditionally, | must use <literal>gettext</literal> conditionally, | ||||
depending on the status of the <varname>NLS</varname> | depending on the status of the <literal>NLS</literal> | ||||
option. For ports of low to medium complexity, you can rely | option. For ports of low to medium complexity, use | ||||
on the following idiom:</para> | this idiom:</para> | ||||
Not Done Inline Actionss/on// wblock: s/on// | |||||
<programlisting>GNU_CONFIGURE= yes | <programlisting>GNU_CONFIGURE= yes | ||||
OPTIONS_DEFINE= NLS | OPTIONS_DEFINE= NLS | ||||
OPTIONS_SUB= yes | OPTIONS_SUB= yes | ||||
NLS_USES= gettext | NLS_USES= gettext | ||||
NLS_CONFIGURE_ENABLE= nls | NLS_CONFIGURE_ENABLE= nls | ||||
Show All 13 Lines | |||||
PLIST_SUB+= NLS="" | PLIST_SUB+= NLS="" | ||||
.else | .else | ||||
CONFIGURE_ARGS+= --disable-nls | CONFIGURE_ARGS+= --disable-nls | ||||
PLIST_SUB+= NLS="@comment " | PLIST_SUB+= NLS="@comment " | ||||
.endif | .endif | ||||
.include <bsd.port.mk></programlisting> | .include <bsd.port.mk></programlisting> | ||||
<para>The next item on your to-do list is to arrange so that | <para>The next item on the to-do list is to arrange so that | ||||
the message catalog files are included in the packing list | the message catalog files are included in the packing list | ||||
conditionally. The <filename>Makefile</filename> part of | conditionally. The <filename>Makefile</filename> part of | ||||
this task is already provided by the idiom. It is explained | this task is already provided by the idiom. It is explained | ||||
in the section on <link linkend="plist-sub">advanced | in the section on <link linkend="plist-sub">advanced | ||||
<filename>pkg-plist</filename> practices</link>. In a | <filename>pkg-plist</filename> practices</link>. In a | ||||
nutshell, each occurrence of <literal>%%NLS%%</literal> in | nutshell, each occurrence of <literal>%%NLS%%</literal> in | ||||
<filename>pkg-plist</filename> will be replaced by | <filename>pkg-plist</filename> will be replaced by | ||||
<quote><literal>@comment </literal></quote> if NLS is | <quote><literal>@comment </literal></quote> if NLS is | ||||
disabled, or by a null string if NLS is enabled. | disabled, or by a null string if NLS is enabled. | ||||
Consequently, the lines prefixed by | Consequently, the lines prefixed by | ||||
<literal>%%NLS%%</literal> will become mere comments in the | <literal>%%NLS%%</literal> will become mere comments in the | ||||
final packing list if NLS is off; otherwise the prefix will | final packing list if NLS is off; otherwise the prefix will | ||||
be just left out. All you need to do now is insert | be just left out. Then insert | ||||
<literal>%%NLS%%</literal> before each path to a message | <literal>%%NLS%%</literal> before each path to a message | ||||
catalog file in <filename>pkg-plist</filename>. For | catalog file in <filename>pkg-plist</filename>. For | ||||
example:</para> | example:</para> | ||||
<programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo | <programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo | ||||
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting> | %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting> | ||||
<para>In high complexity cases, you may need to use more | <para>In high complexity cases, more advanced techniques | ||||
advanced techniques than the recipe given here, such as | may be needed, such as | ||||
Not Done Inline ActionsIn high complexity cases, more advanced techniques wblock: In high complexity cases, more advanced techniques | |||||
Not Done Inline Actionsmay be needed, such as wblock: may be needed, such as | |||||
<link linkend="plist-dynamic">dynamic packing list | <link linkend="plist-dynamic">dynamic packing list | ||||
generation</link>.</para> | generation</link>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="using-gettext-catalog-directories"> | <sect2 xml:id="using-gettext-catalog-directories"> | ||||
<title>Handling Message Catalog Directories</title> | <title>Handling Message Catalog Directories</title> | ||||
<para>There is a point to note about installing message | <para>There is a point to note about installing message | ||||
catalog files. The target directories for them, which | catalog files. The target directories for them, which | ||||
reside under | reside under | ||||
<filename>LOCALBASE/share/locale</filename>, | <filename>LOCALBASE/share/locale</filename>, | ||||
should rarely be created and removed by a port. The most | must not be created and removed by a port. The most | ||||
popular languages have their respective directories listed | popular languages have their respective directories listed | ||||
in | in | ||||
<filename>PORTSDIR/Templates/BSD.local.dist</filename>. | <filename>PORTSDIR/Templates/BSD.local.dist</filename>. | ||||
The directories for many other languages are governed by the | The directories for many other languages are governed by the | ||||
<package role="port">devel/gettext</package> port. | <package role="port">devel/gettext</package> port. | ||||
Consult its <filename>pkg-plist</filename> and see whether | Consult its <filename>pkg-plist</filename> and see whether | ||||
the port is going to install a message catalog file for a | the port is going to install a message catalog file for a | ||||
unique language.</para> | unique language.</para> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-perl"> | <sect1 xml:id="using-perl"> | ||||
<title>Using <application>Perl</application></title> | <title>Using <application>Perl</application></title> | ||||
<para>If <varname>MASTER_SITES</varname> is set to | <para>If <varname>MASTER_SITES</varname> is set to | ||||
<literal>CPAN</literal>, the correct subdirectory should be | <literal>CPAN</literal>, the correct subdirectory is usually | ||||
selected automatically. If the default subdirectory is wrong, | selected automatically. If the default subdirectory is wrong, | ||||
<literal>CPAN/Module</literal> can be used to change it. | <literal>CPAN/Module</literal> can be used to change it. | ||||
<varname>MASTER_SITES</varname> can also be set to the old | <varname>MASTER_SITES</varname> can also be set to the old | ||||
<varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred | <varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred | ||||
value of <varname>MASTER_SITE_SUBDIR</varname> is the | value of <varname>MASTER_SITE_SUBDIR</varname> is the | ||||
top-level hierarchy name. For example, the recommended value | top-level hierarchy name. For example, the recommended value | ||||
for <literal>p5-Module-Name</literal> is | for <literal>p5-Module-Name</literal> is | ||||
<literal>Module</literal>. The top-level hierarchy can be | <literal>Module</literal>. The top-level hierarchy can be | ||||
examined at <link | examined at <link | ||||
xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. | xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. | ||||
This keeps the port working when the author of the module | This keeps the port working when the author of the module | ||||
changes.</para> | changes.</para> | ||||
<para>The exception to this rule is when the relevant directory | <para>The exception to this rule is when the relevant directory | ||||
does not exist or the distfile does not exist in that | does not exist or the distfile does not exist in that | ||||
directory. In such case, using author's id as | directory. In such case, using author's id as | ||||
<varname>MASTER_SITE_SUBDIR</varname> is allowed. | <varname>MASTER_SITE_SUBDIR</varname> is allowed. | ||||
The <literal>CPAN:AUTHOR</literal> macro can be used, which will | The <literal>CPAN:AUTHOR</literal> macro can be used, which will | ||||
be translated to the hashed author directory. (e.g., | be translated to the hashed author directory. For example, | ||||
<literal>CPAN:AUTHOR</literal> will be converted to | <literal>CPAN:AUTHOR</literal> will be converted to | ||||
<literal>authors/id/A/AU/AUTHOR</literal>.)</para> | <literal>authors/id/A/AU/AUTHOR</literal>.</para> | ||||
<para>When a port needs <application>Perl</application> support, | <para>When a port needs <application>Perl</application> support, | ||||
it should use <literal>USES=perl5</literal> with the optional | it must set <literal>USES=perl5</literal> with the optional | ||||
<varname>USE_PERL5</varname> like described in <link | <varname>USE_PERL5</varname> described in <link | ||||
Not Done Inline Actionss/like/as/ wblock: s/like/as/ | |||||
linkend="uses-perl5">the perl5 USES description</link>.</para> | linkend="uses-perl5">the perl5 USES description</link>.</para> | ||||
<table frame="none" xml:id="using-perl-variables"> | <table frame="none" xml:id="using-perl-variables"> | ||||
<title>Read-Only Variables for Ports That Use | <title>Read-Only Variables for Ports That Use | ||||
<application>Perl</application></title> | <application>Perl</application></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Read only variables</entry> | <entry>Read only variables</entry> | ||||
<entry>Means</entry> | <entry>Means</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>PERL</varname></entry> | <entry><varname>PERL</varname></entry> | ||||
<entry>The full path of the Perl 5 interpreter, | <entry>The full path of the Perl 5 interpreter, | ||||
either in the system or installed from a port, but | either in the system or installed from a port, but | ||||
without the version number. Use this if you need to | without the version number. Use this when the software | ||||
replace <quote><literal>#!</literal></quote>lines in | needs the path to the <application>Perl</application> | ||||
scripts.</entry> | interpreter. To replace | ||||
<quote><literal>#!</literal></quote>lines in scripts, | |||||
use <link | |||||
linkend="uses-shebangfix">USES=shebangfix</link>.</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PERL_VERSION</varname></entry> | <entry><varname>PERL_VERSION</varname></entry> | ||||
<entry>The full version of Perl | <entry>The full version of Perl | ||||
installed (e.g., <literal>5.8.9</literal>).</entry> | installed (for example, <literal>5.8.9</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PERL_LEVEL</varname></entry> | <entry><varname>PERL_LEVEL</varname></entry> | ||||
<entry>The installed Perl version as | <entry>The installed Perl version as | ||||
an integer of the form <literal>MNNNPP</literal> | an integer of the form <literal>MNNNPP</literal> | ||||
(e.g., <literal>500809</literal>).</entry> | (for example, <literal>500809</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PERL_ARCH</varname></entry> | <entry><varname>PERL_ARCH</varname></entry> | ||||
<entry>Where Perl stores architecture | <entry>Where Perl stores architecture | ||||
dependent libraries. Defaults to | dependent libraries. Defaults to | ||||
<literal>${ARCH}-freebsd</literal>.</entry> | <literal>${ARCH}-freebsd</literal>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PERL_PORT</varname></entry> | <entry><varname>PERL_PORT</varname></entry> | ||||
<entry>Name of the Perl port that is | <entry>Name of the Perl port that is | ||||
installed (e.g., <literal>perl5</literal>).</entry> | installed (for example, <literal>perl5</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>SITE_PERL</varname></entry> | <entry><varname>SITE_PERL</varname></entry> | ||||
<entry>Directory name where site specific | <entry>Directory name where site specific | ||||
Perl packages go. This value is | Perl packages go. This value is | ||||
added to <varname>PLIST_SUB</varname>.</entry> | added to <varname>PLIST_SUB</varname>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<note> | <note> | ||||
<para>Ports of Perl modules which do not have an official | <para>Ports of Perl modules which do not have an official | ||||
website should link to <systemitem>cpan.org</systemitem> in | website must link to <systemitem>cpan.org</systemitem> in | ||||
the WWW line of <filename>pkg-descr</filename>. The | the WWW line of <filename>pkg-descr</filename>. The | ||||
preferred URL form is | preferred URL form is | ||||
<literal>http://search.cpan.org/dist/Module-Name/</literal> | <literal>http://search.cpan.org/dist/Module-Name/</literal> | ||||
(including the trailing slash).</para> | (including the trailing slash).</para> | ||||
</note> | </note> | ||||
<note> | <note> | ||||
<para>Do not use <literal>${SITE_PERL}</literal> in dependency | <para>Do not use <literal>${SITE_PERL}</literal> in dependency | ||||
Show All 32 Lines | %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting> | ||||
<sect1 xml:id="using-x11"> | <sect1 xml:id="using-x11"> | ||||
<title>Using X11</title> | <title>Using X11</title> | ||||
<sect2 xml:id="x11-variables"> | <sect2 xml:id="x11-variables"> | ||||
<title>X.Org Components</title> | <title>X.Org Components</title> | ||||
<para>The X11 implementation available in The Ports Collection | <para>The X11 implementation available in The Ports Collection | ||||
is X.Org. If your application depends on X components, set | is X.Org. If the application depends on X components, set | ||||
<varname>USE_XORG</varname> to the list of required | <varname>USE_XORG</varname> to the list of required | ||||
components. Available components, at the time of writing, | components. Available components, at the time of writing, | ||||
are:</para> | are:</para> | ||||
<para><literal>bigreqsproto compositeproto damageproto dmx | <para><literal>bigreqsproto compositeproto damageproto dmx | ||||
dmxproto dri2proto dri3proto evieproto fixesproto | dmxproto dri2proto dri3proto evieproto fixesproto | ||||
fontcacheproto fontenc fontsproto fontutil glproto ice | fontcacheproto fontenc fontsproto fontutil glproto ice | ||||
inputproto kbproto libfs oldx pciaccess pixman presentproto | inputproto kbproto libfs oldx pciaccess pixman presentproto | ||||
printproto randrproto recordproto renderproto resourceproto | printproto randrproto recordproto renderproto resourceproto | ||||
scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 | scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 | ||||
xbitmaps xcb xcmiscproto xcomposite xcursor xdamage xdmcp | xbitmaps xcb xcmiscproto xcomposite xcursor xdamage xdmcp | ||||
xevie xext xextproto xf86bigfontproto xf86dgaproto | xevie xext xextproto xf86bigfontproto xf86dgaproto | ||||
xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto | xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto | ||||
xfixes xfont xfontcache xft xi xinerama xineramaproto | xfixes xfont xfontcache xft xi xinerama xineramaproto | ||||
xkbfile xkbui xmu xmuu xorg-macros xorg-server xp xpm | xkbfile xkbui xmu xmuu xorg-macros xorg-server xp xpm | ||||
xprintapputil xprintutil xproto xproxymngproto xrandr | xprintapputil xprintutil xproto xproxymngproto xrandr | ||||
xrender xres xscrnsaver xshmfence xt xtrans xtrap xtst xv | xrender xres xscrnsaver xshmfence xt xtrans xtrap xtst xv | ||||
xvmc xxf86dga xxf86misc xxf86vm</literal>.</para> | xvmc xxf86dga xxf86misc xxf86vm</literal>.</para> | ||||
<para>Always up-to-date list can be found in | <para>Always up-to-date list can be found in | ||||
<filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para> | <filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para> | ||||
<para>The Mesa Project is an effort to provide free OpenGL | <para>The Mesa Project is an effort to provide free OpenGL | ||||
implementation. You can specify a dependency on various | implementation. To specify a dependency on various | ||||
components of this project with <varname>USE_GL</varname> | components of this project, use <varname>USE_GL</varname>. | ||||
variable. Valid options are: | Valid options are: | ||||
<literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and | <literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and | ||||
<literal>linux</literal>. For backwards compatibility, the | <literal>linux</literal>. For backwards compatibility, the | ||||
value of <literal>yes</literal> maps to | value of <literal>yes</literal> maps to | ||||
<literal>glu</literal>.</para> | <literal>glu</literal>.</para> | ||||
<example xml:id="use-xorg-example"> | <example xml:id="use-xorg-example"> | ||||
<title><varname>USE_XORG</varname> Example</title> | <title><varname>USE_XORG</varname> Example</title> | ||||
Show All 27 Lines | USE_GL= glu</programlisting> | ||||
<programlisting># Use some X11 libraries | <programlisting># Use some X11 libraries | ||||
USE_XORG= x11 xpm</programlisting> | USE_XORG= x11 xpm</programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="x11-motif"> | <sect2 xml:id="x11-motif"> | ||||
<title>Ports That Require Motif</title> | <title>Ports That Require Motif</title> | ||||
<para>If your port requires a Motif library, define | <para>If the port requires a Motif library, define | ||||
<varname>USES= motif</varname> in the | <varname>USES= motif</varname> in the | ||||
<filename>Makefile</filename>. Default Motif implementation | <filename>Makefile</filename>. Default Motif implementation | ||||
is | is | ||||
<package role="port">x11-toolkits/open-motif</package>. | <package role="port">x11-toolkits/open-motif</package>. | ||||
Users can choose | Users can choose | ||||
<package role="port">x11-toolkits/lesstif</package> | <package role="port">x11-toolkits/lesstif</package> | ||||
instead by setting <varname>WANT_LESSTIF</varname> | instead by setting <varname>WANT_LESSTIF</varname> | ||||
variable in their <filename>make.conf</filename>.</para> | in their <filename>make.conf</filename>.</para> | ||||
<para>The <varname>MOTIFLIB</varname> variable will be set by | <para><varname>MOTIFLIB</varname> will be set by | ||||
<filename>motif.mk</filename> to reference the | <filename>motif.mk</filename> to reference the | ||||
appropriate Motif library. Please patch the source of your | appropriate Motif library. Please patch the source of the | ||||
port to use <literal>${MOTIFLIB}</literal> wherever | port to use <literal>${MOTIFLIB}</literal> wherever | ||||
the Motif library is referenced in the original | the Motif library is referenced in the original | ||||
<filename>Makefile</filename> or | <filename>Makefile</filename> or | ||||
<filename>Imakefile</filename>.</para> | <filename>Imakefile</filename>.</para> | ||||
<para>There are two common cases:</para> | <para>There are two common cases:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>If the port refers to the Motif library as | <para>If the port refers to the Motif library as | ||||
<literal>-lXm</literal> in its | <literal>-lXm</literal> in its | ||||
<filename>Makefile</filename> or | <filename>Makefile</filename> or | ||||
<filename>Imakefile</filename>, simply substitute | <filename>Imakefile</filename>, substitute | ||||
<literal>${MOTIFLIB}</literal> for it.</para> | <literal>${MOTIFLIB}</literal> for it.</para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>If the port uses <literal>XmClientLibs</literal> in | <para>If the port uses <literal>XmClientLibs</literal> in | ||||
its <filename>Imakefile</filename>, change it to | its <filename>Imakefile</filename>, change it to | ||||
<literal>${MOTIFLIB} ${XTOOLLIB} | <literal>${MOTIFLIB} ${XTOOLLIB} | ||||
${XLIB}</literal>.</para> | ${XLIB}</literal>.</para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>Note that <varname>MOTIFLIB</varname> (usually) expands | <para>Note that <varname>MOTIFLIB</varname> (usually) expands | ||||
to <literal>-L/usr/local/lib -lXm -lXp</literal> or | to <literal>-L/usr/local/lib -lXm -lXp</literal> or | ||||
<literal>/usr/local/lib/libXm.a</literal>, so there is no | <literal>/usr/local/lib/libXm.a</literal>, so there is no | ||||
need to add <literal>-L</literal> or <literal>-l</literal> | need to add <literal>-L</literal> or <literal>-l</literal> | ||||
in front.</para> | in front.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="x11-fonts"> | <sect2 xml:id="x11-fonts"> | ||||
<title>X11 Fonts</title> | <title>X11 Fonts</title> | ||||
<para>If your port installs fonts for the X Window System, put | <para>If the port installs fonts for the X Window System, put | ||||
them in | them in | ||||
<filename>LOCALBASE/lib/X11/fonts/local</filename>.</para> | <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="x11-fake-display"> | <sect2 xml:id="x11-fake-display"> | ||||
<title>Getting a Fake <envar>DISPLAY</envar> with Xvfb</title> | <title>Getting a Fake <envar>DISPLAY</envar> with Xvfb</title> | ||||
<para>Some applications require a working X11 display for | <para>Some applications require a working X11 display for | ||||
compilation to succeed. This pose a problem for machines | compilation to succeed. This pose a problem for machines | ||||
that operate headless. When the following variable is used, | that operate headless. When this variable is used, | ||||
the build infrastructure will start the virtual framebuffer | the build infrastructure will start the virtual framebuffer | ||||
X server. The working <envar>DISPLAY</envar> is then passed | X server. The working <envar>DISPLAY</envar> is then passed | ||||
to the build. See <link | to the build. See <link | ||||
linkend="uses-display"><literal>USES=display</literal></link> | linkend="uses-display"><literal>USES=display</literal></link> | ||||
for the possible arguments.</para> | for the possible arguments.</para> | ||||
<programlisting>USES= display</programlisting> | <programlisting>USES= display</programlisting> | ||||
</sect2> | </sect2> | ||||
Show All 17 Lines | USE_XORG= x11 xpm</programlisting> | ||||
encouraged for applications which can be used in a desktop | encouraged for applications which can be used in a desktop | ||||
environment.</para> | environment.</para> | ||||
<sect3 xml:id="desktop-entries-predefined"> | <sect3 xml:id="desktop-entries-predefined"> | ||||
<title>Using Predefined <filename>.desktop</filename> | <title>Using Predefined <filename>.desktop</filename> | ||||
Files</title> | Files</title> | ||||
<para>Ports that include predefined | <para>Ports that include predefined | ||||
<filename>*.desktop</filename> files should | <filename><replaceable>*</replaceable>.desktop</filename> must | ||||
Not Done Inline ActionsI think this is one where "should" is correct. wblock: I think this is one where "should" is correct. | |||||
Not Done Inline ActionsI don't think so, if it has those files, they must be listed in the plist, and be installed in the directory below. Maybe i should have used "must" and not "have to" ? mat: I don't think so, if it has those files, they must be listed in the plist, and be installed in… | |||||
Not Done Inline ActionsYes, "must" is more definite than "have to". wblock: Yes, "must" is more definite than "have to". | |||||
include those files in <filename>pkg-plist</filename> | include those files in <filename>pkg-plist</filename> | ||||
and install them in the | and install them in the | ||||
<filename>$LOCALBASE/share/applications</filename> | <filename>$LOCALBASE/share/applications</filename> | ||||
directory. The <link | directory. The <link | ||||
linkend="install-macros"><varname>INSTALL_DATA</varname> | linkend="install-macros"><varname>INSTALL_DATA</varname> | ||||
macro</link> is useful for installing these | macro</link> is useful for installing these | ||||
files.</para> | files.</para> | ||||
</sect3> | </sect3> | ||||
<sect3 xml:id="updating-desktop-database"> | <sect3 xml:id="updating-desktop-database"> | ||||
<title>Updating Desktop Database</title> | <title>Updating Desktop Database</title> | ||||
<para>If a port has a MimeType entry in its | <para>If a port has a MimeType entry in its | ||||
<filename><replaceable>portname</replaceable>.desktop</filename>, | <filename><replaceable>portname</replaceable>.desktop</filename>, | ||||
the desktop database must be updated after install and | the desktop database must be updated after install and | ||||
deinstall. To do this, define <varname>USES</varname>= | deinstall. To do this, define <varname>USES</varname>= | ||||
desktop-file-utils.</para> | desktop-file-utils.</para> | ||||
</sect3> | </sect3> | ||||
<sect3 xml:id="desktop-entries-macro"> | <sect3 xml:id="desktop-entries-macro"> | ||||
<title>Creating Desktop Entries with the | <title>Creating Desktop Entries with | ||||
<varname>DESKTOP_ENTRIES</varname> Macro</title> | <varname>DESKTOP_ENTRIES</varname></title> | ||||
<para>Desktop entries can be easily created for applications | <para>Desktop entries can be easily created for applications | ||||
by using the <varname>DESKTOP_ENTRIES</varname> variable. A | by using <varname>DESKTOP_ENTRIES</varname>. A | ||||
file named | file named | ||||
<filename><replaceable>name</replaceable>.desktop</filename> | <filename><replaceable>name</replaceable>.desktop</filename> | ||||
will be created, installed, and added to the | will be created, installed, and added to | ||||
<filename>pkg-plist</filename> automatically. Syntax | <filename>pkg-plist</filename> automatically. Syntax | ||||
is:</para> | is:</para> | ||||
<programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> | <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> | ||||
<para>The list of possible categories is available on the | <para>The list of possible categories is available on the | ||||
<link | <link | ||||
xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop | xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop | ||||
website</link>. <varname>StartupNotify</varname> | website</link>. <varname>StartupNotify</varname> | ||||
indicates whether the application is compatible with | indicates whether the application is compatible with | ||||
<emphasis>startup notifications</emphasis>. These are | <emphasis>startup notifications</emphasis>. These are | ||||
typically a graphic indicator like a clock that appear at | typically a graphic indicator like a clock that appear at | ||||
the mouse pointer, menu, or panel to give the user an | the mouse pointer, menu, or panel to give the user an | ||||
indication when a program is starting. A program that is | indication when a program is starting. A program that is | ||||
compatible with startup notifications clears the indicator | compatible with startup notifications clears the indicator | ||||
after it has started. Programs that are not compatible | after it has started. Programs that are not compatible | ||||
with startup notifications would never clear the indicator | with startup notifications would never clear the indicator | ||||
(potentially confusing and infuriating the user), and | (potentially confusing and infuriating the user), and | ||||
should have <varname>StartupNotify</varname> set to | must have <varname>StartupNotify</varname> set to | ||||
<literal>false</literal> so the indicator is not shown at | <literal>false</literal> so the indicator is not shown at | ||||
all.</para> | all.</para> | ||||
<para>Example:</para> | <para>Example:</para> | ||||
<programlisting>DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ | <programlisting>DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ | ||||
"${DATADIR}/xtra/graf/tome-128.png" \ | "${DATADIR}/xtra/graf/tome-128.png" \ | ||||
"tome -v -g" "Application;Game;RolePlaying;" \ | "tome -v -g" "Application;Game;RolePlaying;" \ | ||||
Show All 14 Lines | USE_XORG= x11 xpm</programlisting> | ||||
<sect1 xml:id="using-qt"> | <sect1 xml:id="using-qt"> | ||||
<title>Using Qt</title> | <title>Using Qt</title> | ||||
<sect2 xml:id="qt-common"> | <sect2 xml:id="qt-common"> | ||||
<title>Ports That Require Qt</title> | <title>Ports That Require Qt</title> | ||||
<para>The Ports Collection provides support for Qt 4 and Qt 5 | <para>The Ports Collection provides support for Qt 4 and Qt 5 | ||||
frameworks with the | frameworks with | ||||
<varname>USE_QT<replaceable>x</replaceable></varname> | <varname>USE_QT<replaceable>x</replaceable></varname>, | ||||
variable, where <replaceable>x</replaceable> is | where <replaceable>x</replaceable> is | ||||
<literal>4</literal> or <literal>5</literal>. | <literal>4</literal> or <literal>5</literal>. | ||||
<varname>USE_QT<replaceable>x</replaceable></varname> should | Set <varname>USE_QT<replaceable>x</replaceable></varname> | ||||
be set to the list of required Qt components (libraries, | to the list of required Qt components (libraries, | ||||
tools, plugins). The Qt 4 and Qt 5 frameworks are quite | tools, plugins). The Qt 4 and Qt 5 frameworks are quite | ||||
similar. The main difference is the set of supported | similar. The main difference is the set of supported | ||||
components.</para> | components.</para> | ||||
<para>The Qt framework exports a number of variables which can | <para>The Qt framework exports a number of variables which can | ||||
be used by ports, some of them listed below:</para> | be used by ports, some of them listed below:</para> | ||||
<table frame="none" xml:id="using-qt-variables"> | <table frame="none" xml:id="using-qt-variables"> | ||||
▲ Show 20 Lines • Show All 65 Lines • ▼ Show 20 Lines | CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ | ||||
QMAKESPEC="${QMAKESPEC}" | QMAKESPEC="${QMAKESPEC}" | ||||
PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ | PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ | ||||
QT_LIBDIR=${QT_LIBDIR_REL} \ | QT_LIBDIR=${QT_LIBDIR_REL} \ | ||||
QT_PLUGINDIR=${QT_PLUGINDIR_REL}</programlisting> | QT_PLUGINDIR=${QT_PLUGINDIR_REL}</programlisting> | ||||
<para>Some configure scripts do not support the arguments above. | <para>Some configure scripts do not support the arguments above. | ||||
To suppress modification of<varname>CONFIGURE_ENV</varname> | To suppress modification of<varname>CONFIGURE_ENV</varname> | ||||
and <varname>CONFIGURE_ARGS</varname>, set the | and <varname>CONFIGURE_ARGS</varname>, set | ||||
<varname>QT_NONSTANDARD</varname> variable.</para> | <varname>QT_NONSTANDARD</varname>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="qt-components"> | <sect2 xml:id="qt-components"> | ||||
<title>Component Selection</title> | <title>Component Selection</title> | ||||
<para>Individual Qt tool and library dependencies must be | <para>Individual Qt tool and library dependencies must be | ||||
specified in the | specified in | ||||
<varname>USE_QT<replaceable>x</replaceable></varname> | <varname>USE_QT<replaceable>x</replaceable></varname>. | ||||
variable. Every component can be suffixed with | Every component can be suffixed with | ||||
<literal>_build</literal> or <literal>_run</literal>, the | <literal>_build</literal> or <literal>_run</literal>, the | ||||
suffix indicating whether the component should be depended on | suffix indicating whether the dependency on the component is | ||||
at buildtime or runtime. If unsuffixed, the component will be | at buildtime or runtime. If unsuffixed, the component will be | ||||
depended on at both build- and runtime. Usually, library | depended on at both build- and runtime. Usually, library | ||||
components should be specified unsuffixed, tool components | components are specified unsuffixed, tool components | ||||
should be specified with the <literal>_build</literal> suffix | are mostly specified with the <literal>_build</literal> suffix | ||||
and plugin components should be specified with the | and plugin components are specified with the | ||||
<literal>_run</literal> suffix. The most commonly used | <literal>_run</literal> suffix. The most commonly used | ||||
components are listed below (all available components are | components are listed below (all available components are | ||||
listed in <varname>_USE_QT_ALL</varname>, | listed in <varname>_USE_QT_ALL</varname>, | ||||
<varname>_USE_QT4_ONLY</varname>, and | <varname>_USE_QT4_ONLY</varname>, and | ||||
<varname>_USE_QT5_ONLY</varname> variables in | <varname>_USE_QT5_ONLY</varname> in | ||||
<filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para> | <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para> | ||||
<table frame="none" xml:id="using-qt-library-list"> | <table frame="none" xml:id="using-qt-library-list"> | ||||
<title>Available Qt Library Components</title> | <title>Available Qt Library Components</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
▲ Show 20 Lines • Show All 251 Lines • ▼ Show 20 Lines | USE_QT5= buildtools_build</programlisting> | ||||
on, which in turn leads to certain loose ends, | on, which in turn leads to certain loose ends, | ||||
like:</para> | like:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para><emphasis>Missing additional include | <para><emphasis>Missing additional include | ||||
paths.</emphasis> Many applications come with | paths.</emphasis> Many applications come with | ||||
system tray icon support, but neglect to look for | system tray icon support, but neglect to look for | ||||
includes and/or libraries in the X11 directories. You | includes and/or libraries in the X11 directories. To add | ||||
can tell <command>qmake</command> to add directories to | directories to <command>qmake</command>'s | ||||
the include and library search paths via the command | include and library search paths via the command | ||||
line, for example:</para> | line, use:</para> | ||||
<programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ | <programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ | ||||
LIBS+=-L${LOCALBASE}/lib</programlisting> | LIBS+=-L${LOCALBASE}/lib</programlisting> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para><emphasis>Bogus installation paths.</emphasis> | <para><emphasis>Bogus installation paths.</emphasis> | ||||
Sometimes data such as icons or .desktop files are by | Sometimes data such as icons or .desktop files are by | ||||
Show All 15 Lines | <sect1 xml:id="using-kde"> | ||||
<sect2 xml:id="kde4-variables"> | <sect2 xml:id="kde4-variables"> | ||||
<title>KDE 4 Variable Definitions</title> | <title>KDE 4 Variable Definitions</title> | ||||
<para>If the application depends on KDE 4, set | <para>If the application depends on KDE 4, set | ||||
<varname>USE_KDE4</varname> to the list of required | <varname>USE_KDE4</varname> to the list of required | ||||
components. <literal>_build</literal> and | components. <literal>_build</literal> and | ||||
<literal>_run</literal> suffixes can be used to force | <literal>_run</literal> suffixes can be used to force | ||||
components dependency type (e.g., | components dependency type (for example, | ||||
<literal>baseapps_run</literal>). If no suffix is set, a | <literal>baseapps_run</literal>). If no suffix is set, a | ||||
default dependency type will be used. If you want to force | default dependency type will be used. To force | ||||
both types, add the component twice with both suffixes | both types, add the component twice with both suffixes | ||||
(e.g., <literal>automoc4_build automoc4_run</literal>). The | (for example, <literal>automoc4_build automoc4_run</literal>). The | ||||
most commonly used components are listed below (up-to-date | most commonly used components are listed below (up-to-date | ||||
components are documented at the top of | components are documented at the top of | ||||
<filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para> | <filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para> | ||||
<table frame="none" xml:id="using-kde-components"> | <table frame="none" xml:id="using-kde-components"> | ||||
<title>Available KDE 4 Components</title> | <title>Available KDE 4 Components</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
▲ Show 20 Lines • Show All 155 Lines • ▼ Show 20 Lines | <para>This is a simple example for a KDE 4 port. | ||||
<xref linkend="using-cmake"/> for detailed usage). | <xref linkend="using-cmake"/> for detailed usage). | ||||
<varname>USE_KDE4</varname> brings dependency on KDE | <varname>USE_KDE4</varname> brings dependency on KDE | ||||
libraries and makes port using | libraries and makes port using | ||||
<command>automoc4</command> at build stage. | <command>automoc4</command> at build stage. | ||||
Required KDE components and other dependencies can be | Required KDE components and other dependencies can be | ||||
determined through configure log. | determined through configure log. | ||||
<varname>USE_KDE4</varname> does not imply | <varname>USE_KDE4</varname> does not imply | ||||
<varname>USE_QT4</varname>. If a port requires some | <varname>USE_QT4</varname>. If a port requires some | ||||
Qt 4 components, they should be specified in | Qt 4 components, specify them in | ||||
<varname>USE_QT4</varname>.</para> | <varname>USE_QT4</varname>.</para> | ||||
<programlisting>USES= cmake:outsource | <programlisting>USES= cmake:outsource | ||||
USE_KDE4= kdelibs kdeprefix automoc4 | USE_KDE4= kdelibs kdeprefix automoc4 | ||||
USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> | USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-java"> | <sect1 xml:id="using-java"> | ||||
<title>Using Java</title> | <title>Using Java</title> | ||||
<sect2 xml:id="java-variables"> | <sect2 xml:id="java-variables"> | ||||
<title>Variable Definitions</title> | <title>Variable Definitions</title> | ||||
<para>If your port needs a Java™ Development Kit | <para>If the port needs a Java™ Development Kit | ||||
(JDK™) to either build, run or even extract the | (<acronym>JDK</acronym>™) to either build, run or even extract the | ||||
distfile, then it should define | distfile, then define | ||||
<varname>USE_JAVA</varname>.</para> | <varname>USE_JAVA</varname>.</para> | ||||
<para>There are several JDKs in the ports collection, from | <para>There are several <acronym>JDK</acronym>s in the ports collection, from | ||||
various vendors, and in several versions. If your port must | various vendors, and in several versions. If the port must | ||||
use one of these versions, you can define which one. The | use one of these versions, define which one. The | ||||
most current version, and &os; default is | most current version, and &os; default is | ||||
<package role="port">java/openjdk6</package>.</para> | <package role="port">java/openjdk6</package>.</para> | ||||
<table frame="none" xml:id="using-java-variables"> | <table frame="none" xml:id="using-java-variables"> | ||||
<title>Variables Which May be Set by Ports That Use | <title>Variables Which May be Set by Ports That Use | ||||
Java</title> | Java</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Variable</entry> | <entry>Variable</entry> | ||||
<entry>Means</entry> | <entry>Means</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>USE_JAVA</varname></entry> | <entry><varname>USE_JAVA</varname></entry> | ||||
<entry>Should be defined for the remaining variables | <entry>Define for the remaining variables | ||||
Not Done Inline Actionss/so that/for/ wblock: s/so that/for/ | |||||
to have any effect.</entry> | to have any effect.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_VERSION</varname></entry> | <entry><varname>JAVA_VERSION</varname></entry> | ||||
<entry>List of space-separated suitable Java versions | <entry>List of space-separated suitable Java versions | ||||
for the port. An optional <literal>"+"</literal> | for the port. An optional <literal>"+"</literal> | ||||
allows you to specify a range of versions (allowed | allows specifying a range of versions (allowed | ||||
values: | values: | ||||
<literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry> | <literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_OS</varname></entry> | <entry><varname>JAVA_OS</varname></entry> | ||||
<entry>List of space-separated suitable JDK port | <entry>List of space-separated suitable <acronym>JDK</acronym> port | ||||
operating systems for the port (allowed values: | operating systems for the port (allowed values: | ||||
<literal>native linux</literal>).</entry> | <literal>native linux</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_VENDOR</varname></entry> | <entry><varname>JAVA_VENDOR</varname></entry> | ||||
<entry>List of space-separated suitable JDK port | <entry>List of space-separated suitable <acronym>JDK</acronym> port | ||||
vendors for the port (allowed values: | vendors for the port (allowed values: | ||||
<literal>freebsd bsdjava sun | <literal>freebsd bsdjava sun | ||||
openjdk</literal>).</entry> | openjdk</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_BUILD</varname></entry> | <entry><varname>JAVA_BUILD</varname></entry> | ||||
<entry>When set, it means that the selected JDK port | <entry>When set, add the selected <acronym>JDK</acronym> port to the build | ||||
Not Done Inline ActionsWhen set, add the selected JDK port to the build dependencies. wblock: When set, add the selected JDK port to the build dependencies. | |||||
Not Done Inline ActionsShould I add <acronym> around JDK too ? should I do this everywhere ? mat: Should I add <acronym> around JDK too ? should I do this everywhere ? | |||||
Not Done Inline ActionsYes. Anything that is an acronym should have <acronym> tags. wblock: Yes. Anything that is an acronym should have <acronym> tags. | |||||
should be added to the build dependencies of the | dependencies.</entry> | ||||
port.</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_RUN</varname></entry> | <entry><varname>JAVA_RUN</varname></entry> | ||||
<entry>When set, it means that the selected JDK port | <entry>When set, add the selected <acronym>JDK</acronym> port to the run | ||||
should be added to the run dependencies of the | dependencies.</entry> | ||||
Not Done Inline ActionsWhen set, add the selected JDK port to the run dependencies. wblock: When set, add the selected JDK port to the run dependencies. | |||||
port.</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_EXTRACT</varname></entry> | <entry><varname>JAVA_EXTRACT</varname></entry> | ||||
<entry>When set, it means that the selected JDK port | <entry>When set, add the selected <acronym>JDK</acronym> port to the | ||||
should be added to the extract dependencies of the | extract dependencies.</entry> | ||||
Not Done Inline ActionsWhen set, add the selected JDK port to the extract dependencies. wblock: When set, add the selected JDK port to the extract dependencies. | |||||
port.</entry> | |||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>Below is the list of all settings a port will receive | <para>Below is the list of all settings a port will receive | ||||
after setting <varname>USE_JAVA</varname>:</para> | after setting <varname>USE_JAVA</varname>:</para> | ||||
<table frame="none" xml:id="using-java-variables2"> | <table frame="none" xml:id="using-java-variables2"> | ||||
<title>Variables Provided to Ports That Use Java</title> | <title>Variables Provided to Ports That Use Java</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Variable</entry> | <entry>Variable</entry> | ||||
<entry>Value</entry> | <entry>Value</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT</varname></entry> | <entry><varname>JAVA_PORT</varname></entry> | ||||
<entry>The name of the JDK port (e.g., | <entry>The name of the <acronym>JDK</acronym> port (for example, | ||||
<literal>'java/openjdk6'</literal>).</entry> | <literal>java/openjdk6</literal>).</entry> | ||||
Not Done Inline ActionsShould this have the single quotes? wblock: Should this have the single quotes? | |||||
Not Done Inline Actionsnope. mat: nope. | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT_VERSION</varname></entry> | <entry><varname>JAVA_PORT_VERSION</varname></entry> | ||||
<entry>The full version of the JDK port (e.g., | <entry>The full version of the <acronym>JDK</acronym> port (for example, | ||||
<literal>'1.6.0'</literal>). If you only need the | <literal>1.6.0</literal>). Only the first two | ||||
first two digits of this version number, use | digits of this version number are needed, use | ||||
<varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry> | <varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT_OS</varname></entry> | <entry><varname>JAVA_PORT_OS</varname></entry> | ||||
<entry>The operating system used by the JDK port | <entry>The operating system used by the <acronym>JDK</acronym> port | ||||
(e.g., <literal>'native'</literal>).</entry> | (for example, <literal>'native'</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT_VENDOR</varname></entry> | <entry><varname>JAVA_PORT_VENDOR</varname></entry> | ||||
<entry>The vendor of the JDK port (e.g., | <entry>The vendor of the <acronym>JDK</acronym> port (for example, | ||||
<literal>'openjdk'</literal>).</entry> | <literal>'openjdk'</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> | <entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> | ||||
<entry>Description of the operating system used by the | <entry>Description of the operating system used by the | ||||
JDK port (e.g., | <acronym>JDK</acronym> port (for example, | ||||
<literal>'Native'</literal>).</entry> | <literal>'Native'</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> | <entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> | ||||
<entry>Description of the vendor of the JDK port | <entry>Description of the vendor of the <acronym>JDK</acronym> port | ||||
(e.g., <literal>'OpenJDK BSD Porting | (for example, <literal>'OpenJDK BSD Porting | ||||
Team'</literal>).</entry> | Team'</literal>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_HOME</varname></entry> | <entry><varname>JAVA_HOME</varname></entry> | ||||
<entry>Path to the installation directory of the JDK | <entry>Path to the installation directory of the <acronym>JDK</acronym> | ||||
(e.g., | (for example, | ||||
<filename>'/usr/local/openjdk6'</filename>).</entry> | <filename>'/usr/local/openjdk6'</filename>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVAC</varname></entry> | <entry><varname>JAVAC</varname></entry> | ||||
<entry>Path to the Java compiler to use (e.g., | <entry>Path to the Java compiler to use (for example, | ||||
<filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry> | <filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAR</varname></entry> | <entry><varname>JAR</varname></entry> | ||||
<entry>Path to the <command>jar</command> tool to use | <entry>Path to the <command>jar</command> tool to use | ||||
(e.g., | (for example, | ||||
<filename>'/usr/local/openjdk6/bin/jar'</filename> | <filename>'/usr/local/openjdk6/bin/jar'</filename> | ||||
or | or | ||||
<filename>'/usr/local/bin/fastjar'</filename>).</entry> | <filename>'/usr/local/bin/fastjar'</filename>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>APPLETVIEWER</varname></entry> | <entry><varname>APPLETVIEWER</varname></entry> | ||||
<entry>Path to the <command>appletviewer</command> | <entry>Path to the <command>appletviewer</command> | ||||
utility (e.g., | utility (for example, | ||||
<filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> | <filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA</varname></entry> | <entry><varname>JAVA</varname></entry> | ||||
<entry>Path to the <command>java</command> executable. | <entry>Path to the <command>java</command> executable. | ||||
Use this for executing Java programs (e.g., | Use this for executing Java programs (for example, | ||||
<filename>'/usr/local/openjdk6/bin/java'</filename>).</entry> | <filename>'/usr/local/openjdk6/bin/java'</filename>).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVADOC</varname></entry> | <entry><varname>JAVADOC</varname></entry> | ||||
<entry>Path to the <command>javadoc</command> utility | <entry>Path to the <command>javadoc</command> utility | ||||
program.</entry> | program.</entry> | ||||
</row> | </row> | ||||
▲ Show 20 Lines • Show All 49 Lines • ▼ Show 20 Lines | <command>rmiregistry</command>.</entry> | ||||
<row> | <row> | ||||
<entry><varname>RMID</varname></entry> | <entry><varname>RMID</varname></entry> | ||||
<entry>Path to the RMI daemon program | <entry>Path to the RMI daemon program | ||||
<command>rmid</command>.</entry> | <command>rmid</command>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVA_CLASSES</varname></entry> | <entry><varname>JAVA_CLASSES</varname></entry> | ||||
<entry>Path to the archive that contains the JDK class | <entry>Path to the archive that contains the <acronym>JDK</acronym> class | ||||
files, | files, | ||||
<filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> | <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>You may use the <literal>java-debug</literal> make | <para>Use the <buildtarget>java-debug</buildtarget> make | ||||
target to get information for debugging your port. It will | target to get information for debugging the port. It will | ||||
display the value of many of the forecited variables.</para> | display the value of many of the previously listed variables.</para> | ||||
Not Done Inline Actions"forecited" is a word, but a rare one. "previously listed variables" is better. wblock: "forecited" is a word, but a rare one. "previously listed variables" is better. | |||||
<para>Additionally, the following constants are defined so all | <para>Additionally, these constants are defined so all | ||||
Java ports may be installed in a consistent way:</para> | Java ports may be installed in a consistent way:</para> | ||||
<table frame="none" xml:id="using-java-constants"> | <table frame="none" xml:id="using-java-constants"> | ||||
<title>Constants Defined for Ports That Use Java</title> | <title>Constants Defined for Ports That Use Java</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Constant</entry> | <entry>Constant</entry> | ||||
<entry>Value</entry> | <entry>Value</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>JAVASHAREDIR</varname></entry> | <entry><varname>JAVASHAREDIR</varname></entry> | ||||
<entry>The base directory for everything related to | <entry>The base directory for everything related to | ||||
Java. Default: | Java. Default: | ||||
<filename>${PREFIX}/share/java</filename>.</entry> | <filename>${PREFIX}/share/java</filename>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVAJARDIR</varname></entry> | <entry><varname>JAVAJARDIR</varname></entry> | ||||
<entry>The directory where JAR files should be | <entry>The directory where JAR files is | ||||
Not Done Inline Actionss/is/are/ wblock: s/is/are/ | |||||
installed. Default: | installed. Default: | ||||
<filename>${JAVASHAREDIR}/classes</filename>.</entry> | <filename>${JAVASHAREDIR}/classes</filename>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>JAVALIBDIR</varname></entry> | <entry><varname>JAVALIBDIR</varname></entry> | ||||
<entry>The directory where JAR files installed by | <entry>The directory where JAR files installed by | ||||
other ports are located. Default: | other ports are located. Default: | ||||
Show All 10 Lines | <varname>SUB_LIST</varname>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="java-building-with-ant"> | <sect2 xml:id="java-building-with-ant"> | ||||
<title>Building with Ant</title> | <title>Building with Ant</title> | ||||
<para>When the port is to be built using Apache Ant, it has to | <para>When the port is to be built using Apache Ant, it has to | ||||
define <varname>USE_ANT</varname>. Ant is thus considered | define <varname>USE_ANT</varname>. Ant is thus considered | ||||
to be the sub-make command. When no | to be the sub-make command. When no | ||||
<literal>do-build</literal> target is defined by the port, a | <buildtarget>do-build</buildtarget> target is defined by the port, a | ||||
default one will be set that simply runs Ant according to | default one will be set that runs Ant according to | ||||
<varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> | <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> | ||||
and <varname>ALL_TARGET</varname>. This is similar to the | and <varname>ALL_TARGET</varname>. This is similar to the | ||||
<varname>USES= gmake</varname> mechanism, which is | <literal>USES= gmake</literal> mechanism, which is | ||||
documented in <xref linkend="building"/>.</para> | documented in <xref linkend="building"/>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="java-best-practices"> | <sect2 xml:id="java-best-practices"> | ||||
<title>Best Practices</title> | <title>Best Practices</title> | ||||
<para>When porting a Java library, your port should install | <para>When porting a Java library, the port has to install | ||||
the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and | the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and | ||||
everything else under | everything else under | ||||
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for | <filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for | ||||
the documentation, see below). In order to reduce the | the documentation, see below). To reduce the | ||||
packing file size, you may reference the JAR file(s) | packing file size, reference the JAR file(s) | ||||
directly in the <filename>Makefile</filename>. Just use the | directly in the <filename>Makefile</filename>. Use this | ||||
following statement (where <filename>myport.jar</filename> | statement (where <filename><replaceable>myport</replaceable>.jar</filename> | ||||
is the name of the JAR file installed as part of the | is the name of the JAR file installed as part of the | ||||
port):</para> | port):</para> | ||||
<programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting> | <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/<replaceable>myport</replaceable>.jar</programlisting> | ||||
<para>When porting a Java application, the port usually | <para>When porting a Java application, the port usually | ||||
installs everything under a single directory (including its | installs everything under a single directory (including its | ||||
JAR dependencies). The use of | JAR dependencies). The use of | ||||
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly | <filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly | ||||
encouraged in this regard. It is up the porter to decide | encouraged in this regard. It is up the porter to decide | ||||
whether the port should install the additional JAR | whether the port installs the additional JAR | ||||
dependencies under this directory or directly use the | dependencies under this directory or uses the | ||||
Not Done Inline Actionss/use/uses/ wblock: s/use/uses/ | |||||
already installed ones (from | already installed ones (from | ||||
<filename>${JAVAJARDIR}</filename>).</para> | <filename>${JAVAJARDIR}</filename>).</para> | ||||
<para>When porting a &java; application that requires an | <para>When porting a &java; application that requires an | ||||
application server such as | application server such as | ||||
<package role="port">www/tomcat7</package> to run the | <package role="port">www/tomcat7</package> to run the | ||||
service, it is quite common for a vendor to distribute a | service, it is quite common for a vendor to distribute a | ||||
<filename>.war</filename> file. A <filename>.war</filename> | <filename>.war</filename>. A <filename>.war</filename> | ||||
file is a Web application ARchive and is extracted when | is a Web application ARchive and is extracted when | ||||
called by the application. Avoid adding a | called by the application. Avoid adding a | ||||
<filename>.war</filename> | <filename>.war</filename> | ||||
file to the <filename>pkg-plist</filename>. | to <filename>pkg-plist</filename>. | ||||
It is not considered best practice. An application server | It is not considered best practice. An application server | ||||
will expand the <filename>war</filename> archive, but not | will expand <application>war</application> archive, but not | ||||
clean it up properly if the port is removed. A more | clean it up properly if the port is removed. A more | ||||
desirable way of working with this file is to extract the | desirable way of working with this file is to extract the | ||||
archive, then install the files, and lastly add these files | archive, then install the files, and lastly add these files | ||||
to <filename>pkg-plist</filename>.</para> | to <filename>pkg-plist</filename>.</para> | ||||
<programlisting>TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 | <programlisting>TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 | ||||
WEBAPPDIR= myapplication | WEBAPPDIR= myapplication | ||||
post-extract: | post-extract: | ||||
@${MKDIR} ${WRKDIR}/${PORTDIRNAME} | @${MKDIR} ${WRKDIR}/${PORTDIRNAME} | ||||
@${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} | @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} | ||||
do-install: | do-install: | ||||
cd ${WRKDIR} && \ | cd ${WRKDIR} && \ | ||||
${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} | ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} | ||||
@cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting> | @cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting> | ||||
<para>Regardless of the type of your port (library or | <para>Regardless of the type of port (library or | ||||
application), the additional documentation should be | application), the additional documentation is | ||||
Not Done Inline Actionss/the// wblock: s/the// | |||||
Not Done Inline Actionss/must/is/ wblock: s/must/is/ | |||||
installed in the | installed in the | ||||
<link linkend="install-documentation">same location</link> | <link linkend="install-documentation">same location</link> | ||||
as for any other port. The JavaDoc tool is known to produce | as for any other port. The JavaDoc tool is known to produce | ||||
a different set of files depending on the version of the JDK | a different set of files depending on the version of the <acronym>JDK</acronym> | ||||
that is used. For ports that do not enforce the use of a | that is used. For ports that do not enforce the use of a | ||||
particular JDK, it is therefore a complex task to specify | particular <acronym>JDK</acronym>, it is therefore a complex task to specify | ||||
the packing list (<filename>pkg-plist</filename>). This is | the packing list (<filename>pkg-plist</filename>). This is | ||||
one reason why porters are strongly encouraged to use the | one reason why porters are strongly encouraged to use | ||||
<varname>PORTDOCS</varname> macro. Moreover, even if you | <varname>PORTDOCS</varname>. Moreover, even if the | ||||
can predict the set of files that will be generated by | set of files that will be generated by | ||||
<command>javadoc</command>, the size of the resulting | <command>javadoc</command> can be predicted, the size of the resulting | ||||
<filename>pkg-plist</filename> advocates for the use of | <filename>pkg-plist</filename> advocates for the use of | ||||
<varname>PORTDOCS</varname>.</para> | <varname>PORTDOCS</varname>.</para> | ||||
<para>The default value for <varname>DATADIR</varname> is | <para>The default value for <varname>DATADIR</varname> is | ||||
<filename>${PREFIX}/share/${PORTNAME}</filename>. It is a | <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a | ||||
good idea to override <varname>DATADIR</varname> to | good idea to override <varname>DATADIR</varname> to | ||||
<filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java | <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java | ||||
ports. Indeed, <varname>DATADIR</varname> is automatically | ports. Indeed, <varname>DATADIR</varname> is automatically | ||||
added to <varname>PLIST_SUB</varname> (documented in | added to <varname>PLIST_SUB</varname> (documented in | ||||
<xref linkend="plist-sub"/>) so you may use | <xref linkend="plist-sub"/>) so use | ||||
<literal>%%DATADIR%%</literal> directly in | <literal>%%DATADIR%%</literal> directly in | ||||
<filename>pkg-plist</filename>.</para> | <filename>pkg-plist</filename>.</para> | ||||
<para>As for the choice of building Java ports from source or | <para>As for the choice of building Java ports from source or | ||||
directly installing them from a binary distribution, there | directly installing them from a binary distribution, there | ||||
is no defined policy at the time of writing. However, | is no defined policy at the time of writing. However, | ||||
people from the | people from the | ||||
<link xlink:href="http://www.freebsd.org/java/">&os; Java | <link xlink:href="http://www.freebsd.org/java/">&os; Java | ||||
Project</link> encourage porters to have their ports | Project</link> encourage porters to have their ports | ||||
built from source whenever it is a trivial task.</para> | built from source whenever it is a trivial task.</para> | ||||
<para>All the features that have been presented in this | <para>All the features that have been presented in this | ||||
section are implemented in <filename>bsd.java.mk</filename>. | section are implemented in <filename>bsd.java.mk</filename>. | ||||
If you ever think that your port needs more sophisticated | If the port needs more sophisticated | ||||
Java support, please first have a look at the <link | Java support, please first have a look at the <link | ||||
xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk | xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log">bsd.java.mk | ||||
<application>Subversion</application> log</link> as it | <application>Subversion</application> log</link> as it | ||||
usually takes some time to document the latest features. | usually takes some time to document the latest features. | ||||
Then, if you think the support you are lacking would be | Then, if the needed support that is lacking would be | ||||
beneficial to many other Java ports, feel free to discuss it | beneficial to many other Java ports, feel free to discuss it | ||||
on the &a.java;.</para> | on the &a.java;.</para> | ||||
<para>Although there is a <literal>java</literal> category for | <para>Although there is a <literal>java</literal> category for | ||||
PRs, it refers to the JDK porting effort from the &os; Java | PRs, it refers to the <acronym>JDK</acronym> porting effort from the &os; Java | ||||
project. Therefore, you should submit your Java port in the | project. Therefore, submit the Java port in the | ||||
<literal>ports</literal> category as for any other port, | <literal>ports</literal> category as for any other port, | ||||
unless the issue you are trying to resolve is related to | unless the issue is related to | ||||
either a JDK implementation or | either a <acronym>JDK</acronym> implementation or | ||||
<filename>bsd.java.mk</filename>.</para> | <filename>bsd.java.mk</filename>.</para> | ||||
<para>Similarly, there is a defined policy regarding the | <para>Similarly, there is a defined policy regarding the | ||||
<varname>CATEGORIES</varname> of a Java port, which is | <varname>CATEGORIES</varname> of a Java port, which is | ||||
detailed in <xref linkend="makefile-categories"/>.</para> | detailed in <xref linkend="makefile-categories"/>.</para> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
Show All 20 Lines | <tgroup cols="2"> | ||||
in <filename>ports/Mk/bsd.apache.mk</filename> and | in <filename>ports/Mk/bsd.apache.mk</filename> and | ||||
at <link | at <link | ||||
xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> | xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>APXS</varname></entry> | <entry><varname>APXS</varname></entry> | ||||
<entry>Full path to the <command>apxs</command> | <entry>Full path to the <command>apxs</command> | ||||
binary. Can be overridden in your port.</entry> | binary. Can be overridden in the port.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>HTTPD</varname></entry> | <entry><varname>HTTPD</varname></entry> | ||||
<entry>Full path to the <command>httpd</command> | <entry>Full path to the <command>httpd</command> | ||||
binary. Can be overridden in your port.</entry> | binary. Can be overridden in the port.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>APACHE_VERSION</varname></entry> | <entry><varname>APACHE_VERSION</varname></entry> | ||||
<entry>The version of present Apache installation | <entry>The version of present Apache installation | ||||
(read-only variable). This variable is only | (read-only variable). This variable is only | ||||
available after inclusion of | available after inclusion of | ||||
<filename>bsd.port.pre.mk</filename>. Possible | <filename>bsd.port.pre.mk</filename>. Possible | ||||
▲ Show 20 Lines • Show All 78 Lines • ▼ Show 20 Lines | <tgroup cols="2"> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="web-apps"> | <sect2 xml:id="web-apps"> | ||||
<title>Web Applications</title> | <title>Web Applications</title> | ||||
<para>Web applications should be installed into | <para>Web applications must be installed into | ||||
<filename>PREFIX/www/<replaceable>appname</replaceable></filename>. | <filename>PREFIX/www/<replaceable>appname</replaceable></filename>. | ||||
For your convenience, this path is available both in | This path is available both in | ||||
<filename>Makefile</filename> and in | <filename>Makefile</filename> and in | ||||
<filename>pkg-plist</filename> as <varname>WWWDIR</varname>, | <filename>pkg-plist</filename> as <varname>WWWDIR</varname>, | ||||
and the path relative to <varname>PREFIX</varname> is | and the path relative to <varname>PREFIX</varname> is | ||||
available in <filename>Makefile</filename> as | available in <filename>Makefile</filename> as | ||||
<varname>WWWDIR_REL</varname>.</para> | <varname>WWWDIR_REL</varname>.</para> | ||||
<para>The user and group of web server process are available | <para>The user and group of web server process are available | ||||
as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>, | as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>, | ||||
in case you need to change the ownership of some files. The | in case the ownership of some files needs to be changed. The | ||||
default values of both are <literal>www</literal>. If you | default values of both are <literal>www</literal>. Use | ||||
want different values for your port, use | <literal>WWWOWN?= myuser</literal> and <literal>WWWGRP?= | ||||
<literal>WWWOWN?= myuser</literal> notation, to allow user | mygroup</literal> if the port needs different values. This | ||||
Not Done Inline Actionsmygroup</literal> if the port needs different values. This wblock: mygroup</literal> if the port needs different values. This | |||||
to override it easily.</para> | allows the user to override them easily.</para> | ||||
Not Done Inline Actionsallows the user to override them easily.</para> wblock: allows the user to override them easily.</para> | |||||
<para>Do not depend on Apache unless the web app explicitly | <para>Do not depend on Apache unless the web app explicitly | ||||
needs Apache. Respect that users may wish to run your web | needs Apache. Respect that users may wish to run a web | ||||
Not Done Inline Actionss/the/a/ wblock: s/the/a/ | |||||
app on different web server than Apache.</para> | app on different web server than Apache.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="php-variables"> | <sect2 xml:id="php-variables"> | ||||
<title>PHP</title> | <title>PHP</title> | ||||
<table frame="none" xml:id="using-php-variables"> | <table frame="none" xml:id="using-php-variables"> | ||||
<title>Variables for Ports That Use PHP</title> | <title>Variables for Ports That Use PHP</title> | ||||
▲ Show 20 Lines • Show All 78 Lines • ▼ Show 20 Lines | <sect2 xml:id="php-pear"> | ||||
<title>PEAR Modules</title> | <title>PEAR Modules</title> | ||||
<para>Porting PEAR modules is a very simple process.</para> | <para>Porting PEAR modules is a very simple process.</para> | ||||
<para>Use the variables <varname>FILES</varname>, | <para>Use the variables <varname>FILES</varname>, | ||||
<varname>TESTS</varname>, <varname>DATA</varname>, | <varname>TESTS</varname>, <varname>DATA</varname>, | ||||
<varname>SQLS</varname>, <varname>SCRIPTFILES</varname>, | <varname>SQLS</varname>, <varname>SCRIPTFILES</varname>, | ||||
<varname>DOCS</varname> and <varname>EXAMPLES</varname> to | <varname>DOCS</varname> and <varname>EXAMPLES</varname> to | ||||
list the files you want to install. All listed files will | list the files to install. All listed files will | ||||
be automatically installed into the appropriate locations | be automatically installed into the appropriate locations | ||||
and added to <filename>pkg-plist</filename>.</para> | and added to <filename>pkg-plist</filename>.</para> | ||||
<para>Include | <para>Include | ||||
<filename>${PORTSDIR}/devel/pear/bsd.pear.mk</filename> | <filename>${PORTSDIR}/devel/pear/bsd.pear.mk</filename> | ||||
on the last line of the | on the last line of the | ||||
<filename>Makefile</filename>.</para> | <filename>Makefile</filename>.</para> | ||||
Show All 27 Lines | .include <bsd.port.post.mk></programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-python"> | <sect1 xml:id="using-python"> | ||||
<title>Using Python</title> | <title>Using Python</title> | ||||
<para>The Ports Collection supports parallel installation of | <para>The Ports Collection supports parallel installation of | ||||
multiple Python versions. Ports should make sure to use a | multiple Python versions. Ports must use a | ||||
Not Done Inline Actionss/must make sure to/must/ wblock: s/must make sure to/must/ | |||||
correct <command>python</command> interpreter, according to | correct <command>python</command> interpreter, according to | ||||
the user-settable <varname>PYTHON_VERSION</varname> variable. | the user-settable <varname>PYTHON_VERSION</varname>. | ||||
Most prominently, this means replacing the path to | Most prominently, this means replacing the path to | ||||
<command>python</command> executable in scripts with the value | <command>python</command> executable in scripts with the value | ||||
of <varname>PYTHON_CMD</varname> variable.</para> | of <varname>PYTHON_CMD</varname>.</para> | ||||
<para>Ports that install files under | <para>Ports that install files under | ||||
<varname>PYTHON_SITELIBDIR</varname> should use the | <varname>PYTHON_SITELIBDIR</varname> must use the | ||||
<literal>pyXY-</literal> package name prefix, so their package | <literal>pyXY-</literal> package name prefix, so their package | ||||
name embeds the version of Python they are installed | name embeds the version of Python they are installed | ||||
into.</para> | into.</para> | ||||
<programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting> | <programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting> | ||||
<table frame="none" xml:id="using-python-variables"> | <table frame="none" xml:id="using-python-variables"> | ||||
<title>Most Useful Variables for Ports That Use Python</title> | <title>Most Useful Variables for Ports That Use Python</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>USE_PYTHON</varname></entry> | <entry><varname>USE_PYTHON</varname></entry> | ||||
<entry>The port needs Python. Minimal required version | <entry>The port needs Python. Minimal required version | ||||
can be specified with values such as | can be specified with values such as | ||||
<literal>2.6+</literal>. Version ranges can also be | <literal>2.6+</literal>. Version ranges can also be | ||||
specified, by separating two version numbers with a | specified, by separating two version numbers with a | ||||
dash, e.g.: <literal>2.6-2.7</literal></entry> | dash, for example, <literal>2.6-2.7</literal></entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_PYDISTUTILS</varname></entry> | <entry><varname>USE_PYDISTUTILS</varname></entry> | ||||
<entry>Use Python distutils for configuring, compiling | <entry>Use Python distutils for configuring, compiling | ||||
and installing. This is required when the port comes | and installing. This is required when the port comes | ||||
with <filename>setup.py</filename>. This overrides | with <filename>setup.py</filename>. This overrides | ||||
the <buildtarget>do-build</buildtarget> and | the <buildtarget>do-build</buildtarget> and | ||||
Show All 9 Lines | <row> | ||||
distinguish packages for different Python versions. | distinguish packages for different Python versions. | ||||
Example: <literal>py24-</literal></entry> | Example: <literal>py24-</literal></entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PYTHON_SITELIBDIR</varname></entry> | <entry><varname>PYTHON_SITELIBDIR</varname></entry> | ||||
<entry>Location of the site-packages tree, that contains | <entry>Location of the site-packages tree, that contains | ||||
installation path of Python (usually | installation path of Python (usually | ||||
<varname>LOCALBASE</varname>). The | <varname>LOCALBASE</varname>). | ||||
<varname>PYTHON_SITELIBDIR</varname> variable can be | <varname>PYTHON_SITELIBDIR</varname> can be | ||||
very useful when installing Python modules.</entry> | very useful when installing Python modules.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>PYTHONPREFIX_SITELIBDIR</varname></entry> | <entry><varname>PYTHONPREFIX_SITELIBDIR</varname></entry> | ||||
<entry>The PREFIX-clean variant of PYTHON_SITELIBDIR. | <entry>The PREFIX-clean variant of PYTHON_SITELIBDIR. | ||||
Always use <literal>%%PYTHON_SITELIBDIR%%</literal> in | Always use <literal>%%PYTHON_SITELIBDIR%%</literal> in | ||||
<filename>pkg-plist</filename> when possible. The | <filename>pkg-plist</filename> when possible. The | ||||
▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines | .include <bsd.port.post.mk></programlisting> | ||||
-d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})</programlisting> | -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;})</programlisting> | ||||
<para>This recompiles the sources with a path relative to the | <para>This recompiles the sources with a path relative to the | ||||
stage directory, and prepends the value of | stage directory, and prepends the value of | ||||
<varname>PREFIX</varname> to the file name recorded in the | <varname>PREFIX</varname> to the file name recorded in the | ||||
byte-compiled output file by <literal>-d</literal>. | byte-compiled output file by <literal>-d</literal>. | ||||
<literal>-f</literal> is required to force recompilation, and | <literal>-f</literal> is required to force recompilation, and | ||||
the <literal>:S;${PREFIX}/;;</literal> strips prefixes from | the <literal>:S;${PREFIX}/;;</literal> strips prefixes from | ||||
the value of the <varname>PYTHONPREFIX_SITELIBDIR</varname> | the value of <varname>PYTHONPREFIX_SITELIBDIR</varname> | ||||
variable to make it relative to | to make it relative to | ||||
<varname>PREFIX</varname>.</para> | <varname>PREFIX</varname>.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-tcl"> | <sect1 xml:id="using-tcl"> | ||||
<title>Using <application>Tcl/Tk</application></title> | <title>Using <application>Tcl/Tk</application></title> | ||||
<para>The Ports Collection supports parallel installation of | <para>The Ports Collection supports parallel installation of | ||||
multiple <application>Tcl/Tk</application> versions. Ports | multiple <application>Tcl/Tk</application> versions. Ports | ||||
should try to support at least the default | should try to support at least the default | ||||
<application>Tcl/Tk</application> version and higher with | <application>Tcl/Tk</application> version and higher with | ||||
<literal>USES=tcl</literal>. It is possible to specify the | <literal>USES=tcl</literal>. It is possible to specify the | ||||
desired version of <command>tcl</command> by appending | desired version of <command>tcl</command> by appending | ||||
<literal>:<replaceable>xx</replaceable></literal>, e.g.: | <literal>:<replaceable>xx</replaceable></literal>, for example, | ||||
<literal>USES=tcl:85</literal>.</para> | <literal>USES=tcl:85</literal>.</para> | ||||
<table frame="none" xml:id="using-tcl-variables"> | <table frame="none" xml:id="using-tcl-variables"> | ||||
<title>The Most Useful Read-Only Variables for Ports That Use | <title>The Most Useful Read-Only Variables for Ports That Use | ||||
<application>Tcl/Tk</application></title> | <application>Tcl/Tk</application></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<tbody> | <tbody> | ||||
▲ Show 20 Lines • Show All 98 Lines • ▼ Show 20 Lines | <row> | ||||
<entry>Set to the alternative name of | <entry>Set to the alternative name of | ||||
<filename>setup.rb</filename>. Common value is | <filename>setup.rb</filename>. Common value is | ||||
<filename>install.rb</filename>.</entry> | <filename>install.rb</filename>.</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>The following table shows the selected variables available | <para>This table shows the selected variables available | ||||
to port authors via the ports infrastructure. These variables | to port authors via the ports infrastructure. These variables | ||||
should be used to install files into their proper locations. | are used to install files into their proper locations. | ||||
Use them in <filename>pkg-plist</filename> as much as | Use them in <filename>pkg-plist</filename> as much as | ||||
possible. These variables should not be redefined in the | possible. Do not redefine these variables in the port.</para> | ||||
Not Done Inline ActionsDo not redefine these variables in the port. wblock: Do not redefine these variables in the port. | |||||
port.</para> | |||||
<table frame="none" xml:id="using-ruby-variables-ro"> | <table frame="none" xml:id="using-ruby-variables-ro"> | ||||
<title>Selected Read-Only Variables for Ports That Use | <title>Selected Read-Only Variables for Ports That Use | ||||
Ruby</title> | Ruby</title> | ||||
<tgroup cols="3"> | <tgroup cols="3"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
▲ Show 20 Lines • Show All 50 Lines • ▼ Show 20 Lines | </tbody> | ||||
<para>A complete list of available variables can be found in | <para>A complete list of available variables can be found in | ||||
<filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para> | <filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-sdl"> | <sect1 xml:id="using-sdl"> | ||||
<title>Using SDL</title> | <title>Using SDL</title> | ||||
<para>The <varname>USE_SDL</varname> variable is used to | <para><varname>USE_SDL</varname> is used to | ||||
autoconfigure the dependencies for ports which use an SDL | autoconfigure the dependencies for ports which use an SDL | ||||
based library like <package role="port">devel/sdl12</package> | based library like <package role="port">devel/sdl12</package> | ||||
and <package role="port">graphics/sdl_image</package>.</para> | and <package role="port">graphics/sdl_image</package>.</para> | ||||
<para>The following SDL libraries for version 1.2 are recognized | <para>These SDL libraries for version 1.2 are recognized:</para> | ||||
at the moment:</para> | |||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>sdl: <package role="port">devel/sdl12</package></para> | <para>sdl: <package role="port">devel/sdl12</package></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>console: <package | <para>console: <package | ||||
Show All 34 Lines | <para>sound: <package | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>ttf: <package | <para>ttf: <package | ||||
role="port">graphics/sdl_ttf</package></para> | role="port">graphics/sdl_ttf</package></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>The following SDL libraries for version 2.0 are recognized | <para>These SDL libraries for version 2.0 are recognized:</para> | ||||
at the moment:</para> | |||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>sdl: <package role="port">devel/sdl20</package></para> | <para>sdl: <package role="port">devel/sdl20</package></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>gfx: <package | <para>gfx: <package | ||||
Show All 29 Lines | <para>ttf: <package | ||||
<programlisting>USE_SDL= net mixer</programlisting> | <programlisting>USE_SDL= net mixer</programlisting> | ||||
<para>The dependency | <para>The dependency | ||||
<package role="port">devel/sdl12</package>, which is | <package role="port">devel/sdl12</package>, which is | ||||
required by <package role="port">net/sdl_net</package> | required by <package role="port">net/sdl_net</package> | ||||
and <package role="port">audio/sdl_mixer</package>, is | and <package role="port">audio/sdl_mixer</package>, is | ||||
automatically added as well.</para> | automatically added as well.</para> | ||||
<para>If you use <varname>USE_SDL</varname> with entries using | <para>Using <varname>USE_SDL</varname> with entries for | ||||
SDL 1.2, it will automatically:</para> | SDL 1.2, it will automatically:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>Add a dependency on | <para>Add a dependency on | ||||
<application>sdl12-config</application> to | <application>sdl12-config</application> to | ||||
<varname>BUILD_DEPENDS</varname></para> | <varname>BUILD_DEPENDS</varname></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Add the variable <varname>SDL_CONFIG</varname> to | <para>Add the variable <varname>SDL_CONFIG</varname> to | ||||
<varname>CONFIGURE_ENV</varname></para> | <varname>CONFIGURE_ENV</varname></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Add the dependencies of the selected libraries to the | <para>Add the dependencies of the selected libraries to | ||||
<varname>LIB_DEPENDS</varname></para> | <varname>LIB_DEPENDS</varname></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>If you use <varname>USE_SDL</varname> with entries using | <para>Using <varname>USE_SDL</varname> with entries for | ||||
Not Done Inline Actionss/entries using/entries for/ wblock: s/entries using/entries for/ | |||||
SDL 2.0, it will automatically:</para> | SDL 2.0, it will automatically:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>Add a dependency on | <para>Add a dependency on | ||||
<application>sdl2-config</application> to | <application>sdl2-config</application> to | ||||
<varname>BUILD_DEPENDS</varname></para> | <varname>BUILD_DEPENDS</varname></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Add the variable <varname>SDL2_CONFIG</varname> to | <para>Add the variable <varname>SDL2_CONFIG</varname> to | ||||
<varname>CONFIGURE_ENV</varname></para> | <varname>CONFIGURE_ENV</varname></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>Add the dependencies of the selected libraries to the | <para>Add the dependencies of the selected libraries to | ||||
<varname>LIB_DEPENDS</varname></para> | <varname>LIB_DEPENDS</varname></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>To check whether an SDL library is available, you can do | <para>To check whether an SDL library is available, use | ||||
it with the <varname>WANT_SDL</varname> variable:</para> | <varname>WANT_SDL</varname>:</para> | ||||
<programlisting>WANT_SDL= yes | <programlisting>WANT_SDL= yes | ||||
.include <bsd.port.pre.mk> | .include <bsd.port.pre.mk> | ||||
.if ${HAVE_SDL:Mmixer}!="" | .if ${HAVE_SDL:Mmixer}!="" | ||||
USE_SDL+= mixer | USE_SDL+= mixer | ||||
.endif | .endif | ||||
Show All 28 Lines | .include <bsd.port.post.mk></programlisting> | ||||
configure argument, to specify which | configure argument, to specify which | ||||
<command>wx-config</command> script to call. Otherwise they | <command>wx-config</command> script to call. Otherwise they | ||||
have to be patched.</para> | have to be patched.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-version"> | <sect2 xml:id="wx-version"> | ||||
<title>Version Selection</title> | <title>Version Selection</title> | ||||
<para>To make your port use a specific version of | <para>To make the port use a specific version of | ||||
<application>wxWidgets</application> there are two variables | <application>wxWidgets</application> there are two variables | ||||
available for defining (if only one is defined the other | available for defining (if only one is defined the other | ||||
will be set to a default value):</para> | will be set to a default value):</para> | ||||
<table xml:id="wx-ver-sel-table" frame="none"> | <table xml:id="wx-ver-sel-table" frame="none"> | ||||
<title>Variables to Select | <title>Variables to Select | ||||
<application>wxWidgets</application> Versions</title> | <application>wxWidgets</application> Versions</title> | ||||
Show All 10 Lines | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>USE_WX</varname></entry> | <entry><varname>USE_WX</varname></entry> | ||||
<entry>List of versions the port can use</entry> | <entry>List of versions the port can use</entry> | ||||
<entry>All available versions</entry> | <entry>All available versions</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_WX_NOT</varname></entry> | <entry><varname>USE_WX_NOT</varname></entry> | ||||
<entry>List of versions the port can not use</entry> | <entry>List of versions the port cannot use</entry> | ||||
<entry>None</entry> | <entry>None</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>The following is a list of available | <para>The available | ||||
<application>wxWidgets</application> versions and the | <application>wxWidgets</application> versions and the | ||||
corresponding ports in the tree:</para> | corresponding ports in the tree are:</para> | ||||
<table frame="none" xml:id="wx-widgets-versions-table"> | <table frame="none" xml:id="wx-widgets-versions-table"> | ||||
<title>Available <application>wxWidgets</application> | <title>Available <application>wxWidgets</application> | ||||
Versions</title> | Versions</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
Show All 29 Lines | <para>The versions starting from <literal>2.5</literal> also | ||||
come in Unicode version and are installed by a slave port | come in Unicode version and are installed by a slave port | ||||
named like the normal one plus a | named like the normal one plus a | ||||
<literal>-unicode</literal> suffix, but this can be | <literal>-unicode</literal> suffix, but this can be | ||||
handled with variables (see | handled with variables (see | ||||
<xref linkend="wx-unicode"/>).</para> | <xref linkend="wx-unicode"/>).</para> | ||||
</note> | </note> | ||||
<para>The variables in <xref linkend="wx-ver-sel-table"/> can | <para>The variables in <xref linkend="wx-ver-sel-table"/> can | ||||
be set to one or more of the following combinations | be set to one or more of these combinations | ||||
separated by spaces:</para> | separated by spaces:</para> | ||||
<table frame="none" xml:id="wx-widgets-versions-specification"> | <table frame="none" xml:id="wx-widgets-versions-specification"> | ||||
<title><application>wxWidgets</application> Version | <title><application>wxWidgets</application> Version | ||||
Specifications</title> | Specifications</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
▲ Show 20 Lines • Show All 59 Lines • ▼ Show 20 Lines | </tgroup> | ||||
</table> | </table> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-components"> | <sect2 xml:id="wx-components"> | ||||
<title>Component Selection</title> | <title>Component Selection</title> | ||||
<para>There are other applications that, while not being | <para>There are other applications that, while not being | ||||
<application>wxWidgets</application> libraries, are related | <application>wxWidgets</application> libraries, are related | ||||
to them. These applications can be specified in the | to them. These applications can be specified in | ||||
<varname>WX_COMPS</varname> variable. The following | <varname>WX_COMPS</varname>. These | ||||
components are available:</para> | components are available:</para> | ||||
<table frame="none" xml:id="wx-widgets-components-table"> | <table frame="none" xml:id="wx-widgets-components-table"> | ||||
<title>Available <application>wxWidgets</application> | <title>Available <application>wxWidgets</application> | ||||
Components</title> | Components</title> | ||||
<tgroup cols="3"> | <tgroup cols="3"> | ||||
<thead> | <thead> | ||||
Show All 37 Lines | (<application>Python</application> bindings)</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>The dependency type can be selected for each component | <para>The dependency type can be selected for each component | ||||
by adding a suffix separated by a semicolon. If not present | by adding a suffix separated by a semicolon. If not present | ||||
then a default type will be used (see | then a default type will be used (see | ||||
<xref linkend="wx-def-dep-types"/>). The following types | <xref linkend="wx-def-dep-types"/>). These types | ||||
are available:</para> | are available:</para> | ||||
<table frame="none" xml:id="wx-widgets-dependency-table"> | <table frame="none" xml:id="wx-widgets-dependency-table"> | ||||
<title>Available <application>wxWidgets</application> | <title>Available <application>wxWidgets</application> | ||||
Dependency Types</title> | Dependency Types</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
Show All 21 Lines | to <varname>RUN_DEPENDS</varname></entry> | ||||
<entry>Component is required for building and running, | <entry>Component is required for building and running, | ||||
equivalent to <varname>LIB_DEPENDS</varname></entry> | equivalent to <varname>LIB_DEPENDS</varname></entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<para>The default values for the components are detailed in | <para>The default values for the components are detailed in | ||||
the following table:</para> | this table:</para> | ||||
<table xml:id="wx-def-dep-types" frame="none"> | <table xml:id="wx-def-dep-types" frame="none"> | ||||
<title>Default <application>wxWidgets</application> | <title>Default <application>wxWidgets</application> | ||||
Dependency Types</title> | Dependency Types</title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
Show All 30 Lines | <tgroup cols="2"> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<example xml:id="wx-components-example"> | <example xml:id="wx-components-example"> | ||||
<title>Selecting <application>wxWidgets</application> | <title>Selecting <application>wxWidgets</application> | ||||
Components</title> | Components</title> | ||||
<para>The following fragment corresponds to a port which | <para>This fragment corresponds to a port which | ||||
uses <application>wxWidgets</application> version | uses <application>wxWidgets</application> version | ||||
<literal>2.4</literal> and its contributed | <literal>2.4</literal> and its contributed | ||||
libraries.</para> | libraries.</para> | ||||
<programlisting>USE_WX= 2.4 | <programlisting>USE_WX= 2.4 | ||||
WX_COMPS= wx contrib</programlisting> | WX_COMPS= wx contrib</programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-unicode"> | <sect2 xml:id="wx-unicode"> | ||||
<title>Unicode</title> | <title>Unicode</title> | ||||
<para>The <application>wxWidgets</application> library | <para>The <application>wxWidgets</application> library | ||||
supports Unicode since version <literal>2.5</literal>. In | supports Unicode since version <literal>2.5</literal>. In | ||||
the ports tree both versions are available and can be | the ports tree both versions are available and can be | ||||
selected with the following variables:</para> | selected with these variables:</para> | ||||
<table xml:id="wx-unicode-var-table" frame="none"> | <table xml:id="wx-unicode-var-table" frame="none"> | ||||
<title>Variables to Select Unicode in | <title>Variables to Select Unicode in | ||||
<application>wxWidgets</application> | <application>wxWidgets</application> | ||||
Versions</title> | Versions</title> | ||||
<tgroup cols="3"> | <tgroup cols="3"> | ||||
<thead> | <thead> | ||||
Show All 33 Lines | defined)</entry> | ||||
<entry>the user</entry> | <entry>the user</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
<warning> | <warning> | ||||
<para>Do not use <varname>WX_UNICODE</varname> for ports | <para>Do not use <varname>WX_UNICODE</varname> for ports | ||||
that can use both Unicode and normal versions. If you | that can use both Unicode and normal versions. If | ||||
want the port to use Unicode by default define | the port needs to use Unicode by default, define | ||||
Not Done Inline Actionss/default define/default, define/ wblock: s/default define/default, define/ | |||||
<varname>WANT_UNICODE</varname> instead.</para> | <varname>WANT_UNICODE</varname> instead.</para> | ||||
</warning> | </warning> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-version-detection"> | <sect2 xml:id="wx-version-detection"> | ||||
<title>Detecting Installed Versions</title> | <title>Detecting Installed Versions</title> | ||||
<para>To detect an installed version you have to define | <para>To detect an installed version, define | ||||
<varname>WANT_WX</varname>. If you do not set it to a | <varname>WANT_WX</varname>. If it is not set to a | ||||
Not Done Inline Actionss/version define/version, define/ wblock: s/version define/version, define/ | |||||
specific version then the components will have a version | specific version then the components will have a version | ||||
suffix. The <varname>HAVE_WX</varname> variable will be | suffix. <varname>HAVE_WX</varname> will be | ||||
filled after detection.</para> | filled after detection.</para> | ||||
<example xml:id="wx-ver-det-example"> | <example xml:id="wx-ver-det-example"> | ||||
<title>Detecting Installed | <title>Detecting Installed | ||||
<application>wxWidgets</application> Versions and | <application>wxWidgets</application> Versions and | ||||
Components</title> | Components</title> | ||||
<para>The following fragment can be used in a port that uses | <para>This fragment can be used in a port that uses | ||||
<application>wxWidgets</application> if it is installed, | <application>wxWidgets</application> if it is installed, | ||||
or an option is selected.</para> | or an option is selected.</para> | ||||
<programlisting>WANT_WX= yes | <programlisting>WANT_WX= yes | ||||
.include <bsd.port.pre.mk> | .include <bsd.port.pre.mk> | ||||
.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4) | .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4) | ||||
USE_WX= 2.4 | USE_WX= 2.4 | ||||
CONFIGURE_ARGS+= --enable-wx | CONFIGURE_ARGS+= --enable-wx | ||||
.endif</programlisting> | .endif</programlisting> | ||||
<para>The following fragment can be used in a port that | <para>This fragment can be used in a port that | ||||
enables <application>wxPython</application> support if it | enables <application>wxPython</application> support if it | ||||
is installed or if an option is selected, in addition to | is installed or if an option is selected, in addition to | ||||
<application>wxWidgets</application>, both version | <application>wxWidgets</application>, both version | ||||
<literal>2.6</literal>.</para> | <literal>2.6</literal>.</para> | ||||
<programlisting>USE_WX= 2.6 | <programlisting>USE_WX= 2.6 | ||||
WX_COMPS= wx | WX_COMPS= wx | ||||
WANT_WX= 2.6 | WANT_WX= 2.6 | ||||
.include <bsd.port.pre.mk> | .include <bsd.port.pre.mk> | ||||
.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) | .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) | ||||
WX_COMPS+= python | WX_COMPS+= python | ||||
CONFIGURE_ARGS+= --enable-wxpython | CONFIGURE_ARGS+= --enable-wxpython | ||||
.endif</programlisting> | .endif</programlisting> | ||||
</example> | </example> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-defined-variables"> | <sect2 xml:id="wx-defined-variables"> | ||||
<title>Defined Variables</title> | <title>Defined Variables</title> | ||||
<para>The following variables are available in the port (after | <para>These variables are available in the port (after | ||||
defining one from | defining one from | ||||
<xref linkend="wx-ver-sel-table"/>).</para> | <xref linkend="wx-ver-sel-table"/>).</para> | ||||
<table frame="none" xml:id="wx-widgets-variables"> | <table frame="none" xml:id="wx-widgets-variables"> | ||||
<title>Variables Defined for Ports That Use | <title>Variables Defined for Ports That Use | ||||
<application>wxWidgets</application></title> | <application>wxWidgets</application></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
Show All 19 Lines | <tgroup cols="2"> | ||||
<application>wxWidgets</application> | <application>wxWidgets</application> | ||||
<command>wxrc</command> program (with different | <command>wxrc</command> program (with different | ||||
name)</entry> | name)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>WX_VERSION</varname></entry> | <entry><varname>WX_VERSION</varname></entry> | ||||
<entry>The <application>wxWidgets</application> | <entry>The <application>wxWidgets</application> | ||||
version that is going to be used (e.g., | version that is going to be used (for example, | ||||
<literal>2.6</literal>)</entry> | <literal>2.6</literal>)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>WX_UNICODE</varname></entry> | <entry><varname>WX_UNICODE</varname></entry> | ||||
<entry>If not defined but Unicode is going to be used | <entry>If not defined but Unicode is going to be used | ||||
then it will be defined</entry> | then it will be defined</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </table> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-premk"> | <sect2 xml:id="wx-premk"> | ||||
<title>Processing in | <title>Processing in | ||||
<filename>bsd.port.pre.mk</filename></title> | <filename>bsd.port.pre.mk</filename></title> | ||||
<para>If you need to use the variables for running commands | <para>Define <varname>WX_PREMK</varname> to be able to use the | ||||
right after including <filename>bsd.port.pre.mk</filename> | variables right after including | ||||
you need to define <varname>WX_PREMK</varname>.</para> | <filename>bsd.port.pre.mk</filename>.</para> | ||||
<important> | <important> | ||||
<para>If you define <varname>WX_PREMK</varname>, then the | <para>When defining <varname>WX_PREMK</varname>, then the | ||||
version, dependencies, components and defined variables | version, dependencies, components and defined variables | ||||
will not change if you modify the | will not change if modifying the | ||||
<application>wxWidgets</application> port variables | <application>wxWidgets</application> port variables | ||||
<emphasis>after</emphasis> including | <emphasis>after</emphasis> including | ||||
<filename>bsd.port.pre.mk</filename>.</para> | <filename>bsd.port.pre.mk</filename>.</para> | ||||
</important> | </important> | ||||
<example xml:id="wx-premk-example"> | <example xml:id="wx-premk-example"> | ||||
<title>Using <application>wxWidgets</application> Variables | <title>Using <application>wxWidgets</application> Variables | ||||
in Commands</title> | in Commands</title> | ||||
<para>The following fragment illustrates the use of | <para>This fragment illustrates the use of | ||||
<varname>WX_PREMK</varname> by running the | <varname>WX_PREMK</varname> by running the | ||||
<command>wx-config</command> script to obtain the full | <command>wx-config</command> script to obtain the full | ||||
version string, assign it to a variable and pass it to the | version string, assign it to a variable and pass it to the | ||||
program.</para> | program.</para> | ||||
<programlisting>USE_WX= 2.4 | <programlisting>USE_WX= 2.4 | ||||
WX_PREMK= yes | WX_PREMK= yes | ||||
Show All 12 Lines | <para>The <application>wxWidgets</application> variables can | ||||
without the need of <varname>WX_PREMK</varname>.</para> | without the need of <varname>WX_PREMK</varname>.</para> | ||||
</note> | </note> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="wx-additional-config-args"> | <sect2 xml:id="wx-additional-config-args"> | ||||
<title>Additional <command>configure</command> | <title>Additional <command>configure</command> | ||||
Arguments</title> | Arguments</title> | ||||
<para>Some GNU <command>configure</command> scripts can not | <para>Some GNU <command>configure</command> scripts cannot | ||||
find <application>wxWidgets</application> with just the | find <application>wxWidgets</application> with just the | ||||
<literal>WX_CONFIG</literal> environment variable set, | <literal>WX_CONFIG</literal> environment variable set, | ||||
requiring additional arguments. The | requiring additional arguments. | ||||
<varname>WX_CONF_ARGS</varname> variable can be used for | <varname>WX_CONF_ARGS</varname> can be used for | ||||
provide them.</para> | provide them.</para> | ||||
<table frame="none" xml:id="wx-conf-args-values"> | <table frame="none" xml:id="wx-conf-args-values"> | ||||
<title>Legal Values for | <title>Legal Values for | ||||
<varname>WX_CONF_ARGS</varname></title> | <varname>WX_CONF_ARGS</varname></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
▲ Show 20 Lines • Show All 42 Lines • ▼ Show 20 Lines | .endif</programlisting> | ||||
But it can be solved by adding some additional flags to the | But it can be solved by adding some additional flags to the | ||||
compiler and linker.</para> | compiler and linker.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="lua-version"> | <sect2 xml:id="lua-version"> | ||||
<title>Version Selection</title> | <title>Version Selection</title> | ||||
<para>A port using <application>Lua</application> only needs to | <para>A port using <application>Lua</application> only needs to | ||||
have the following line:</para> | have this line:</para> | ||||
<programlisting>USES= lua</programlisting> | <programlisting>USES= lua</programlisting> | ||||
<para>If a specific version of Lua is needed, instructions on | <para>If a specific version of Lua is needed, instructions on | ||||
how to select it are given in the <link | how to select it are given in the <link | ||||
linkend="uses-lua"><literal>USES=lua</literal></link> part | linkend="uses-lua"><literal>USES=lua</literal></link> part | ||||
of <xref linkend="uses-values"/>.</para> | of <xref linkend="uses-values"/>.</para> | ||||
</sect2> | </sect2> | ||||
<sect2 xml:id="lua-defined-variables"> | <sect2 xml:id="lua-defined-variables"> | ||||
<title>Defined Variables</title> | <title>Defined Variables</title> | ||||
<para>The following variables are available in the port.</para> | <para>These variables are available in the port.</para> | ||||
<table frame="none" xml:id="using-lua-variables-ports"> | <table frame="none" xml:id="using-lua-variables-ports"> | ||||
<title>Variables Defined for Ports That Use | <title>Variables Defined for Ports That Use | ||||
<application>Lua</application></title> | <application>Lua</application></title> | ||||
<tgroup cols="2"> | <tgroup cols="2"> | ||||
<thead> | <thead> | ||||
<row> | <row> | ||||
<entry>Name</entry> | <entry>Name</entry> | ||||
<entry>Description</entry> | <entry>Description</entry> | ||||
</row> | </row> | ||||
</thead> | </thead> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>LUA_VER</varname></entry> | <entry><varname>LUA_VER</varname></entry> | ||||
<entry>The <application>Lua</application> version that | <entry>The <application>Lua</application> version that | ||||
is going to be used (e.g., | is going to be used (for example, | ||||
<literal>5.1</literal>)</entry> | <literal>5.1</literal>)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_VER_STR</varname></entry> | <entry><varname>LUA_VER_STR</varname></entry> | ||||
<entry>The <application>Lua</application> version | <entry>The <application>Lua</application> version | ||||
without the dots (e.g., | without the dots (for example, | ||||
<literal>51</literal>)</entry> | <literal>51</literal>)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_PREFIX</varname></entry> | <entry><varname>LUA_PREFIX</varname></entry> | ||||
<entry>The prefix where <application>Lua</application> | <entry>The prefix where <application>Lua</application> | ||||
(and components) is installed</entry> | (and components) is installed</entry> | ||||
</row> | </row> | ||||
▲ Show 20 Lines • Show All 199 Lines • ▼ Show 20 Lines | |||||
.include <bsd.port.post.mk></programlisting> | .include <bsd.port.post.mk></programlisting> | ||||
</example> | </example> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-xfce"> | <sect1 xml:id="using-xfce"> | ||||
<title>Using Xfce</title> | <title>Using Xfce</title> | ||||
<para>The <varname>USE_XFCE</varname> variable is used to | <para><varname>USE_XFCE</varname> is used to | ||||
autoconfigure the dependencies for ports which use an Xfce | autoconfigure the dependencies for ports which use an Xfce | ||||
based library or application like | based library or application like | ||||
<package role="port">x11-toolkits/libxfce4gui</package> | <package role="port">x11-toolkits/libxfce4gui</package> | ||||
and <package role="port">x11-wm/xfce4-panel</package>.</para> | and <package role="port">x11-wm/xfce4-panel</package>.</para> | ||||
<para>The following Xfce libraries and applications are | <para>These Xfce libraries and applications are | ||||
recognized at the moment:</para> | recognized:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>libexo: <package | <para>libexo: <package | ||||
role="port">x11/libexo</package></para> | role="port">x11/libexo</package></para> | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
Show All 32 Lines | <para>wm: <package | ||||
</listitem> | </listitem> | ||||
<listitem> | <listitem> | ||||
<para>xfdev: <package | <para>xfdev: <package | ||||
role="port">dev/xfce4-dev-tools</package></para> | role="port">dev/xfce4-dev-tools</package></para> | ||||
</listitem> | </listitem> | ||||
</itemizedlist> | </itemizedlist> | ||||
<para>The following additional parameters are recognized:</para> | <para>These additional parameters are recognized:</para> | ||||
<itemizedlist> | <itemizedlist> | ||||
<listitem> | <listitem> | ||||
<para>configenv: Use this if your port requires a special | <para>configenv: Use this if the port requires a special | ||||
modified <varname>CONFIGURE_ENV</varname> to find its | modified <varname>CONFIGURE_ENV</varname> to find its | ||||
required libraries.</para> | required libraries.</para> | ||||
<programlisting>-I${LOCALBASE}/include -L${LOCALBASE}/lib</programlisting> | <programlisting>-I${LOCALBASE}/include -L${LOCALBASE}/lib</programlisting> | ||||
<para>gets added to CPPFLAGS to | <para>gets added to CPPFLAGS to | ||||
<varname>CONFIGURE_ENV</varname>.</para> | <varname>CONFIGURE_ENV</varname>.</para> | ||||
</listitem> | </listitem> | ||||
Show All 18 Lines | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>USE_GECKO</varname></entry> | <entry><varname>USE_GECKO</varname></entry> | ||||
<entry>Gecko backend the port can handle. Possible | <entry>Gecko backend the port can handle. Possible | ||||
values: <literal>libxul</literal> | values: <literal>libxul</literal> | ||||
(<filename>libxul.so</filename>), | (<filename>libxul.so</filename>), | ||||
<literal>seamonkey</literal> | <literal>seamonkey</literal> | ||||
(<filename>libgtkembedmoz.so</filename>, deprecated, | (<filename>libgtkembedmoz.so</filename>, deprecated, | ||||
should not be used any more).</entry> | must not be used any more).</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_FIREFOX</varname></entry> | <entry><varname>USE_FIREFOX</varname></entry> | ||||
<entry>The port requires Firefox as a runtime | <entry>The port requires Firefox as a runtime | ||||
dependency. Possible values: <literal>yes</literal> | dependency. Possible values: <literal>yes</literal> | ||||
(get default version), <literal>40</literal>, | (get default version), <literal>40</literal>, | ||||
<literal>36</literal>, <literal>35</literal>. Default | <literal>36</literal>, <literal>35</literal>. Default | ||||
Show All 9 Lines | <row> | ||||
value.</entry> | value.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_SEAMONKEY</varname></entry> | <entry><varname>USE_SEAMONKEY</varname></entry> | ||||
<entry>The port requires SeaMonkey as a runtime | <entry>The port requires SeaMonkey as a runtime | ||||
dependency. Possible values: <literal>yes</literal> | dependency. Possible values: <literal>yes</literal> | ||||
(get default version), <literal>20</literal>, | (get default version), <literal>20</literal>, | ||||
<literal>11</literal> (deprecated, should not be used | <literal>11</literal> (deprecated, must not be used | ||||
any more). Default dependency is on version | any more). Default dependency is on version | ||||
<literal>20</literal>.</entry> | <literal>20</literal>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_SEAMONKEY_BUILD</varname></entry> | <entry><varname>USE_SEAMONKEY_BUILD</varname></entry> | ||||
<entry>The port requires SeaMonkey as a buildtime | <entry>The port requires SeaMonkey as a buildtime | ||||
dependency. Possible values: see USE_SEAMONKEY. This | dependency. Possible values: see USE_SEAMONKEY. This | ||||
automatically sets USE_SEAMONKEY and assigns the same | automatically sets USE_SEAMONKEY and assigns the same | ||||
value.</entry> | value.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_THUNDERBIRD</varname></entry> | <entry><varname>USE_THUNDERBIRD</varname></entry> | ||||
<entry>The port requires Thunderbird as a runtime | <entry>The port requires Thunderbird as a runtime | ||||
dependency. Possible values: <literal>yes</literal> | dependency. Possible values: <literal>yes</literal> | ||||
(get default version), <literal>31</literal>, | (get default version), <literal>31</literal>, | ||||
<literal>30</literal> (deprecated, should not be used | <literal>30</literal> (deprecated, must not be used | ||||
any more). Default dependency is on version | any more). Default dependency is on version | ||||
<literal>31</literal>.</entry> | <literal>31</literal>.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_THUNDERBIRD_BUILD</varname></entry> | <entry><varname>USE_THUNDERBIRD_BUILD</varname></entry> | ||||
<entry>The port requires Thunderbird as a buildtime | <entry>The port requires Thunderbird as a buildtime | ||||
dependency. Possible values: see USE_THUNDERBIRD. | dependency. Possible values: see USE_THUNDERBIRD. | ||||
Show All 24 Lines | .include <bsd.port.post.mk></programlisting> | ||||
<tbody> | <tbody> | ||||
<row> | <row> | ||||
<entry><varname>USE_BDB</varname></entry> | <entry><varname>USE_BDB</varname></entry> | ||||
<entry>If variable is set to <literal>yes</literal>, | <entry>If variable is set to <literal>yes</literal>, | ||||
add dependency on | add dependency on | ||||
<package role="port">databases/db41</package> | <package role="port">databases/db41</package> | ||||
port. The variable may also be set to values: 40, 41, | port. The variable may also be set to values: 40, 41, | ||||
42, 43, 44, 46, 47, 48, or 51. You can declare a | 42, 43, 44, 46, 47, 48, or 51. It is possible to declare a | ||||
range of acceptable values, | range of acceptable values, | ||||
<varname>USE_BDB</varname>=42+ will find the highest | <varname>USE_BDB</varname>=42+ will find the highest | ||||
installed version, and fall back to 42 if nothing else | installed version, and fall back to 42 if nothing else | ||||
is installed.</entry> | is installed.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_MYSQL</varname></entry> | <entry><varname>USE_MYSQL</varname></entry> | ||||
<entry>If the variable is set to <literal>yes</literal>, | <entry>If the variable is set to <literal>yes</literal>, | ||||
add a dependency on the <package | add a dependency on the <package | ||||
role="port">databases/mysql55-client</package> port. | role="port">databases/mysql55-client</package> port. | ||||
An associated variable, | An associated variable, | ||||
<varname>WANT_MYSQL_VER</varname>, may be set to | <varname>WANT_MYSQL_VER</varname>, may be set to | ||||
values such as 323, 40, 41, 50, 51, 52, 55, or | values such as 323, 40, 41, 50, 51, 52, 55, or | ||||
60.</entry> | 60.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_PGSQL</varname></entry> | <entry><varname>USE_PGSQL</varname></entry> | ||||
<entry>If set to <literal>yes</literal>, add dependency | <entry>If set to <literal>yes</literal>, add dependency | ||||
on <package | on <package | ||||
role="port">databases/postgresql90-client</package> | role="port">databases/postgresql90-client</package> | ||||
port. An associated variable, | port. An associated variable, | ||||
<varname>WANT_PGSQL_VER</varname>, may be set to | <varname>WANT_PGSQL_VER</varname>, may be set to | ||||
values such as 83, 84, 90, 91 or 92. You can declare | values such as 83, 84, 90, 91 or 92. It is possible to declare | ||||
a minimum or maximum value; | a minimum or maximum value; | ||||
<varname>WANT_PGSQL_VER</varname>= <literal> | <varname>WANT_PGSQL_VER</varname>= <literal> | ||||
90+</literal> will cause the port to depend on a | 90+</literal> will cause the port to depend on a | ||||
minimum version of 9.0.</entry> | minimum version of 9.0.</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>USE_SQLITE</varname></entry> | <entry><varname>USE_SQLITE</varname></entry> | ||||
▲ Show 20 Lines • Show All 53 Lines • ▼ Show 20 Lines | section</link>.</para> | ||||
<programlisting>#!/bin/sh | <programlisting>#!/bin/sh | ||||
# $FreeBSD$ | # $FreeBSD$ | ||||
# | # | ||||
# PROVIDE: doormand | # PROVIDE: doormand | ||||
# REQUIRE: LOGIN | # REQUIRE: LOGIN | ||||
# KEYWORD: shutdown | # KEYWORD: shutdown | ||||
# | # | ||||
# Add the following lines to /etc/rc.conf.local or /etc/rc.conf | # Add these lines to /etc/rc.conf.local or /etc/rc.conf | ||||
# to enable this service: | # to enable this service: | ||||
# | # | ||||
# doormand_enable (bool): Set to NO by default. | # doormand_enable (bool): Set to NO by default. | ||||
# Set it to YES to enable doormand. | # Set it to YES to enable doormand. | ||||
# doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf | # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf | ||||
# by default. | # by default. | ||||
. /etc/rc.subr | . /etc/rc.subr | ||||
Show All 9 Lines | |||||
command=%%PREFIX%%/sbin/${name} | command=%%PREFIX%%/sbin/${name} | ||||
pidfile=/var/run/${name}.pid | pidfile=/var/run/${name}.pid | ||||
command_args="-p $pidfile -f $doormand_config" | command_args="-p $pidfile -f $doormand_config" | ||||
run_rc_command "$1"</programlisting> | run_rc_command "$1"</programlisting> | ||||
<para>Unless there is a good reason to start the service | <para>Unless there is a good reason to start the service | ||||
earlier all ports scripts should use</para> | earlier, all ports scripts should use</para> | ||||
Not Done Inline ActionsThis is a recommendation: earlier, all ports scripts should use</para> wblock: This is a recommendation:
earlier, all ports scripts should use</para> | |||||
<programlisting>REQUIRE: LOGIN</programlisting> | <programlisting>REQUIRE: LOGIN</programlisting> | ||||
<para>If the service runs as a particular user (other than root) | <para>If the service runs as a particular user (other than root) | ||||
this is mandatory.</para> | this is mandatory.</para> | ||||
<programlisting>KEYWORD: shutdown</programlisting> | <programlisting>KEYWORD: shutdown</programlisting> | ||||
<para>is included in the script above because the mythical port | <para>is included in the script above because the mythical port | ||||
we are using as an example starts a service, and should be | we are using as an example starts a service, and it must be | ||||
shut down cleanly when the system shuts down. If the script | shut down cleanly when the system shuts down. If the script | ||||
is not starting a persistent service this is not | is not starting a persistent service this is not | ||||
necessary.</para> | necessary.</para> | ||||
<para>For optional configuration elements the "=" | <para>For optional configuration elements the "=" | ||||
style of default variable assignment is preferable to the | style of default variable assignment is preferable to the | ||||
":=" style here, since the former sets a default | ":=" style here, since the former sets a default | ||||
value only if the variable is unset, and the latter sets one | value only if the variable is unset, and the latter sets one | ||||
if the variable is unset <emphasis>or</emphasis> null. A user | if the variable is unset <emphasis>or</emphasis> null. A user | ||||
might very well include something like</para> | might very well include something like</para> | ||||
<programlisting>doormand_flags=""</programlisting> | <programlisting>doormand_flags=""</programlisting> | ||||
<para>in their <filename>rc.conf.local</filename> file, and a | <para>in their <filename>rc.conf.local</filename>, and a | ||||
variable substitution using ":=" would | variable substitution using ":=" would | ||||
inappropriately override the user's intention. The | inappropriately override the user's intention. The | ||||
<literal>_enable</literal> variable is not optional, | <literal>_enable</literal> variable is not optional, | ||||
and should use the ":" for the default.</para> | and must use the ":" for the default.</para> | ||||
<sect2 xml:id="rc-scripts-checklist"> | <sect2 xml:id="rc-scripts-checklist"> | ||||
<title>Pre-Commit Checklist</title> | <title>Pre-Commit Checklist</title> | ||||
<para>Before contributing a port with an | <para>Before contributing a port with an | ||||
<filename>rc.d</filename> script, and more importantly, | <filename>rc.d</filename> script, and more importantly, | ||||
before committing one, please consult the following | before committing one, please consult this | ||||
checklist to be sure that it is ready.</para> | checklist to be sure that it is ready.</para> | ||||
<para>The <package role="port">devel/rclint</package> | <para>The <package role="port">devel/rclint</package> | ||||
port can check for most of these, but it is not a | port can check for most of these, but it is not a | ||||
substitute for proper review.</para> | substitute for proper review.</para> | ||||
<procedure> | <procedure> | ||||
<step> | <step> | ||||
<para>If this is a new file, does it have | <para>If this is a new file, does it have a | ||||
Not Done Inline Actionss/have/have a/ wblock: s/have/have a/ | |||||
Not Done Inline Actionss/If so that/If so, that/ wblock: s/If so that/If so, that/ | |||||
<filename>.sh</filename> in the file name? If so that | <filename>.sh</filename> extension? If so, that | ||||
should be changed to just <filename>file.in</filename> | must be changed to just <filename><replaceable>file</replaceable>.in</filename> | ||||
since <filename>rc.d</filename> files may not end | since <filename>rc.d</filename> files may not end | ||||
with that extension.</para> | with that extension.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Does the file have a | <para>Does the file have a | ||||
<literal>$FreeBSD$</literal> tag?</para> | <literal>$FreeBSD$</literal> tag?</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Do the name of the file (minus | <para>Do the name of the file (minus | ||||
<filename>.in</filename>), the | <filename>.in</filename>), the | ||||
<literal>PROVIDE</literal> line, and | <literal>PROVIDE</literal> line, and | ||||
<literal>$</literal><replaceable>name</replaceable> | <literal>$</literal><replaceable>name</replaceable> | ||||
all match? The file name matching | all match? The file name matching | ||||
<literal>PROVIDE</literal> makes debugging easier, | <literal>PROVIDE</literal> makes debugging easier, | ||||
especially for &man.rcorder.8; issues. Matching the | especially for &man.rcorder.8; issues. Matching the | ||||
file name and | file name and | ||||
<literal>$</literal><replaceable>name</replaceable> | <literal>$</literal><replaceable>name</replaceable> | ||||
makes it easier to figure out which variables are | makes it easier to figure out which variables are | ||||
relevant in <filename>rc.conf[.local]</filename>. The | relevant in <filename>rc.conf[.local]</filename>. It is | ||||
latter is also what you might call “policy” | also a policy | ||||
for all new scripts, including those in the base | for all new scripts, including those in the base | ||||
system.</para> | system.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Is the <literal>REQUIRE</literal> line set to | <para>Is the <literal>REQUIRE</literal> line set to | ||||
<literal>LOGIN</literal>? This is mandatory for scripts | <literal>LOGIN</literal>? This is mandatory for scripts | ||||
that run as a non-root user. If it runs as root, is | that run as a non-root user. If it runs as root, is | ||||
there a good reason for it to run prior to | there a good reason for it to run prior to | ||||
<literal>LOGIN</literal>? If not, it should run there | <literal>LOGIN</literal>? If not, it must run after | ||||
so that we can loosely group local scripts to a point in | so that local scrips can be loosely grouped to a point in | ||||
&man.rcorder.8; after most everything in the base is | &man.rcorder.8; after most everything in the base is | ||||
already running.</para> | already running.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Does the script start a persistent service? If so, | <para>Does the script start a persistent service? If so, | ||||
it should have <literal>KEYWORD: | it must have <literal>KEYWORD: | ||||
shutdown</literal>.</para> | shutdown</literal>.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Make sure there is no | <para>Make sure there is no | ||||
<literal>KEYWORD: &os;</literal> present. This has | <literal>KEYWORD: &os;</literal> present. This has | ||||
not been necessary or desirable for years. It is also | not been necessary or desirable for years. It is also | ||||
an indication that the new script was copy/pasted from | an indication that the new script was copy/pasted from | ||||
an old script, so extra caution should be given to the | an old script, so extra caution must be given to the | ||||
review.</para> | review.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>If the script uses an interpreted language like | <para>If the script uses an interpreted language like | ||||
<command>perl</command>, <command>python</command>, or | <command>perl</command>, <command>python</command>, or | ||||
<command>ruby</command>, make certain that | <command>ruby</command>, make certain that | ||||
<varname>command_interpreter</varname> is set | <varname>command_interpreter</varname> is set | ||||
appropriately, e.g., for <application>Perl</application>, | appropriately, for example, for <application>Perl</application>, | ||||
by adding <literal>PERL=${PERL}</literal> to | by adding <literal>PERL=${PERL}</literal> to | ||||
<varname>SUB_LIST</varname> and using | <varname>SUB_LIST</varname> and using | ||||
<literal>%%PERL%%</literal>. Otherwise,</para> | <literal>%%PERL%%</literal>. Otherwise,</para> | ||||
<screen>&prompt.root; <userinput>service <replaceable>name</replaceable> stop</userinput></screen> | <screen>&prompt.root; <userinput>service <replaceable>name</replaceable> stop</userinput></screen> | ||||
<para>will probably not work properly. See | <para>will probably not work properly. See | ||||
&man.service.8; for more information.</para> | &man.service.8; for more information.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Have all occurrences of | <para>Have all occurrences of | ||||
<filename>/usr/local</filename> been replaced with | <filename>/usr/local</filename> been replaced with | ||||
<literal>%%PREFIX%%</literal>?</para> | <literal>%%PREFIX%%</literal>?</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Do the default variable assignments come after | <para>Do the default variable assignments come after | ||||
<function>load_rc_config</function>?</para> | <function>load_rc_config</function>?</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Are there default assignments to empty strings? | <para>Are there default assignments to empty strings? | ||||
They should be removed, but double-check that the option | They should be removed, but double-check that the option | ||||
Not Done Inline Actions"Should" is a recommendation here, and correct. wblock: "Should" is a recommendation here, and correct. | |||||
is documented in the comments at the top of the | is documented in the comments at the top of the | ||||
file.</para> | file.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Are things that are set in variables actually used | <para>Are things that are set in variables actually used | ||||
in the script?</para> | in the script?</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Are options listed in the default | <para>Are options listed in the default | ||||
<replaceable>name</replaceable><varname>_flags</varname> | <replaceable>name</replaceable><varname>_flags</varname> | ||||
things that are actually mandatory? If so, they should | things that are actually mandatory? If so, they must | ||||
be in <varname>command_args</varname>. The | be in <varname>command_args</varname>. The | ||||
<option>-d</option> option is a red flag (pardon the | <option>-d</option> option is a red flag (pardon the | ||||
pun) here, since it is usually the option to | pun) here, since it is usually the option to | ||||
“daemonize” the process, and therefore is | “daemonize” the process, and therefore is | ||||
actually mandatory.</para> | actually mandatory.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>The | <para><varname><replaceable>name</replaceable>_flags</varname> | ||||
<replaceable>name</replaceable><varname>_flags</varname> | must never be included in | ||||
variable should never be included in | |||||
<varname>command_args</varname> (and vice versa, | <varname>command_args</varname> (and vice versa, | ||||
although that error is less common).</para> | although that error is less common).</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Does the script execute any code unconditionally? | <para>Does the script execute any code unconditionally? | ||||
This is frowned on. Usually these things can/should be | This is frowned on. Usually these things must be | ||||
dealt with through a | dealt with through a | ||||
<function>start_precmd</function>.</para> | <function>start_precmd</function>.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>All boolean tests should utilize the | <para>All boolean tests must use the | ||||
<function>checkyesno</function> function. No | <function>checkyesno</function> function. No | ||||
hand-rolled tests for <literal>[Yy][Ee][Ss]</literal>, | hand-rolled tests for <literal>[Yy][Ee][Ss]</literal>, | ||||
etc.</para> | etc.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>If there is a loop (for example, waiting for | <para>If there is a loop (for example, waiting for | ||||
something to start) does it have a counter to terminate | something to start) does it have a counter to terminate | ||||
the loop? We do not want the boot to be stuck forever | the loop? We do not want the boot to be stuck forever | ||||
if there is an error.</para> | if there is an error.</para> | ||||
</step> | </step> | ||||
<step> | <step> | ||||
<para>Does the script create files or directories that | <para>Does the script create files or directories that | ||||
need specific permissions, for example, a | need specific permissions, for example, a | ||||
<filename>pid</filename> file that needs to be owned by | <filename>pid</filename> that needs to be owned by | ||||
the user that runs the process? Rather than the | the user that runs the process? Rather than the | ||||
traditional &man.touch.1;/&man.chown.8;/&man.chmod.1; | traditional &man.touch.1;/&man.chown.8;/&man.chmod.1; | ||||
routine, consider using &man.install.1; with the proper | routine, consider using &man.install.1; with the proper | ||||
command line arguments to do the whole procedure with | command line arguments to do the whole procedure with | ||||
one step.</para> | one step.</para> | ||||
</step> | </step> | ||||
</procedure> | </procedure> | ||||
</sect2> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="users-and-groups"> | <sect1 xml:id="users-and-groups"> | ||||
<title>Adding Users and Groups</title> | <title>Adding Users and Groups</title> | ||||
<para>Some ports require a certain user to be on the installed | <para>Some ports require a certain user to be on the installed | ||||
system. Choose a free UID from 50 to 999 and register it | system. Choose a free UID from 50 to 999 and register it | ||||
either in <filename>ports/UIDs</filename> (for users) or in | either in <filename>ports/UIDs</filename> (for users) or in | ||||
<filename>ports/GIDs</filename> (for groups). Make sure you | <filename>ports/GIDs</filename> (for groups). Make sure | ||||
do not use a UID already used by the system or other | not to use a UID already used by the system or other | ||||
ports.</para> | ports.</para> | ||||
<para>Please include a patch against these two files when you | <para>Please include a patch against these two files when | ||||
require a new user or group to be created for your | requiring a new user or group to be created for the | ||||
port.</para> | port.</para> | ||||
<para>Then you can use <varname>USERS</varname> and | <para>Then use <varname>USERS</varname> and | ||||
<varname>GROUPS</varname> variables in your | <varname>GROUPS</varname> in | ||||
<filename>Makefile</filename>, and the user will be | <filename>Makefile</filename>, and the user will be | ||||
automatically created when installing the port.</para> | automatically created when installing the port.</para> | ||||
<programlisting>USERS= pulse | <programlisting>USERS= pulse | ||||
GROUPS= pulse pulse-access pulse-rt</programlisting> | GROUPS= pulse pulse-access pulse-rt</programlisting> | ||||
<para>The current list of reserved UIDs and GIDs can be found | <para>The current list of reserved UIDs and GIDs can be found | ||||
in <filename>ports/UIDs</filename> and | in <filename>ports/UIDs</filename> and | ||||
Show All 18 Lines |
<para>This section explains the most common things to consider when creating a port.</para>