svn commit: r43956 - head/en_US.ISO8859-1/books/porters-handbook/special
Warren Block
wblock at FreeBSD.org
Sun Feb 16 03:25:23 UTC 2014
Author: wblock
Date: Sun Feb 16 03:25:22 2014
New Revision: 43956
URL: http://svnweb.freebsd.org/changeset/doc/43956
Log:
Whitespace-only fixes, translators please ignore.
Modified:
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Sun Feb 16 03:09:35 2014 (r43955)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Sun Feb 16 03:25:22 2014 (r43956)
@@ -4,3542 +4,3540 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="special">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="special">
+
+ <title>Special Considerations</title>
+
+ <para>There are some more things you have to take into account
+ when you create a port. This section explains the most common
+ of those.</para>
+
+ <sect1 xml:id="staging">
+ <title>Staging</title>
+
+ <para><filename>bsd.port.mk</filename> expects ports to work
+ with a <quote>stage directory</quote>. This means that a port
+ should not install files directly to the regular destination
+ directories (that is, under <varname>PREFIX</varname>, for
+ example) but instead into a separate directory from which the
+ package is then built. In many cases, this does not require
+ root privileges, making it possible to build packages as an
+ unprivileged user. With staging, the port is built and
+ installed into the stage directory,
+ <varname>STAGEDIR</varname>. A package is created from the
+ stage directory and then installed on the system. Automake
+ tools refer to this concept as <varname>DESTDIR</varname>, but
+ in &os;, <varname>DESTDIR</varname> has a different meaning
+ (see <xref linkend="porting-prefix"/>).</para>
+
+ <para>When a port still requires system-wide privileges in order
+ to run the <buildtarget>package</buildtarget> target, this
+ line must be added to the
+ <filename>Makefile</filename>:</para>
+
+ <programlisting>NEED_ROOT= yes</programlisting>
+
+ <para>Meta ports, or ports that do not install files themselves
+ but only depend on other ports, should avoid needlessly
+ extracting the &man.mtree.8; to the stage directory. This is
+ the basic directory layout of the package, and these empty
+ directories will be seens as orphans. To prevent
+ &man.mtree.8; extraction, add this line:</para>
+
+ <programlisting>NO_MTREE= yes</programlisting>
+
+ <para>Staging is enabled by prepending the
+ <varname>STAGEDIR</varname> variable to paths used in the
+ <buildtarget>pre-install</buildtarget>,
+ <buildtarget>do-install</buildtarget>, and
+ <buildtarget>post-install</buildtarget> targets (see the
+ examples through the book). Typically, this includes
+ <varname>PREFIX</varname>, <varname>ETCDIR</varname>,
+ <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>,
+ <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and
+ so on. Directories should be created as part of the
+ <buildtarget>post-install</buildtarget> target. Avoid using
+ absolute paths whenever possible.</para>
+
+ <para>When creating a symlink, <varname>STAGEDIR</varname>
+ should be prepended to the target path only. For
+ example:</para>
+
+ <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting>
+
+ <para>The source path
+ <filename>${PREFIX}/lib/libfoo.so.42</filename> looks fine but
+ could, in fact, be incorrect. Absolute paths can point to a
+ wrong location, like when a remote file system has been
+ mounted with <acronym>NFS</acronym> under a non-root mount
+ point. Relative paths are less fragile, and often much
+ shorter.</para>
+
+ <para>Ports that install kernel modules must prepend the
+ <varname>STAGEDIR</varname> variable to
+ their destination, by default
+ <filename>/boot/modules</filename>.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-shlibs">
+ <title>Shared Libraries</title>
+
+ <para>If your port installs one or more shared libraries, define
+ a <varname>USE_LDCONFIG</varname> make variable, which will
+ instruct a <filename>bsd.port.mk</filename> to run
+ <literal>${LDCONFIG} -m</literal> on the directory
+ where the new library is installed (usually
+ <filename>PREFIX/lib</filename>) during
+ <buildtarget>post-install</buildtarget> target to register it
+ into the shared library cache. This variable, when defined,
+ will also facilitate addition of an appropriate
+ <literal>@exec /sbin/ldconfig -m</literal> and
+ <literal>@unexec /sbin/ldconfig -R</literal> pair into your
+ <filename>pkg-plist</filename> file, so that a user who
+ installed the package can start using the shared library
+ immediately and de-installation will not cause the system to
+ still believe the library is there.</para>
+
+ <programlisting>USE_LDCONFIG= yes</programlisting>
+
+ <para>If you need, you can override the default directory by
+ setting the <varname>USE_LDCONFIG</varname> value to a list of
+ directories into which shared libraries are to be installed.
+ For example if your port installs shared libraries into
+ <filename>PREFIX/lib/foo</filename> and
+ <filename>PREFIX/lib/bar</filename>
+ directories you could use the following in your
+ <filename>Makefile</filename>:</para>
+
+ <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
+
+ <para>Please double-check, often this is not necessary at all or
+ can be avoided through <literal>-rpath</literal> or setting
+ <envar>LD_RUN_PATH</envar> during linking (see
+ <package role="port">lang/moscow_ml</package> for an
+ example), or through a shell-wrapper which sets
+ <varname>LD_LIBRARY_PATH</varname> before invoking the binary,
+ like <package role="port">www/seamonkey</package>
+ does.</para>
+
+ <para>When installing 32-bit libraries on 64-bit system, use
+ <varname>USE_LDCONFIG32</varname> instead.</para>
+
+ <para>Try to keep shared library version numbers in the
+ <filename>libfoo.so.0</filename> format. Our runtime linker
+ only cares for the major (first) number.</para>
+
+ <para>When the major library version number increments in the
+ update to the new port version, all other ports that link to
+ the affected library should have their
+ <varname>PORTREVISION</varname> incremented, to force
+ recompilation with the new library version.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-restrictions">
+ <title>Ports with Distribution Restrictions or Legal
+ Concerns</title>
+
+ <para>Licenses vary, and some of them place restrictions on how
+ the application can be packaged, whether it can be sold for
+ profit, and so on.</para>
+
+ <important>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the
+ &os; project will not be held accountable for violating
+ them by redistributing the source or compiled binaries
+ either via FTP/HTTP or CD-ROM. If in doubt, please contact
+ the &a.ports;.</para>
+ </important>
+
+ <para>In situations like this, the variables described in the
+ following sections can be set.</para>
+
+ <sect2>
+ <title><varname>NO_PACKAGE</varname></title>
+
+ <para>This variable indicates that we may not generate a
+ binary package of the application. For instance, the
+ license may disallow binary redistribution, or it may
+ prohibit distribution of packages created from patched
+ sources.</para>
+
+ <para>However, the port's <varname>DISTFILES</varname> may be
+ freely mirrored on FTP/HTTP. They may also be distributed
+ on a CD-ROM (or similar media) unless
+ <varname>NO_CDROM</varname> is set as well.</para>
+
+ <para><varname>NO_PACKAGE</varname> should also be used if the
+ binary package is not generally useful, and the application
+ should always be compiled from the source code. For
+ example, if the application has configuration information
+ that is site specific hard coded in to it at compile time,
+ set <varname>NO_PACKAGE</varname>.</para>
+
+ <para><varname>NO_PACKAGE</varname> should be set to a string
+ describing the reason why the package should not be
+ generated.</para>
+ </sect2>
+
+ <sect2>
+ <title><varname>NO_CDROM</varname></title>
+
+ <para>This variable alone indicates that, although we are
+ allowed to generate binary packages, we may put neither
+ those packages nor the port's <varname>DISTFILES</varname>
+ onto a CD-ROM (or similar media) for resale. However, the
+ binary packages and the port's <varname>DISTFILES</varname>
+ will still be available via FTP/HTTP.</para>
+
+ <para> If this variable is set along with
+ <varname>NO_PACKAGE</varname>, then only the port's
+ <varname>DISTFILES</varname> will be available, and only via
+ FTP/HTTP.</para>
+
+ <para><varname>NO_CDROM</varname> should be set to a string
+ describing the reason why the port cannot be redistributed
+ on CD-ROM. For instance, this should be used if the port's
+ license is for <quote>non-commercial</quote> use
+ only.</para>
+ </sect2>
+
+ <sect2>
+ <title><varname>NOFETCHFILES</varname></title>
+
+ <para>Files defined in the <varname>NOFETCHFILES</varname>
+ variable are not fetchable from any of the
+ <varname>MASTER_SITES</varname>. An example of such a file
+ is when the file is supplied on CD-ROM by the vendor.</para>
+
+ <para>Tools which check for the availability of these files
+ on the <varname>MASTER_SITES</varname> should ignore these
+ files and not report about them.</para>
+ </sect2>
+
+ <sect2>
+ <title><varname>RESTRICTED</varname></title>
+
+ <para>Set this variable alone if the application's license
+ permits neither mirroring the application's
+ <varname>DISTFILES</varname> nor distributing the binary
+ package in any way.</para>
+
+ <para><varname>NO_CDROM</varname> or
+ <varname>NO_PACKAGE</varname> should not be set along with
+ <varname>RESTRICTED</varname> since the latter variable
+ implies the former ones.</para>
+
+ <para><varname>RESTRICTED</varname> should be set to a string
+ describing the reason why the port cannot be redistributed.
+ Typically, this indicates that the port contains proprietary
+ software and that the user will need to manually download
+ the <varname>DISTFILES</varname>, possibly after registering
+ for the software or agreeing to accept the terms of an
+ <acronym>EULA</acronym>.</para>
+ </sect2>
+
+ <sect2>
+ <title><varname>RESTRICTED_FILES</varname></title>
+
+ <para>When <varname>RESTRICTED</varname> or
+ <varname>NO_CDROM</varname> is set, this variable defaults
+ to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise
+ it is empty. If only some of the distribution files are
+ restricted, then set this variable to list them.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><varname>LEGAL_TEXT</varname></title>
+
+ <para>If the port has legal concerns not addressed by the
+ above variables, the variable <varname>LEGAL_TEXT</varname>
+ should be set to a string explaining the concern. For
+ example, if special permission was obtained for &os; to
+ redistribute the binary, this variable should indicate
+ so.</para>
+ </sect2>
+
+ <sect2>
+ <title><filename>/usr/ports/LEGAL</filename> and
+ <varname>LEGAL</varname></title>
+
+ <para>A port which sets any of the above variables must also
+ be added to <filename>/usr/ports/LEGAL</filename>. The
+ first column is a glob which matches the restricted
+ distfiles. The second column is the port's origin. The
+ third column is the output of
+ <command>make -VLEGAL</command>.</para>
+ </sect2>
- <title>Special Considerations</title>
+ <sect2>
+ <title>Examples</title>
- <para>There are some more things you have to take into account
- when you create a port. This section explains the most common
- of those.</para>
-
- <sect1 xml:id="staging">
- <title>Staging</title>
-
- <para><filename>bsd.port.mk</filename> expects ports to work
- with a <quote>stage directory</quote>. This means that a port
- should not install files directly to the regular destination
- directories (that is, under <varname>PREFIX</varname>, for
- example) but instead into a separate directory from which the
- package is then built. In many cases, this does not require
- root privileges, making it possible to build packages as an
- unprivileged user. With staging, the port is built and
- installed into the stage directory,
- <varname>STAGEDIR</varname>. A package is created from the
- stage directory and then installed on the system. Automake
- tools refer to this concept as <varname>DESTDIR</varname>, but
- in &os;, <varname>DESTDIR</varname> has a different meaning
- (see <xref linkend="porting-prefix"/>).</para>
-
- <para>When a port still requires system-wide privileges in order
- to run the <buildtarget>package</buildtarget> target, this
- line must be added to the
- <filename>Makefile</filename>:</para>
-
- <programlisting>NEED_ROOT= yes</programlisting>
-
- <para>Meta ports, or ports that do not install files themselves
- but only depend on other ports, should avoid needlessly
- extracting the &man.mtree.8; to the stage directory. This is
- the basic directory layout of the package, and these empty
- directories will be seens as orphans. To prevent
- &man.mtree.8; extraction, add this line:</para>
-
- <programlisting>NO_MTREE= yes</programlisting>
-
- <para>Staging is enabled by prepending the
- <varname>STAGEDIR</varname> variable to paths used in the
- <buildtarget>pre-install</buildtarget>,
- <buildtarget>do-install</buildtarget>, and
- <buildtarget>post-install</buildtarget> targets (see the
- examples through the book). Typically, this includes
- <varname>PREFIX</varname>, <varname>ETCDIR</varname>,
- <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>,
- <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and
- so on. Directories should be created as part of the
- <buildtarget>post-install</buildtarget> target. Avoid using
- absolute paths whenever possible.</para>
+ <para>The preferred way to state "the distfiles for this port
+ must be fetched manually" is as follows:</para>
- <para>When creating a symlink, <varname>STAGEDIR</varname>
- should be prepended to the target path only. For
- example:</para>
-
- <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting>
-
- <para>The source path
- <filename>${PREFIX}/lib/libfoo.so.42</filename> looks fine but
- could, in fact, be incorrect. Absolute paths can point to a
- wrong location, like when a remote file system has been
- mounted with <acronym>NFS</acronym> under a non-root mount
- point. Relative paths are less fragile, and often much
- shorter.</para>
-
- <para>Ports that install kernel modules must prepend the
- <varname>STAGEDIR</varname> variable to
- their destination, by default
- <filename>/boot/modules</filename>.</para>
- </sect1>
-
- <sect1 xml:id="porting-shlibs">
- <title>Shared Libraries</title>
-
- <para>If your port installs one or more shared libraries, define
- a <varname>USE_LDCONFIG</varname> make variable, which will
- instruct a <filename>bsd.port.mk</filename> to run
- <literal>${LDCONFIG} -m</literal> on the directory
- where the new library is installed (usually
- <filename>PREFIX/lib</filename>) during
- <buildtarget>post-install</buildtarget> target to register it
- into the shared library cache. This variable, when defined,
- will also facilitate addition of an appropriate
- <literal>@exec /sbin/ldconfig -m</literal> and
- <literal>@unexec /sbin/ldconfig -R</literal> pair into your
- <filename>pkg-plist</filename> file, so that a user who
- installed the package can start using the shared library
- immediately and de-installation will not cause the system to
- still believe the library is there.</para>
-
- <programlisting>USE_LDCONFIG= yes</programlisting>
-
- <para>If you need, you can override the default directory by
- setting the <varname>USE_LDCONFIG</varname> value to a list of
- directories into which shared libraries are to be installed.
- For example if your port installs shared libraries into
- <filename>PREFIX/lib/foo</filename> and
- <filename>PREFIX/lib/bar</filename>
- directories you could use the following in your
- <filename>Makefile</filename>:</para>
-
- <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
-
- <para>Please double-check, often this is not necessary at all or
- can be avoided through <literal>-rpath</literal> or setting
- <envar>LD_RUN_PATH</envar> during linking (see
- <package role="port">lang/moscow_ml</package> for an
- example), or through a shell-wrapper which sets
- <varname>LD_LIBRARY_PATH</varname> before invoking the binary,
- like <package role="port">www/seamonkey</package>
- does.</para>
-
- <para>When installing 32-bit libraries on 64-bit system, use
- <varname>USE_LDCONFIG32</varname> instead.</para>
-
- <para>Try to keep shared library version numbers in the
- <filename>libfoo.so.0</filename> format. Our runtime linker
- only cares for the major (first) number.</para>
-
- <para>When the major library version number increments in the
- update to the new port version, all other ports that link to
- the affected library should have their
- <varname>PORTREVISION</varname> incremented, to force
- recompilation with the new library version.</para>
- </sect1>
-
- <sect1 xml:id="porting-restrictions">
- <title>Ports with Distribution Restrictions or Legal
- Concerns</title>
-
- <para>Licenses vary, and some of them place restrictions on how
- the application can be packaged, whether it can be sold for
- profit, and so on.</para>
-
- <important>
- <para>It is your responsibility as a porter to read the
- licensing terms of the software and make sure that the
- &os; project will not be held accountable for violating
- them by redistributing the source or compiled binaries
- either via FTP/HTTP or CD-ROM. If in doubt, please contact
- the &a.ports;.</para>
- </important>
-
- <para>In situations like this, the variables described in the
- following sections can be set.</para>
-
- <sect2>
- <title><varname>NO_PACKAGE</varname></title>
-
- <para>This variable indicates that we may not generate a
- binary package of the application. For instance, the
- license may disallow binary redistribution, or it may
- prohibit distribution of packages created from patched
- sources.</para>
-
- <para>However, the port's <varname>DISTFILES</varname> may be
- freely mirrored on FTP/HTTP. They may also be distributed
- on a CD-ROM (or similar media) unless
- <varname>NO_CDROM</varname> is set as well.</para>
-
- <para><varname>NO_PACKAGE</varname> should also be used if the
- binary package is not generally useful, and the application
- should always be compiled from the source code. For
- example, if the application has configuration information
- that is site specific hard coded in to it at compile time,
- set <varname>NO_PACKAGE</varname>.</para>
-
- <para><varname>NO_PACKAGE</varname> should be set to a string
- describing the reason why the package should not be
- generated.</para>
- </sect2>
-
- <sect2>
- <title><varname>NO_CDROM</varname></title>
-
- <para>This variable alone indicates that, although we are
- allowed to generate binary packages, we may put neither
- those packages nor the port's <varname>DISTFILES</varname>
- onto a CD-ROM (or similar media) for resale. However, the
- binary packages and the port's <varname>DISTFILES</varname>
- will still be available via FTP/HTTP.</para>
-
- <para> If this variable is set along with
- <varname>NO_PACKAGE</varname>, then only the port's
- <varname>DISTFILES</varname> will be available, and only via
- FTP/HTTP.</para>
-
- <para><varname>NO_CDROM</varname> should be set to a string
- describing the reason why the port cannot be redistributed
- on CD-ROM. For instance, this should be used if the port's
- license is for <quote>non-commercial</quote> use
- only.</para>
- </sect2>
-
- <sect2>
- <title><varname>NOFETCHFILES</varname></title>
-
- <para>Files defined in the <varname>NOFETCHFILES</varname>
- variable are not fetchable from any of the
- <varname>MASTER_SITES</varname>. An example of such a file
- is when the file is supplied on CD-ROM by the vendor.</para>
-
- <para>Tools which check for the availability of these files
- on the <varname>MASTER_SITES</varname> should ignore these
- files and not report about them.</para>
- </sect2>
-
- <sect2>
- <title><varname>RESTRICTED</varname></title>
-
- <para>Set this variable alone if the application's license
- permits neither mirroring the application's
- <varname>DISTFILES</varname> nor distributing the binary
- package in any way.</para>
-
- <para><varname>NO_CDROM</varname> or
- <varname>NO_PACKAGE</varname> should not be set along with
- <varname>RESTRICTED</varname> since the latter variable
- implies the former ones.</para>
-
- <para><varname>RESTRICTED</varname> should be set to a string
- describing the reason why the port cannot be redistributed.
- Typically, this indicates that the port contains proprietary
- software and that the user will need to manually download
- the <varname>DISTFILES</varname>, possibly after registering
- for the software or agreeing to accept the terms of an
- <acronym>EULA</acronym>.</para>
- </sect2>
-
- <sect2>
- <title><varname>RESTRICTED_FILES</varname></title>
-
- <para>When <varname>RESTRICTED</varname> or
- <varname>NO_CDROM</varname> is set, this variable defaults
- to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise
- it is empty. If only some of the distribution files are
- restricted, then set this variable to list them.</para>
-
- </sect2>
-
- <sect2>
- <title><varname>LEGAL_TEXT</varname></title>
-
- <para>If the port has legal concerns not addressed by the
- above variables, the variable <varname>LEGAL_TEXT</varname>
- should be set to a string explaining the concern. For
- example, if special permission was obtained for &os; to
- redistribute the binary, this variable should indicate
- so.</para>
- </sect2>
-
- <sect2>
- <title><filename>/usr/ports/LEGAL</filename> and
- <varname>LEGAL</varname></title>
-
- <para>A port which sets any of the above variables must also
- be added to <filename>/usr/ports/LEGAL</filename>. The
- first column is a glob which matches the restricted
- distfiles. The second column is the port's origin. The
- third column is the output of
- <command>make -VLEGAL</command>.</para>
- </sect2>
-
- <sect2>
- <title>Examples</title>
-
- <para>The preferred way to state "the distfiles for this port
- must be fetched manually" is as follows:</para>
-
- <programlisting>.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
+ <programlisting>.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
IGNORE= may not be redistributed because of licensing reasons. Please visit <replaceable>some-website</replaceable> to accept their license and download ${DISTFILES} into ${DISTDIR}
.endif</programlisting>
- <para>This both informs the user, and sets the proper metadata
- on the user's machine for use by automated programs.</para>
-
- <para>Note that this stanza must be preceded by an inclusion
- of <filename>bsd.port.pre.mk</filename>.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="building">
- <title>Building Mechanisms</title>
-
- <sect2 xml:id="parallel-builds">
- <title>Building Ports in Parallel</title>
-
- <para>The &os; ports framework supports parallel building
- using multiple <command>make</command> sub-processes, which
- allows <acronym>SMP</acronym> systems to utilize all of
- their available <acronym>CPU</acronym> power, allowing port
- builds to be faster and more effective.</para>
-
- <para>This is achieved by passing <varname>-jX</varname> flag
- to &man.make.1; running on vendor code. This is the default
- build behavior of ports. Unfortunately, not all ports
- handle parallel building well and it may be required to
- explicitly disable this feature by adding the
- <literal>MAKE_JOBS_UNSAFE=yes</literal> variable. It is
- used when a port is known to be broken with
- <varname>-jX</varname>.</para>
-
- </sect2>
-
- <sect2 xml:id="using-make">
- <title><command>make</command>, <command>gmake</command>,
- <command>fmake</command>, and <command>imake</command></title>
-
- <para>Several differing <literal>make</literal>
- implementations exist. Ported software often requires a
- particular implementation, like <acronym>GNU</acronym>
- <command>make</command>, known in &os; as
- <command>gmake</command>, or <command>fmake</command>, the
- legacy &os; <command>make</command>.</para>
-
- <para>If the port uses <application>GNU make</application>,
- add <literal>gmake</literal> to <literal>USES</literal>. If
- the legacy &os; <command>make</command> is needed, add
- <literal>fmake</literal> there.</para>
-
- <para><varname>MAKE_CMD</varname> can be used to reference the
- specific command configured by the <literal>USES</literal>
- setting in the port's <filename>Makefile</filename>. In
- rare cases when more than one <literal>make</literal>
- implementation is listed in <literal>USES</literal>, the
- variables <varname>GMAKE</varname> (for the
- <acronym>GNU</acronym> version) or <varname>FMAKE</varname>
- (for the legacy &os; version) are available. Most ports
- should only use <varname>MAKE_CMD</varname> within the
- application <filename>Makefile</filename>s in
- <varname>WRKSRC</varname> to call the
- <command>make</command> implementation expected by the
- ported software.</para>
-
- <para>If your port is an X application that creates
- <filename>Makefile</filename> files from
- <filename>Imakefile</filename> files using
- <application>imake</application>, then set
- <literal>USES= imake</literal>. This will cause the
- configure stage to automatically do an
- <command>xmkmf -a</command>. If the <option>-a</option>
- flag is a problem for your port, set
- <literal>XMKMF=xmkmf</literal>. If the port uses
- <application>imake</application> but does not understand the
- <buildtarget>install.man</buildtarget> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be
- set.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <buildtarget>all</buildtarget> as the
- main build target, set <varname>ALL_TARGET</varname>
- accordingly. Same goes for
- <buildtarget>install</buildtarget> and
- <varname>INSTALL_TARGET</varname>.</para>
- </sect2>
-
- <sect2 xml:id="using-configure">
- <title><command>configure</command> Script</title>
-
- <para>If your port uses the <command>configure</command>
- script to generate <filename>Makefile</filename> files from
- <filename>Makefile.in</filename> files, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
- extra arguments to the <command>configure</command> script
- (the default argument is <literal>--prefix=${PREFIX}
- --infodir=${PREFIX}/${INFO_PATH}
- --mandir=${MANPREFIX}/man
- --build=${CONFIGURE_TARGET}</literal>), set those
- extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
- environment variables can be passed using
- <varname>CONFIGURE_ENV</varname> variable.</para>
-
- <table frame="none">
- <title>Variables for Ports That Use
- <command>configure</command></title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>GNU_CONFIGURE</varname></entry>
- <entry>The port uses <command>configure</command>
- script to prepare build.</entry>
- </row>
-
- <row>
- <entry><varname>HAS_CONFIGURE</varname></entry>
- <entry>Same as <varname>GNU_CONFIGURE</varname>,
- except default configure target is not added to
- <varname>CONFIGURE_ARGS</varname>.</entry>
- </row>
-
- <row>
- <entry><varname>CONFIGURE_ARGS</varname></entry>
- <entry>Additional arguments passed to
- <command>configure</command> script.</entry>
- </row>
-
- <row>
- <entry><varname>CONFIGURE_ENV</varname></entry>
- <entry>Additional environment variables to be set
- for <command>configure</command> script run.</entry>
- </row>
-
- <row>
- <entry><varname>CONFIGURE_TARGET</varname></entry>
- <entry>Override default configure target. Default
- value is
- <literal>${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- <sect2 xml:id="using-cmake">
- <title>Using <command>cmake</command></title>
-
- <para>For ports that use <application>CMake</application>,
- define <literal>USES= cmake</literal>, or
- <literal>USES= cmake:outsource</literal> to build in a
- separate directory (see below).</para>
-
- <table frame="none">
- <title>Variables for Ports That Use
- <command>cmake</command></title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>CMAKE_ARGS</varname></entry>
- <entry>Port specific <application>CMake</application>
- flags to be passed to the <command>cmake</command>
- binary.</entry>
- </row>
-
- <row>
- <entry><varname>CMAKE_BUILD_TYPE</varname></entry>
- <entry>Type of build (<application>CMake</application>
- predefined build profiles). Default is
- <literal>Release</literal>, or
- <literal>Debug</literal> if
- <varname>WITH_DEBUG</varname> is set.</entry>
- </row>
-
- <row>
- <entry><varname>CMAKE_ENV</varname></entry>
- <entry>Environment variables to be set for the
- <command>cmake</command> binary. Default is
- <literal>${CONFIGURE_ENV}</literal>.</entry>
- </row>
-
- <row>
- <entry><varname>CMAKE_SOURCE_PATH</varname></entry>
- <entry>Path to the source directory. Default is
- <literal>${WRKSRC}</literal>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none">
- <title>Variables the Users can define for
- <command>cmake</command> builds</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>CMAKE_VERBOSE</varname></entry>
- <entry>Enable verbose build output. Default not set,
- unless <varname>BATCH</varname> or
- <varname>PACKAGE_BUILDING</varname> are set.</entry>
- </row>
-
- <row>
- <entry><varname>CMAKE_NOCOLOR</varname></entry>
- <entry>Disables colour build output. Default not set,
- unless <varname>BATCH</varname> or
- <varname>PACKAGE_BUILDING</varname> are set.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para><application>CMake</application> supports the following
- build profiles: <literal>Debug</literal>,
- <literal>Release</literal>,
- <literal>RelWithDebInfo</literal> and
- <literal>MinSizeRel</literal>. <literal>Debug</literal> and
- <literal>Release</literal> profiles respect system
- <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal>
- and <literal>MinSizeRel</literal> will set
- <varname>CFLAGS</varname> to <literal>-O2 -g</literal> and
- <literal>-Os -DNDEBUG</literal> correspondingly. The
- lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is
- exported to the <varname>PLIST_SUB</varname> and should be
- used if port installs <literal>*.cmake</literal> files
- depending on the build type (see
- <package role="port">deskutils/strigi</package> for an
- example). Please note that some projects may define their
- own build profiles and/or force particular build type by
- setting <literal>CMAKE_BUILD_TYPE</literal> in
- <filename>CMakeLists.txt </filename> files. In order to
- make a port for such a project respect
- <varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>,
- the <literal>CMAKE_BUILD_TYPE</literal> definitions must be
- removed from those files.</para>
-
- <para>Most <application>CMake</application>-based projects
- support an out-of-source method of building. The
- out-of-source build for a port can be requested by using the
- <literal>:outsource</literal> suffix. When enabled,
- <varname>CONFIGURE_WRKSRC</varname>,
- <varname>BUILD_WRKSRC</varname> and
- <varname>INSTALL_WRKSRC</varname> will be set to
- <literal>${WRKDIR}/.build</literal> and this
- directory will be used to keep all files generated during
- configuration and build stages, leaving the source directory
- intact.</para>
-
- <example xml:id="using-cmake-example">
- <title><literal>USES= cmake</literal> Example</title>
-
- <para>The following snippet demonstrates the use of
- <application>CMake</application> for a port.
- <varname>CMAKE_SOURCE_PATH</varname> is not usually
- required, but can be set when the sources are not located
- in the top directory, or if only a subset of the project
- is intended to be built by the port.</para>
-
- <programlisting>USES= cmake:outsource
-CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting>
- </example>
- </sect2>
-
- <sect2 xml:id="using-scons">
- <title>Using <command>scons</command></title>
+ <para>This both informs the user, and sets the proper metadata
+ on the user's machine for use by automated programs.</para>
- <para>If your port uses <application>SCons</application>,
- define <literal>USE_SCONS=yes</literal>.</para>
+ <para>Note that this stanza must be preceded by an inclusion
+ of <filename>bsd.port.pre.mk</filename>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="building">
+ <title>Building Mechanisms</title>
+
+ <sect2 xml:id="parallel-builds">
+ <title>Building Ports in Parallel</title>
+
+ <para>The &os; ports framework supports parallel building
+ using multiple <command>make</command> sub-processes, which
+ allows <acronym>SMP</acronym> systems to utilize all of
+ their available <acronym>CPU</acronym> power, allowing port
+ builds to be faster and more effective.</para>
+
+ <para>This is achieved by passing <varname>-jX</varname> flag
+ to &man.make.1; running on vendor code. This is the default
+ build behavior of ports. Unfortunately, not all ports
+ handle parallel building well and it may be required to
+ explicitly disable this feature by adding the
+ <literal>MAKE_JOBS_UNSAFE=yes</literal> variable. It is
+ used when a port is known to be broken with
+ <varname>-jX</varname>.</para>
+ </sect2>
+
+ <sect2 xml:id="using-make">
+ <title><command>make</command>, <command>gmake</command>,
+ <command>fmake</command>, and <command>imake</command></title>
+
+ <para>Several differing <literal>make</literal>
+ implementations exist. Ported software often requires a
+ particular implementation, like <acronym>GNU</acronym>
+ <command>make</command>, known in &os; as
+ <command>gmake</command>, or <command>fmake</command>, the
+ legacy &os; <command>make</command>.</para>
+
+ <para>If the port uses <application>GNU make</application>,
+ add <literal>gmake</literal> to <literal>USES</literal>. If
+ the legacy &os; <command>make</command> is needed, add
+ <literal>fmake</literal> there.</para>
+
+ <para><varname>MAKE_CMD</varname> can be used to reference the
+ specific command configured by the <literal>USES</literal>
+ setting in the port's <filename>Makefile</filename>. In
+ rare cases when more than one <literal>make</literal>
+ implementation is listed in <literal>USES</literal>, the
+ variables <varname>GMAKE</varname> (for the
+ <acronym>GNU</acronym> version) or <varname>FMAKE</varname>
+ (for the legacy &os; version) are available. Most ports
+ should only use <varname>MAKE_CMD</varname> within the
+ application <filename>Makefile</filename>s in
+ <varname>WRKSRC</varname> to call the
+ <command>make</command> implementation expected by the
+ ported software.</para>
+
+ <para>If your port is an X application that creates
+ <filename>Makefile</filename> files from
+ <filename>Imakefile</filename> files using
+ <application>imake</application>, then set
+ <literal>USES= imake</literal>. This will cause the
+ configure stage to automatically do an
+ <command>xmkmf -a</command>. If the <option>-a</option>
+ flag is a problem for your port, set
+ <literal>XMKMF=xmkmf</literal>. If the port uses
+ <application>imake</application> but does not understand the
+ <buildtarget>install.man</buildtarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be
+ set.</para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <buildtarget>all</buildtarget> as the
+ main build target, set <varname>ALL_TARGET</varname>
+ accordingly. Same goes for
+ <buildtarget>install</buildtarget> and
+ <varname>INSTALL_TARGET</varname>.</para>
+ </sect2>
+
+ <sect2 xml:id="using-configure">
+ <title><command>configure</command> Script</title>
+
+ <para>If your port uses the <command>configure</command>
+ script to generate <filename>Makefile</filename> files from
+ <filename>Makefile.in</filename> files, set
+ <literal>GNU_CONFIGURE=yes</literal>. If you want to give
+ extra arguments to the <command>configure</command> script
+ (the default argument is <literal>--prefix=${PREFIX}
+ --infodir=${PREFIX}/${INFO_PATH}
+ --mandir=${MANPREFIX}/man
+ --build=${CONFIGURE_TARGET}</literal>), set those
+ extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
+ environment variables can be passed using
+ <varname>CONFIGURE_ENV</varname> variable.</para>
- <table frame="none">
- <title>Variables for Ports That Use
- <command>scons</command></title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>SCONS_ARGS</varname></entry>
- <entry>Port specific SCons flags passed to the SCons
- environment.</entry>
- </row>
-
- <row>
- <entry><varname>SCONS_BUILDENV</varname></entry>
- <entry>Variables to be set in system
- environment.</entry>
- </row>
-
- <row>
- <entry><varname>SCONS_ENV</varname></entry>
- <entry>Variables to be set in SCons
- environment.</entry>
- </row>
-
- <row>
- <entry><varname>SCONS_TARGET</varname></entry>
- <entry>Last argument passed to SCons, similar to
- <varname>MAKE_TARGET</varname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>To make third party <filename>SConstruct</filename>
- respect everything that is passed to SCons in
- <varname>SCONS_ENV</varname> (that is, most importantly,
- <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the
- <filename>SConstruct</filename> so build
- <literal>Environment</literal> is constructed like
- this:</para>
-
- <programlisting>env = Environment(**ARGUMENTS)</programlisting>
-
- <para>It may be then modified with
- <literal>env.Append</literal> and
- <literal>env.Replace</literal>.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="using-autotools">
- <title>Using GNU Autotools</title>
-
- <sect2 xml:id="using-autotools-introduction">
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list