Date: Tue, 16 Sep 2014 12:01:30 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45616 - head/en_US.ISO8859-1/books/porters-handbook/special Message-ID: <201409161201.s8GC1UPW026876@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat (ports committer) Date: Tue Sep 16 12:01:29 2014 New Revision: 45616 URL: http://svnweb.freebsd.org/changeset/doc/45616 Log: igor -Ry and some other rewording and fixes. Differential Revision: https://reviews.freebsd.org/D653 Reviewed by: wblock Sponsored by: Absolight 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 Tue Sep 16 11:58:50 2014 (r45615) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Sep 16 12:01:29 2014 (r45616) @@ -10,16 +10,15 @@ <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> + <para>This section explains the most common things to consider when + creating a port.</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 + must 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 @@ -42,7 +41,7 @@ <note> <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 using <link linkend="uses-uidfix"><literal>USES=uidfix</literal></link>, and from time to time by slightly patching the port's @@ -50,7 +49,7 @@ </note> <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 the basic directory layout of the package, and these empty directories will be seen as orphans. To prevent @@ -58,8 +57,8 @@ <programlisting>NO_MTREE= yes</programlisting> - <para>Staging is enabled by prepending the - <varname>STAGEDIR</varname> variable to paths used in the + <para>Staging is enabled by prepending + <varname>STAGEDIR</varname> to paths used in the <buildtarget>pre-install</buildtarget>, <buildtarget>do-install</buildtarget>, and <buildtarget>post-install</buildtarget> targets (see the @@ -72,21 +71,21 @@ absolute paths whenever possible.</para> <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 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 - <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 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 + <para>Ports that install kernel modules must prepend + <varname>STAGEDIR</varname> to their destination, by default <filename>/boot/modules</filename>.</para> </sect1> @@ -106,7 +105,7 @@ distribution file. The second approach seems easier at 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>; and <link xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>; @@ -220,7 +219,7 @@ port. If such a port does not exist yet, consider creating it.</para> - <para>Bundled libraries should only be used if upstream has a + <para>Only use bundled libraries if the upstream has a good track record on security and using unbundled versions leads to overly complex patches.</para> </sect2> @@ -229,7 +228,7 @@ <sect1 xml:id="porting-shlibs"> <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 instruct a <filename>bsd.port.mk</filename> to run <literal>${LDCONFIG} -m</literal> on the directory @@ -239,21 +238,21 @@ 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 + <literal>@unexec /sbin/ldconfig -R</literal> pair into + <filename>pkg-plist</filename>, 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 + <para>The default directory can be overridden by + setting <varname>USE_LDCONFIG</varname> to a list of 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 <filename>PREFIX/lib/foo</filename> and <filename>PREFIX/lib/bar</filename> - directories you could use the following in your + use this in <filename>Makefile</filename>:</para> <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting> @@ -270,14 +269,14 @@ <para>When installing 32-bit libraries on 64-bit system, use <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 - <command>libtool</command>, you should add <link + <command>libtool</command>, add <link linkend="uses-libtool"><literal>USES=libtool</literal></link>.</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 + the affected library must have their <varname>PORTREVISION</varname> incremented, to force recompilation with the new library version.</para> </sect1> @@ -291,7 +290,7 @@ profit, and so on.</para> <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 &os; project will not be held accountable for violating them by redistributing the source or compiled binaries @@ -300,7 +299,7 @@ </important> <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"> <title><varname>NO_PACKAGE</varname></title> @@ -316,15 +315,16 @@ 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 + <para>If the 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 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, 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 + <para>Set <varname>NO_PACKAGE</varname> to a string + describing the reason why the package cannot be generated.</para> </sect2> @@ -343,9 +343,9 @@ <varname>DISTFILES</varname> will be available, and only via 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 - 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 only.</para> </sect2> @@ -353,13 +353,13 @@ <sect2 xml:id="porting-restrictions-nofetchfiles"> <title><varname>NOFETCHFILES</varname></title> - <para>Files defined in the <varname>NOFETCHFILES</varname> - variable are not fetchable from any of the + <para>Files defined in <varname>NOFETCHFILES</varname> + are not fetchable from any of <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 + on <varname>MASTER_SITES</varname> have to ignore these files and not report about them.</para> </sect2> @@ -371,12 +371,12 @@ <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 + <para>Do not set <varname>NO_CDROM</varname> or + <varname>NO_PACKAGE</varname> along with + <varname>RESTRICTED</varname>, since the latter variable 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. Typically, this indicates that the port contains proprietary software and that the user will need to manually download @@ -400,10 +400,10 @@ <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 + above variables, set <varname>LEGAL_TEXT</varname> + to a string explaining the concern. For 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> </sect2> @@ -482,8 +482,8 @@ IGNORE= may not be redistributed because 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 + (for the legacy &os; version) are available. + 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 @@ -497,10 +497,10 @@ IGNORE= may not be redistributed because linkend="uses-imake"><literal>USES=imake</literal></link> section of <xref linkend="uses"/> for more details.</para> - <para>If your port's source <filename>Makefile</filename> has - something else than <buildtarget>all</buildtarget> as the + <para>If the port's source <filename>Makefile</filename> has + something other than <buildtarget>all</buildtarget> as the main build target, set <varname>ALL_TARGET</varname> - accordingly. Same goes for + accordingly. The same goes for <buildtarget>install</buildtarget> and <varname>INSTALL_TARGET</varname>.</para> </sect2> @@ -508,10 +508,10 @@ IGNORE= may not be redistributed because <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 + <para>If the port uses the <command>configure</command> + script to generate <filename>Makefile</filename> from + <filename>Makefile.in</filename>, set + <literal>GNU_CONFIGURE=yes</literal>. To give extra arguments to the <command>configure</command> script (the default argument is <literal>--prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} @@ -519,7 +519,7 @@ IGNORE= may not be redistributed because --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> + <varname>CONFIGURE_ENV</varname>.</para> <table frame="none" xml:id="using-configure-variables"> <title>Variables for Ports That Use @@ -624,8 +624,8 @@ IGNORE= may not be redistributed because </table> <table frame="none" xml:id="using-cmake-user-variables"> - <title>Variables the Users can define for - <command>cmake</command> builds</title> + <title>Variables the Users Can Define for + <command>cmake</command> Builds</title> <tgroup cols="2"> <thead> @@ -653,7 +653,7 @@ IGNORE= may not be redistributed because </tgroup> </table> - <para><application>CMake</application> supports the following + <para><application>CMake</application> supports these build profiles: <literal>Debug</literal>, <literal>Release</literal>, <literal>RelWithDebInfo</literal> and @@ -664,14 +664,14 @@ IGNORE= may not be redistributed because <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 + exported to <varname>PLIST_SUB</varname> and must be + used if the port installs <filename><replaceable>*</replaceable>.cmake</filename> 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 + <filename>CMakeLists.txt</filename>. 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 @@ -692,7 +692,7 @@ IGNORE= may not be redistributed because <example xml:id="using-cmake-example"> <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. <varname>CMAKE_SOURCE_PATH</varname> is not usually required, but can be set when the sources are not located @@ -707,7 +707,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp <sect2 xml:id="using-scons"> <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> <table frame="none" xml:id="using-scons-variables"> @@ -753,7 +753,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp <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 + <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch <filename>SConstruct</filename> so build <literal>Environment</literal> is constructed like this:</para> @@ -842,9 +842,9 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp <command>autoheader</command></title> <para>Some ports do not contain a configure script, but do - contain an autoconf template in the - <filename>configure.ac</filename> file. You can use the - following assignments to let <command>autoconf</command> + contain an autoconf template in + <filename>configure.ac</filename>. Use these + assignments to let <command>autoconf</command> create the configure script, and also have <command>autoheader</command> create template headers for use by the configure script.</para> @@ -872,14 +872,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp <command>aclocal</command></title> <para>Some packages only contain - <filename>Makefile.am</filename> files. These have to be - converted into <filename>Makefile.in</filename> files using + <filename>Makefile.am</filename>. These have to be + converted into <filename>Makefile.in</filename> using <command>automake</command>, and the further processed by <command>configure</command> to generate an actual <filename>Makefile</filename>.</para> <para>Similarly, packages occasionally do not ship with - included <filename>aclocal.m4</filename> files, again + an included <filename>aclocal.m4</filename>, again required to build the software. This can be achieved with <command>aclocal</command>, which scans <filename>configure.ac</filename> or @@ -914,8 +914,8 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subp <sect2 xml:id="using-gettext-basic"> <title>Basic Usage</title> - <para>If your port requires <literal>gettext</literal>, set - <literal>USES= gettext</literal>, and your port will inherit + <para>If the port requires <literal>gettext</literal>, set + <literal>USES= gettext</literal>, and the port will inherit a dependency on <filename>libintl.so</filename> from <package role="port">devel/gettext</package>. Other values for <literal>gettext</literal> usage are listed in @@ -945,13 +945,13 @@ GNU_CONFIGURE= yes</programlisting> <sect2 xml:id="using-gettext-optional"> <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, through passing <option>--disable-nls</option> to - <command>configure</command>. In that case, your port - should use <literal>gettext</literal> conditionally, - depending on the status of the <varname>NLS</varname> - option. For ports of low to medium complexity, you can rely - on the following idiom:</para> + <command>configure</command>. In that case, the port + must use <literal>gettext</literal> conditionally, + depending on the status of the <literal>NLS</literal> + option. For ports of low to medium complexity, use + this idiom:</para> <programlisting>GNU_CONFIGURE= yes @@ -981,7 +981,7 @@ PLIST_SUB+= NLS="@comment " .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 conditionally. The <filename>Makefile</filename> part of this task is already provided by the idiom. It is explained @@ -994,7 +994,7 @@ PLIST_SUB+= NLS="@comment " Consequently, the lines prefixed by <literal>%%NLS%%</literal> will become mere comments in the 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 catalog file in <filename>pkg-plist</filename>. For example:</para> @@ -1002,8 +1002,8 @@ PLIST_SUB+= NLS="@comment " <programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting> - <para>In high complexity cases, you may need to use more - advanced techniques than the recipe given here, such as + <para>In high complexity cases, more advanced techniques + may be needed, such as <link linkend="plist-dynamic">dynamic packing list generation</link>.</para> </sect2> @@ -1015,7 +1015,7 @@ PLIST_SUB+= NLS="@comment " catalog files. The target directories for them, which reside under <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 in <filename>PORTSDIR/Templates/BSD.local.dist</filename>. @@ -1031,7 +1031,7 @@ PLIST_SUB+= NLS="@comment " <title>Using <application>Perl</application></title> <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, <literal>CPAN/Module</literal> can be used to change it. <varname>MASTER_SITES</varname> can also be set to the old @@ -1050,13 +1050,13 @@ PLIST_SUB+= NLS="@comment " directory. In such case, using author's id as <varname>MASTER_SITE_SUBDIR</varname> is allowed. 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>authors/id/A/AU/AUTHOR</literal>.)</para> + <literal>authors/id/A/AU/AUTHOR</literal>.</para> <para>When a port needs <application>Perl</application> support, - it should use <literal>USES=perl5</literal> with the optional - <varname>USE_PERL5</varname> like described in <link + it must set <literal>USES=perl5</literal> with the optional + <varname>USE_PERL5</varname> described in <link linkend="uses-perl5">the perl5 USES description</link>.</para> <table frame="none" xml:id="using-perl-variables"> @@ -1076,22 +1076,25 @@ PLIST_SUB+= NLS="@comment " <entry><varname>PERL</varname></entry> <entry>The full path of the Perl 5 interpreter, either in the system or installed from a port, but - without the version number. Use this if you need to - replace <quote><literal>#!</literal></quote>lines in - scripts.</entry> + without the version number. Use this when the software + needs the path to the <application>Perl</application> + interpreter. To replace + <quote><literal>#!</literal></quote>lines in scripts, + use <link + linkend="uses-shebangfix">USES=shebangfix</link>.</entry> </row> <row> <entry><varname>PERL_VERSION</varname></entry> <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> <entry><varname>PERL_LEVEL</varname></entry> <entry>The installed Perl version as an integer of the form <literal>MNNNPP</literal> - (e.g., <literal>500809</literal>).</entry> + (for example, <literal>500809</literal>).</entry> </row> <row> @@ -1104,7 +1107,7 @@ PLIST_SUB+= NLS="@comment " <row> <entry><varname>PERL_PORT</varname></entry> <entry>Name of the Perl port that is - installed (e.g., <literal>perl5</literal>).</entry> + installed (for example, <literal>perl5</literal>).</entry> </row> <row> @@ -1119,7 +1122,7 @@ PLIST_SUB+= NLS="@comment " <note> <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 preferred URL form is <literal>http://search.cpan.org/dist/Module-Name/</literal>; @@ -1168,7 +1171,7 @@ PLIST_SUB+= NLS="@comment " <title>X.Org Components</title> <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 components. Available components, at the time of writing, are:</para> @@ -1192,9 +1195,9 @@ PLIST_SUB+= NLS="@comment " <filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para> <para>The Mesa Project is an effort to provide free OpenGL - implementation. You can specify a dependency on various - components of this project with <varname>USE_GL</varname> - variable. Valid options are: + implementation. To specify a dependency on various + components of this project, use <varname>USE_GL</varname>. + Valid options are: <literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and <literal>linux</literal>. For backwards compatibility, the value of <literal>yes</literal> maps to @@ -1238,7 +1241,7 @@ USE_XORG= x11 xpm</programlisting> <sect2 xml:id="x11-motif"> <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 <filename>Makefile</filename>. Default Motif implementation is @@ -1246,11 +1249,11 @@ USE_XORG= x11 xpm</programlisting> Users can choose <package role="port">x11-toolkits/lesstif</package> 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 - 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 the Motif library is referenced in the original <filename>Makefile</filename> or @@ -1263,7 +1266,7 @@ USE_XORG= x11 xpm</programlisting> <para>If the port refers to the Motif library as <literal>-lXm</literal> in its <filename>Makefile</filename> or - <filename>Imakefile</filename>, simply substitute + <filename>Imakefile</filename>, substitute <literal>${MOTIFLIB}</literal> for it.</para> </listitem> @@ -1285,7 +1288,7 @@ USE_XORG= x11 xpm</programlisting> <sect2 xml:id="x11-fonts"> <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 <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para> </sect2> @@ -1295,7 +1298,7 @@ USE_XORG= x11 xpm</programlisting> <para>Some applications require a working X11 display for 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 X server. The working <envar>DISPLAY</envar> is then passed to the build. See <link @@ -1329,7 +1332,7 @@ USE_XORG= x11 xpm</programlisting> Files</title> <para>Ports that include predefined - <filename>*.desktop</filename> files should + <filename><replaceable>*</replaceable>.desktop</filename> must include those files in <filename>pkg-plist</filename> and install them in the <filename>$LOCALBASE/share/applications</filename> @@ -1350,14 +1353,14 @@ USE_XORG= x11 xpm</programlisting> </sect3> <sect3 xml:id="desktop-entries-macro"> - <title>Creating Desktop Entries with the - <varname>DESKTOP_ENTRIES</varname> Macro</title> + <title>Creating Desktop Entries with + <varname>DESKTOP_ENTRIES</varname></title> <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 <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 is:</para> @@ -1376,7 +1379,7 @@ USE_XORG= x11 xpm</programlisting> after it has started. Programs that are not compatible with startup notifications would never clear the indicator (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 all.</para> @@ -1407,12 +1410,12 @@ USE_XORG= x11 xpm</programlisting> <title>Ports That Require Qt</title> <para>The Ports Collection provides support for Qt 4 and Qt 5 - frameworks with the - <varname>USE_QT<replaceable>x</replaceable></varname> - variable, where <replaceable>x</replaceable> is + frameworks with + <varname>USE_QT<replaceable>x</replaceable></varname>, + where <replaceable>x</replaceable> is <literal>4</literal> or <literal>5</literal>. - <varname>USE_QT<replaceable>x</replaceable></varname> should - be set to the list of required Qt components (libraries, + Set <varname>USE_QT<replaceable>x</replaceable></varname> + to the list of required Qt components (libraries, tools, plugins). The Qt 4 and Qt 5 frameworks are quite similar. The main difference is the set of supported components.</para> @@ -1494,29 +1497,29 @@ PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ <para>Some configure scripts do not support the arguments above. To suppress modification of<varname>CONFIGURE_ENV</varname> - and <varname>CONFIGURE_ARGS</varname>, set the - <varname>QT_NONSTANDARD</varname> variable.</para> + and <varname>CONFIGURE_ARGS</varname>, set + <varname>QT_NONSTANDARD</varname>.</para> </sect2> <sect2 xml:id="qt-components"> <title>Component Selection</title> <para>Individual Qt tool and library dependencies must be - specified in the - <varname>USE_QT<replaceable>x</replaceable></varname> - variable. Every component can be suffixed with + specified in + <varname>USE_QT<replaceable>x</replaceable></varname>. + Every component can be suffixed with <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 depended on at both build- and runtime. Usually, library - components should be specified unsuffixed, tool components - should be specified with the <literal>_build</literal> suffix - and plugin components should be specified with the + components are specified unsuffixed, tool components + are mostly specified with the <literal>_build</literal> suffix + and plugin components are specified with the <literal>_run</literal> suffix. The most commonly used components are listed below (all available components are listed in <varname>_USE_QT_ALL</varname>, <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> <table frame="none" xml:id="using-qt-library-list"> @@ -1784,10 +1787,10 @@ USE_QT5= buildtools_build</programlistin <para><emphasis>Missing additional include paths.</emphasis> Many applications come with system tray icon support, but neglect to look for - includes and/or libraries in the X11 directories. You - can tell <command>qmake</command> to add directories to - the include and library search paths via the command - line, for example:</para> + includes and/or libraries in the X11 directories. To add + directories to <command>qmake</command>'s + include and library search paths via the command + line, use:</para> <programlisting>QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib</programlisting> @@ -1819,11 +1822,11 @@ USE_QT5= buildtools_build</programlistin <varname>USE_KDE4</varname> to the list of required components. <literal>_build</literal> and <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 - 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 - (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 components are documented at the top of <filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para> @@ -1995,7 +1998,7 @@ USE_QT5= buildtools_build</programlistin determined through configure log. <varname>USE_KDE4</varname> does not imply <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> <programlisting>USES= cmake:outsource @@ -2011,14 +2014,14 @@ USE_QT4= moc_build qmake_build rcc_build <sect2 xml:id="java-variables"> <title>Variable Definitions</title> - <para>If your port needs a Java™ Development Kit - (JDK™) to either build, run or even extract the - distfile, then it should define + <para>If the port needs a Java™ Development Kit + (<acronym>JDK</acronym>™) to either build, run or even extract the + distfile, then define <varname>USE_JAVA</varname>.</para> - <para>There are several JDKs in the ports collection, from - various vendors, and in several versions. If your port must - use one of these versions, you can define which one. The + <para>There are several <acronym>JDK</acronym>s in the ports collection, from + various vendors, and in several versions. If the port must + use one of these versions, define which one. The most current version, and &os; default is <package role="port">java/openjdk6</package>.</para> @@ -2037,7 +2040,7 @@ USE_QT4= moc_build qmake_build rcc_build <tbody> <row> <entry><varname>USE_JAVA</varname></entry> - <entry>Should be defined for the remaining variables + <entry>Define for the remaining variables to have any effect.</entry> </row> @@ -2045,21 +2048,21 @@ USE_QT4= moc_build qmake_build rcc_build <entry><varname>JAVA_VERSION</varname></entry> <entry>List of space-separated suitable Java versions for the port. An optional <literal>"+"</literal> - allows you to specify a range of versions (allowed + allows specifying a range of versions (allowed values: <literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry> </row> <row> <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: <literal>native linux</literal>).</entry> </row> <row> <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: <literal>freebsd bsdjava sun openjdk</literal>).</entry> @@ -2067,23 +2070,20 @@ USE_QT4= moc_build qmake_build rcc_build <row> <entry><varname>JAVA_BUILD</varname></entry> - <entry>When set, it means that the selected JDK port - should be added to the build dependencies of the - port.</entry> + <entry>When set, add the selected <acronym>JDK</acronym> port to the build + dependencies.</entry> </row> <row> <entry><varname>JAVA_RUN</varname></entry> - <entry>When set, it means that the selected JDK port - should be added to the run dependencies of the - port.</entry> + <entry>When set, add the selected <acronym>JDK</acronym> port to the run + dependencies.</entry> </row> <row> <entry><varname>JAVA_EXTRACT</varname></entry> - <entry>When set, it means that the selected JDK port - should be added to the extract dependencies of the - port.</entry> + <entry>When set, add the selected <acronym>JDK</acronym> port to the + extract dependencies.</entry> </row> </tbody> </tgroup> @@ -2106,61 +2106,61 @@ USE_QT4= moc_build qmake_build rcc_build <tbody> <row> <entry><varname>JAVA_PORT</varname></entry> - <entry>The name of the JDK port (e.g., - <literal>'java/openjdk6'</literal>).</entry> + <entry>The name of the <acronym>JDK</acronym> port (for example, + <literal>java/openjdk6</literal>).</entry> </row> <row> <entry><varname>JAVA_PORT_VERSION</varname></entry> - <entry>The full version of the JDK port (e.g., - <literal>'1.6.0'</literal>). If you only need the - first two digits of this version number, use + <entry>The full version of the <acronym>JDK</acronym> port (for example, + <literal>1.6.0</literal>). Only the first two + digits of this version number are needed, use <varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry> </row> <row> <entry><varname>JAVA_PORT_OS</varname></entry> - <entry>The operating system used by the JDK port - (e.g., <literal>'native'</literal>).</entry> + <entry>The operating system used by the <acronym>JDK</acronym> port + (for example, <literal>'native'</literal>).</entry> </row> <row> <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> </row> <row> <entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> <entry>Description of the operating system used by the - JDK port (e.g., + <acronym>JDK</acronym> port (for example, <literal>'Native'</literal>).</entry> </row> <row> <entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> - <entry>Description of the vendor of the JDK port - (e.g., <literal>'OpenJDK BSD Porting + <entry>Description of the vendor of the <acronym>JDK</acronym> port + (for example, <literal>'OpenJDK BSD Porting Team'</literal>).</entry> </row> <row> <entry><varname>JAVA_HOME</varname></entry> - <entry>Path to the installation directory of the JDK - (e.g., + <entry>Path to the installation directory of the <acronym>JDK</acronym> + (for example, <filename>'/usr/local/openjdk6'</filename>).</entry> </row> <row> <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> </row> <row> <entry><varname>JAR</varname></entry> <entry>Path to the <command>jar</command> tool to use - (e.g., + (for example, <filename>'/usr/local/openjdk6/bin/jar'</filename> or <filename>'/usr/local/bin/fastjar'</filename>).</entry> @@ -2169,14 +2169,14 @@ USE_QT4= moc_build qmake_build rcc_build <row> <entry><varname>APPLETVIEWER</varname></entry> <entry>Path to the <command>appletviewer</command> - utility (e.g., + utility (for example, <filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> </row> <row> <entry><varname>JAVA</varname></entry> <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> </row> @@ -2242,7 +2242,7 @@ USE_QT4= moc_build qmake_build rcc_build <row> <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, <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> </row> @@ -2250,11 +2250,11 @@ USE_QT4= moc_build qmake_build rcc_build </tgroup> </table> - <para>You may use the <literal>java-debug</literal> make - target to get information for debugging your port. It will - display the value of many of the forecited variables.</para> + <para>Use the <buildtarget>java-debug</buildtarget> make + target to get information for debugging the port. It will + display the value of many of the previously listed variables.</para> - <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> <table frame="none" xml:id="using-java-constants"> @@ -2278,7 +2278,7 @@ USE_QT4= moc_build qmake_build rcc_build <row> <entry><varname>JAVAJARDIR</varname></entry> - <entry>The directory where JAR files should be + <entry>The directory where JAR files is installed. Default: <filename>${JAVASHAREDIR}/classes</filename>.</entry> </row> @@ -2305,37 +2305,37 @@ USE_QT4= moc_build qmake_build rcc_build <para>When the port is to be built using Apache Ant, it has to define <varname>USE_ANT</varname>. Ant is thus considered to be the sub-make command. When no - <literal>do-build</literal> target is defined by the port, a - default one will be set that simply runs Ant according to + <buildtarget>do-build</buildtarget> target is defined by the port, a + default one will be set that runs Ant according to <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> 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> </sect2> <sect2 xml:id="java-best-practices"> <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 everything else under <filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for - the documentation, see below). In order to reduce the - packing file size, you may reference the JAR file(s) - directly in the <filename>Makefile</filename>. Just use the - following statement (where <filename>myport.jar</filename> + the documentation, see below). To reduce the + packing file size, reference the JAR file(s) + directly in the <filename>Makefile</filename>. Use this + statement (where <filename><replaceable>myport</replaceable>.jar</filename> is the name of the JAR file installed as part of the 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 installs everything under a single directory (including its *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409161201.s8GC1UPW026876>