Date: Sun, 16 Feb 2014 03:25:22 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43956 - head/en_US.ISO8859-1/books/porters-handbook/special Message-ID: <201402160325.s1G3PM7E075667@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402160325.s1G3PM7E075667>