Date: Sun, 8 Dec 2013 18:04:02 +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: r43302 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201312081804.rB8I4296081305@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Dec 8 18:04:01 2013 New Revision: 43302 URL: http://svnweb.freebsd.org/changeset/doc/43302 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml head/en_US.ISO8859-1/books/porters-handbook/uses.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Dec 8 16:29:37 2013 (r43301) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Dec 8 18:04:01 2013 (r43302) @@ -9,11 +9,18 @@ $FreeBSD$ --> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> - <info><title>FreeBSD Porter's Handbook</title> + +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:lang="en"> + + <info> + <title>FreeBSD Porter's Handbook</title> <authorgroup> - <author><orgname>The FreeBSD Documentation Project</orgname></author> + <author> + <orgname>The FreeBSD Documentation Project</orgname> + </author> </authorgroup> <pubdate>$FreeBSD$</pubdate> @@ -129,9 +136,10 @@ <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> - <para>This setting enables the <quote>developer mode</quote> that - displays deprecation warnings and activates some further quality - checks on calling the <command>make</command> command.</para> + <para>This setting enables the <quote>developer mode</quote> + that displays deprecation warnings and activates some further + quality checks on calling the <command>make</command> + command.</para> </note> <sect1 xml:id="porting-makefile"> @@ -361,16 +369,16 @@ PLIST_DIRS= lib/X11/oneko</programlistin <listitem> <para>The port can be deinstalled properly using the - <buildtarget>deinstall</buildtarget> target. This verifies - that the deinstall script works correctly.</para> + <buildtarget>deinstall</buildtarget> target. This + verifies that the deinstall script works correctly.</para> </listitem> <listitem> <para>Make sure that <command>make package</command> can be run as a normal user (that is, not as - <systemitem class="username">root</systemitem>). If that fails, - <literal>NEED_ROOT=yes</literal> must be added to the - port <filename>Makefile</filename>.</para> + <systemitem class="username">root</systemitem>). If that + fails, <literal>NEED_ROOT=yes</literal> must be added to + the port <filename>Makefile</filename>.</para> </listitem> </itemizedlist> @@ -413,11 +421,13 @@ PLIST_DIRS= lib/X11/oneko</programlistin <para>Make certain no warnings are shown in any of the stages.</para> - <para>Thorough automated testing can be done with <package>ports-mgmt/tinderbox</package> or - <package>ports-mgmt/poudriere</package> from the Ports Collection. - These applications maintain + <para>Thorough automated testing can be done with + <package>ports-mgmt/tinderbox</package> or + <package>ports-mgmt/poudriere</package> from the Ports + Collection. These applications maintain <literal>jails</literal> where all of the steps shown above - can be tested without affecting the state of the host system.</para> + can be tested without affecting the state of the host + system.</para> </sect1> <sect1 xml:id="porting-portlint"> @@ -455,7 +465,8 @@ PLIST_DIRS= lib/X11/oneko</programlistin <para>Include your <literal>oneko.shar</literal> file in a bug report and send it with the &man.send-pr.1; program (see - <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + <link + xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General Commentary</link> for more information about &man.send-pr.1;). Be sure to classify the bug report as category <literal>ports</literal> and class @@ -485,12 +496,14 @@ PLIST_DIRS= lib/X11/oneko</programlistin <para>After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in &os;, although it might only take a few days. You can - view the list of <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports + view the list of <link + xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports PRs waiting to be committed to &os;</link>.</para> <para>Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also - be added to the list of <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional + be added to the list of <link + xlink:href="&url.articles.contributors;/contrib-additional.html">Additional FreeBSD Contributors</link> and other files.</para> </sect1> </chapter> @@ -518,20 +531,20 @@ PLIST_DIRS= lib/X11/oneko</programlistin <procedure> <step> - <para>The <buildtarget>fetch</buildtarget> target is run. The - <buildtarget>fetch</buildtarget> target is responsible for - making sure that the tarball exists locally in + <para>The <buildtarget>fetch</buildtarget> target is run. + The <buildtarget>fetch</buildtarget> target is responsible + for making sure that the tarball exists locally in <varname>DISTDIR</varname>. If <buildtarget>fetch</buildtarget> cannot find the required files in <varname>DISTDIR</varname> it will look up the URL <varname>MASTER_SITES</varname>, which is set in the - Makefile, as well as our FTP mirrors - where we put distfiles as backup. It will then - attempt to fetch the named distribution file with - <varname>FETCH</varname>, assuming that the requesting - site has direct access to the Internet. If that succeeds, - it will save the file in <varname>DISTDIR</varname> for - future use and proceed.</para> + Makefile, as well as our FTP mirrors where we put + distfiles as backup. It will then attempt to fetch the + named distribution file with <varname>FETCH</varname>, + assuming that the requesting site has direct access to the + Internet. If that succeeds, it will save the file in + <varname>DISTDIR</varname> for future use and + proceed.</para> </step> <step> @@ -555,8 +568,8 @@ PLIST_DIRS= lib/X11/oneko</programlistin </step> <step> - <para>The <buildtarget>configure</buildtarget> target is run. - This can do any one of many different things.</para> + <para>The <buildtarget>configure</buildtarget> target is + run. This can do any one of many different things.</para> <orderedlist> <listitem> @@ -582,11 +595,12 @@ PLIST_DIRS= lib/X11/oneko</programlistin </step> <step> - <para>The <buildtarget>stage</buildtarget> target is run. This - puts the final set of built files into a temporary directory - (<varname>STAGEDIR</varname>, see <xref linkend="staging"/>). The hierarchy of this directory - mirrors that of the system on which the package will be - installed.</para> + <para>The <buildtarget>stage</buildtarget> target is run. + This puts the final set of built files into a temporary + directory (<varname>STAGEDIR</varname>, see + <xref linkend="staging"/>). The hierarchy of this + directory mirrors that of the system on which the package + will be installed.</para> </step> <step> @@ -680,8 +694,8 @@ PLIST_DIRS= lib/X11/oneko</programlistin <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the least-preferred solution. The distfile must be placed into <filename>~/public_distfiles/</filename> of someone's - <systemitem>freefall</systemitem> account. Ask the person who commits - your port to do this. This person will also set + <systemitem>freefall</systemitem> account. Ask the person who + commits your port to do this. This person will also set <varname>MASTER_SITES</varname> to <varname>MASTER_SITE_LOCAL</varname> and <varname>MASTER_SITE_SUBDIR</varname> to their @@ -843,9 +857,9 @@ PLIST_DIRS= lib/X11/oneko</programlistin <programlisting>USES= dos2unix DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting> - <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which - invokes <command>find</command> for each element listed in - it.</para> + <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, + which invokes <command>find</command> for each element listed + in it.</para> <programlisting>USES= dos2unix DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting> @@ -854,8 +868,8 @@ DOS2UNIX_GLOB= *.c *.cpp *.h</programlis existing file, you can copy it with an <filename>.orig</filename> extension, and then modify the original one. The <buildtarget>makepatch</buildtarget> target - will write out an appropriate patch file to the <filename>files</filename> directory of the - port.</para> + will write out an appropriate patch file to the + <filename>files</filename> directory of the port.</para> </sect1> <sect1 xml:id="slow-configure"> @@ -1327,9 +1341,10 @@ PORTEPOCH= 1</programlisting> </listitem> <listitem> - <para>If the port can be built with different <link linkend="makefile-masterdir">hardcoded defaults</link> - (usually part of the directory name in a family of - ports), the + <para>If the port can be built with different + <link linkend="makefile-masterdir">hardcoded + defaults</link> (usually part of the directory name in + a family of ports), the <replaceable>-compiled.specifics</replaceable> part should state the compiled-in defaults (the hyphen is optional). Examples are paper size and font @@ -1581,7 +1596,9 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>afterstep*</filename></entry> - <entry>Ports to support the <link xlink:href="http://www.afterstep.org">AfterStep</link> + + <entry>Ports to support the <link + xlink:href="http://www.afterstep.org">AfterStep</link> window manager.</entry> <entry/> </row> @@ -1925,7 +1942,9 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>palm</filename></entry> - <entry>Software support for the <link xlink:href="http://www.palm.com/">Palm™</link> + + <entry>Software support for the <link + xlink:href="http://www.palm.com/">Palm™</link> series.</entry> <entry/> </row> @@ -1954,7 +1973,9 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>plan9*</filename></entry> - <entry>Various programs from <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry> + + <entry>Various programs from <link + xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry> <entry/> </row> @@ -1985,21 +2006,26 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>python*</filename></entry> - <entry>Software related to the <link xlink:href="http://www.python.org/">Python</link> + + <entry>Software related to the <link + xlink:href="http://www.python.org/">Python</link> language.</entry> <entry/> </row> <row> <entry><filename>ruby*</filename></entry> - <entry>Software related to the <link xlink:href="http://www.ruby-lang.org/">Ruby</link> + <entry>Software related to the <link + xlink:href="http://www.ruby-lang.org/">Ruby</link> language.</entry> <entry/> </row> <row> <entry><filename>rubygems*</filename></entry> - <entry>Ports of <link xlink:href="http://www.rubygems.org/">RubyGems</link> + + <entry>Ports of <link + xlink:href="http://www.rubygems.org/">RubyGems</link> packages.</entry> <entry/> </row> @@ -2163,7 +2189,8 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>zope*</filename></entry> - <entry><link xlink:href="http://www.zope.org/">Zope</link> + <entry><link + xlink:href="http://www.zope.org/">Zope</link> support.</entry> <entry/> </row> @@ -2283,15 +2310,16 @@ PORTEPOCH= 1</programlisting> human languages), or preferably both.</para> <para>The rationale for this is that such a change creates a - <link xlink:href="&url.articles.committers-guide;/#ports"> fair - amount of work</link> for both the committers and also - for all users who track changes to the Ports Collection. In + <link + xlink:href="&url.articles.committers-guide;/#ports">fair + amount of work</link> for both the committers and also for + all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no - clear consensus on when a category is <quote>too - big</quote>, nor whether categories should lend themselves - to browsing (and thus what number of categories would be an - ideal number), and so forth.)</para> + clear consensus on when a category is + <quote>too big</quote>, nor whether categories should lend + themselves to browsing (and thus what number of categories + would be an ideal number), and so forth.)</para> <para>Here is the procedure:</para> @@ -2356,8 +2384,9 @@ PORTEPOCH= 1</programlisting> <step> <para>If that PR is approved, a committer will need to - follow the rest of the procedure that is <link xlink:href="&url.articles.committers-guide;/article.html#PORTS"> - outlined in the Committer's Guide</link>.</para> + follow the rest of the procedure that is <link + xlink:href="&url.articles.committers-guide;/article.html#PORTS">outlined + in the Committer's Guide</link>.</para> </step> </procedure> @@ -2812,9 +2841,12 @@ EXTRACT_ONLY= source.tar.gz</programlist and <filename>source2.tar.gz</filename>, which must be downloaded from two different sites. The port's <filename>Makefile</filename> would include lines like - <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> + <xref + linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> + + <example + xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> - <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with One File Per Site</title> @@ -2830,9 +2862,12 @@ DISTFILES= source1.tar.gz:source1 \ should be downloaded from <systemitem>ftp.example2.com</systemitem>. The <filename>Makefile</filename> would then be written like - <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + <xref + linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + + <example + xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> - <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with More Than One File Per Site</title> @@ -2872,9 +2907,11 @@ DISTFILES= source1.tar.gz:source1 \ postfixing purposes since they yield special meaning: <literal>default</literal>, <literal>all</literal> and <literal>ALL</literal> (they are used internally in - item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>). + item <xref + linkend="porting-master-sites-n-what-changes-in-port-targets"/>). Furthermore, <literal>DEFAULT</literal> is a special - purpose word (check item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para> + purpose word (check item <xref + linkend="porting-master-sites-n-DEFAULT-group"/>).</para> </listitem> <listitem> @@ -2891,7 +2928,8 @@ DISTFILES= source1.tar.gz:source1 \ elements with <literal>DEFAULT</literal>, you are just being redundant unless you want to have an element belonging to both <literal>DEFAULT</literal> and other - groups at the same time (check item <xref linkend="porting-master-sites-n-comma-operator"/>).</para> + groups at the same time (check item <xref + linkend="porting-master-sites-n-comma-operator"/>).</para> <para>The following examples are equivalent but the first one is preferred:</para> @@ -2960,9 +2998,8 @@ DISTFILES= source1.tar.gz:source1 \ be terminated with the forward slash <literal>/</literal> character. If any elements belong to any groups, the group postfix - <literal>:n</literal> - must come right after the terminator - <literal>/</literal>. The + <literal>:n</literal> must come right after the + terminator <literal>/</literal>. The <literal>MASTER_SITES:n</literal> mechanism relies on the existence of the terminator <literal>/</literal> to avoid confusing elements @@ -2974,15 +3011,18 @@ DISTFILES= source1.tar.gz:source1 \ required before in both <varname>MASTER_SITE_SUBDIR</varname> and <varname>PATCH_SITE_SUBDIR</varname> elements, if - the postfix immediate preceding character is not - a <literal>/</literal> then <literal>:n</literal> + the postfix immediate preceding character is not a + <literal>/</literal> then <literal>:n</literal> will be considered a valid part of the element instead of a group postfix even if an element is postfixed with <literal>:n</literal>. See both - <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> - and <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <xref + linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> + and <xref + linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> - <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + <example + xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> in @@ -3004,7 +3044,9 @@ DISTFILES= source1.tar.gz:source1 \ </itemizedlist> </example> - <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <example + xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <title>Detailed Use of <literal>MASTER_SITES:n</literal> with Comma Operator, Multiple Files, Multiple Sites and @@ -3199,9 +3241,12 @@ MASTER_SITE_SUBDIR= directory-trial:1 di <filename>bsd.sites.mk</filename>, e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>?</para> - <para>See <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + <para>See <xref + linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + + <example + xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> - <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> with <varname>MASTER_SITE_SOURCEFORGE</varname></title> @@ -3222,9 +3267,12 @@ DISTFILES= something.tar.gz:sourceforge< <para>All examples were done with <varname>MASTER*</varname> variables but they work exactly the same for <varname>PATCH*</varname> ones as - can be seen in <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + can be seen in <xref + linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + + <example + xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> - <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with <varname>PATCH_SITES</varname></title> @@ -3244,27 +3292,30 @@ PATCHFILES= patch1:test</programlisting> <para>All current ports remain the same. The <literal>MASTER_SITES:n</literal> feature code is only activated if there are elements postfixed with - <literal>:n</literal> like - elements according to the aforementioned syntax rules, - especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para> + <literal>:n</literal> like elements according to the + aforementioned syntax rules, especially as shown in + item <xref + linkend="porting-master-sites-n-group-semantics"/>.</para> </listitem> - <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets"> + <listitem + xml:id="porting-master-sites-n-what-changes-in-port-targets"> <para>The port targets remain the same: <buildtarget>checksum</buildtarget>, <buildtarget>makesum</buildtarget>, <buildtarget>patch</buildtarget>, <buildtarget>configure</buildtarget>, - <buildtarget>build</buildtarget>, etc. With the obvious - exceptions of <buildtarget>do-fetch</buildtarget>, + <buildtarget>build</buildtarget>, etc. With the + obvious exceptions of + <buildtarget>do-fetch</buildtarget>, <buildtarget>fetch-list</buildtarget>, <buildtarget>master-sites</buildtarget> and <buildtarget>patch-sites</buildtarget>.</para> <itemizedlist> <listitem> - <para><buildtarget>do-fetch</buildtarget>: deploys the - new grouping postfixed + <para><buildtarget>do-fetch</buildtarget>: deploys + the new grouping postfixed <varname>DISTFILES</varname> and <varname>PATCHFILES</varname> with their matching group elements within both @@ -3272,13 +3323,14 @@ PATCHFILES= patch1:test</programlisting> <varname>PATCH_SITES</varname> which use matching group elements within both <varname>MASTER_SITE_SUBDIR</varname> and - <varname>PATCH_SITE_SUBDIR</varname>. Check <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <varname>PATCH_SITE_SUBDIR</varname>. Check <xref + linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> </listitem> <listitem> <para><buildtarget>fetch-list</buildtarget>: works - like old <buildtarget>fetch-list</buildtarget> with - the exception that it groups just like + like old <buildtarget>fetch-list</buildtarget> + with the exception that it groups just like <buildtarget>do-fetch</buildtarget>.</para> </listitem> @@ -3286,10 +3338,10 @@ PATCHFILES= patch1:test</programlisting> <para><buildtarget>master-sites</buildtarget> and <buildtarget>patch-sites</buildtarget>: (incompatible with older versions) only return the - elements of group <literal>DEFAULT</literal>; in + elements of group <literal>DEFAULT</literal>; in fact, they execute targets - <buildtarget>master-sites-default</buildtarget> and - <buildtarget>patch-sites-default</buildtarget> + <buildtarget>master-sites-default</buildtarget> + and <buildtarget>patch-sites-default</buildtarget> respectively.</para> <para>Furthermore, using target either @@ -3299,7 +3351,8 @@ PATCHFILES= patch1:test</programlisting> <buildtarget>MASTER_SITES</buildtarget> or <buildtarget>PATCH_SITES</buildtarget>. Also, directly checking is not guaranteed to work in any - future versions. Check item <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> + future versions. Check item <xref + linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> for more information on these new port targets.</para> </listitem> @@ -3320,20 +3373,21 @@ PATCHFILES= patch1:test</programlisting> within <varname>MASTER_SITES</varname> and <varname>PATCH_SITES</varname> respectively. For instance, both - <buildtarget>master-sites-DEFAULT</buildtarget> and - <buildtarget>patch-sites-DEFAULT</buildtarget> will - return the elements of group + <buildtarget>master-sites-DEFAULT</buildtarget> + and <buildtarget>patch-sites-DEFAULT</buildtarget> + will return the elements of group <literal>DEFAULT</literal>, <buildtarget>master-sites-test</buildtarget> and - <buildtarget>patch-sites-test</buildtarget> of group - <literal>test</literal>, and thereon.</para> + <buildtarget>patch-sites-test</buildtarget> of + group <literal>test</literal>, and thereon.</para> </listitem> - <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> + <listitem + xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> <para>There are new targets <buildtarget>master-sites-all</buildtarget> and - <buildtarget>patch-sites-all</buildtarget> which do - the work of the old + <buildtarget>patch-sites-all</buildtarget> which + do the work of the old <buildtarget>master-sites</buildtarget> and <buildtarget>patch-sites</buildtarget> ones. They return the elements of all groups as if they all @@ -3343,7 +3397,7 @@ PATCHFILES= patch1:test</programlisting> <varname>MASTER_SITE_OVERRIDE</varname> as there are groups defined within either <varname>DISTFILES</varname> or - <varname>PATCHFILES</varname>; respectively for + <varname>PATCHFILES</varname>; respectively for <buildtarget>master-sites-all</buildtarget> and <buildtarget>patch-sites-all</buildtarget>.</para> </listitem> @@ -3397,7 +3451,9 @@ PATCHFILES= patch1:test</programlisting> add the source distfiles to <varname>DISTFILES</varname> when <varname>PACKAGE_BUILDING</varname> is defined.</para> - <example xml:id="ports-master-sites-n-example-always-keep-distfiles"> + <example + xml:id="ports-master-sites-n-example-always-keep-distfiles"> + <title>Use of <varname>ALWAYS_KEEP_DISTFILES</varname></title> @@ -3419,8 +3475,9 @@ ALWAYS_KEEP_DISTFILES= yes <sect1 xml:id="makefile-maintainer"> <title><varname>MAINTAINER</varname></title> - <para>Set your mail-address here. Please. <!-- smiley - --><emphasis>:-)</emphasis></para> + <para>Set your mail-address here. Please. + <!-- smiley--> + <emphasis>:-)</emphasis></para> <para>Note that only a single address without the comment part is allowed as a <varname>MAINTAINER</varname> value. The @@ -3430,9 +3487,10 @@ ALWAYS_KEEP_DISTFILES= yes <filename>bsd.port.mk</filename>.</para> <para>The maintainer is responsible for keeping the port up to - date, and ensuring the port works correctly. - For a detailed description of the responsibilities of a port - maintainer, refer to the <link xlink:href="&url.articles.contributing-ports;/maintain-port.html">The + date, and ensuring the port works correctly. For a detailed + description of the responsibilities of a port maintainer, + refer to the <link + xlink:href="&url.articles.contributing-ports;/maintain-port.html">The challenge for port maintainers</link> section.</para> <para>Changes to the port will be sent to the maintainer of a @@ -3597,8 +3655,8 @@ ALWAYS_KEEP_DISTFILES= yes <para>The dependency is checked twice, once from within the <buildtarget>build</buildtarget> target and then from within - the <buildtarget>install</buildtarget> target. Also, the name - of the dependency is put into the package so that + the <buildtarget>install</buildtarget> target. Also, the + name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system.</para> </sect2> @@ -3651,8 +3709,8 @@ ALWAYS_KEEP_DISTFILES= yes </note> <para>The dependency is checked from within the - <buildtarget>install</buildtarget> target. Also, the name of - the dependency is put into the package so that + <buildtarget>install</buildtarget> target. Also, the name + of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The <replaceable>target</replaceable> part can be omitted if it is the same as @@ -3794,7 +3852,8 @@ ALWAYS_KEEP_DISTFILES= yes <programlisting>USES= feature[:arguments]</programlisting> - <para>For the complete list of such values, please see <xref linkend="uses-values"/>.</para> + <para>For the complete list of such values, please see + <xref linkend="uses-values"/>.</para> <warning> <para><varname>USES</varname> cannot be assigned after @@ -3983,7 +4042,8 @@ ALWAYS_KEEP_DISTFILES= yes <title>Problems Caused by Automatic Dependencies</title> <para>Dependencies must be declared either explicitly or by - using the <link linkend="makefile-options">OPTIONS framework</link>. + using the + <link linkend="makefile-options">OPTIONS framework</link>. Using other methods like automatic detection complicates indexing, which causes problems for port and package management.</para> @@ -4079,7 +4139,8 @@ LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/b In the sole <filename>Makefile</filename>, you can use <varname>MASTERDIR</varname> to specify the directory where the rest of the files are. Also, use a variable as part of - <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> + <link + linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> so the packages will have different names.</para> <para>This will be best demonstrated by an example. This is @@ -4132,11 +4193,11 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>If your port anchors its man tree somewhere other than <varname>PREFIX</varname>, you can use <varname>MANDIRS</varname> to specify those directories. Note - that the files corresponding to manual pages should be placed in - <filename>pkg-plist</filename> along with the rest of the files. - The purpose of <varname>MANDIRS</varname> is to enable automatic - compression of manual pages, therefore the file names should be - suffixed with <filename>.gz</filename>.</para> + that the files corresponding to manual pages should be placed + in <filename>pkg-plist</filename> along with the rest of the + files. The purpose of <varname>MANDIRS</varname> is to enable + automatic compression of manual pages, therefore the file + names should be suffixed with <filename>.gz</filename>.</para> </sect1> <sect1 xml:id="makefile-info"> @@ -4187,7 +4248,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>These variables are designed to be set by the system administrator. There are many that are standardized in - the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></link> + the <link + xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></link> file.</para> <para>When creating a port, do not make knob names specific @@ -4246,10 +4308,11 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <sect3> <title>Knob Naming</title> - <para>Porters should use like-named knobs, both - for the benefit of end-users and to help keep the number - of knob names down. A list of popular knob names can be - found in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></link> + <para>Porters should use like-named knobs, both for the + benefit of end-users and to help keep the number of knob + names down. A list of popular knob names can be found in + the <link + xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></link> file.</para> <para>Knob names should reflect what the knob is and does. @@ -4962,16 +5025,15 @@ PORTVERSION= 1.0</programlisting> <para>Use the macros provided in <filename>bsd.port.mk</filename> to ensure correct modes of - files in the port's <buildtarget>*-install</buildtarget> targets. - Set ownership directly in + files in the port's <buildtarget>*-install</buildtarget> + targets. Set ownership directly in <filename>pkg-plist</filename> with the corresponding - entries, such as <literal>@owner - owner</literal> and <literal>@group - group</literal>. These - operators work until being overridden, or until the end of - <filename>pkg-plist</filename>, so do not forget to reset them - after they are no longer needed. The default - ownership is <literal>root:wheel</literal>.</para> + entries, such as <literal>@owner owner</literal> and + <literal>@group group</literal>. These operators work until + being overridden, or until the end of + <filename>pkg-plist</filename>, so do not forget to reset + them after they are no longer needed. The default ownership + is <literal>root:wheel</literal>.</para> <itemizedlist> <listitem> @@ -5046,14 +5108,14 @@ PORTVERSION= 1.0</programlisting> <title>Installing a Whole Tree of Files</title> <para>Sometimes, a large number of - files must be installed while preserving their hierarchical organization. For example, - copying over a whole directory tree from - <varname>WRKSRC</varname> to a target directory under - <varname>PREFIX</varname>. Note that + files must be installed while preserving their hierarchical + organization. For example, copying over a whole directory + tree from <varname>WRKSRC</varname> to a target directory + under <varname>PREFIX</varname>. Note that <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>, - <varname>DATADIR</varname>, and other path varialbes must always be - prepended with <varname>STAGEDIR</varname> to respect - staging (see <xref linkend="staging"/>).</para> + <varname>DATADIR</varname>, and other path varialbes must + always be prepended with <varname>STAGEDIR</varname> to + respect staging (see <xref linkend="staging"/>).</para> <para>Two macros exist for this situation. The advantage of using these macros instead of <command>cp</command> is that @@ -5097,9 +5159,10 @@ PORTVERSION= 1.0</programlisting> ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting> <para>These macros do not add the installed files - to <filename>pkg-plist</filename>. They must be added manually. - For optional documentation - (<varname>PORTDOCS</varname>, see <xref linkend="install-documentation"/>) and examples + to <filename>pkg-plist</filename>. They must be added + manually. For optional documentation + (<varname>PORTDOCS</varname>, see + <xref linkend="install-documentation"/>) and examples (<varname>PORTEXAMPLES</varname>), the <literal>%%PORTDOCS%%</literal> or <literal>%%PORTEXAMPLES%%</literal> prefixes must be @@ -5126,9 +5189,10 @@ PORTVERSION= 1.0</programlisting> <para>Since only the files listed in <filename>pkg-plist</filename> are installed, it is safe to always install documentation to <varname>STAGEDIR</varname> - (see <xref linkend="staging"/>). Hence <literal>.if</literal> - blocks are only needed when the installed files are - large enough to cause significant I/O overhead.</para> + (see <xref linkend="staging"/>). Hence + <literal>.if</literal> blocks are only needed when the + installed files are large enough to cause significant I/O + overhead.</para> <programlisting>post-install: ${MKDIR} ${STAGEDIR}${DOCSDIR} @@ -5274,19 +5338,20 @@ PORTVERSION= 1.0</programlisting> <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><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 @@ -5296,38 +5361,40 @@ PORTVERSION= 1.0</programlisting> <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> + 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>, + <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 + <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 + <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> + <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> + <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 @@ -5605,9 +5672,10 @@ IGNORE= may not be redistributed because 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 + 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> @@ -6138,7 +6206,8 @@ PLIST_SUB+= NLS="@comment " top-level hierarchy name. For example, the recommended value for <literal>p5-Module-Name</literal> is <literal>Module</literal>. The top-level hierarchy can be - examined at <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. + examined at <link + xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. This keeps the port working when the author of the module changes.</para> @@ -6260,8 +6329,8 @@ 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 the WWW - line of <filename>pkg-descr</filename>. The + website should 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> (including the trailing slash).</para> @@ -6284,10 +6353,10 @@ PLIST_SUB+= NLS="@comment " </example> <para>For Perl ports that install manual pages, the macro - <varname>PERL5_MAN<replaceable>x</replaceable></varname> (where - <replaceable>x</replaceable> ranges from <literal>1</literal> to - <literal>9</literal>) can be used inside - <filename>pkg-plist</filename>. For example,</para> + <varname>PERL5_MAN<replaceable>x</replaceable></varname> + (where <replaceable>x</replaceable> ranges from + <literal>1</literal> to <literal>9</literal>) can be used + inside <filename>pkg-plist</filename>. For example,</para> <programlisting>lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting> @@ -6441,7 +6510,8 @@ USE_XORG= x11 xpm</programlisting> <sect2 xml:id="desktop-entries"> <title>Desktop Entries</title> - <para>Desktop entries (<link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">a + <para>Desktop entries (<link + xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">a Freedesktop standard</link>) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For @@ -6465,7 +6535,8 @@ USE_XORG= x11 xpm</programlisting> include those files in <filename>pkg-plist</filename> and install them in the <filename>$LOCALBASE/share/applications</filename> - directory. The <link linkend="install-macros"><varname>INSTALL_DATA</varname> + directory. The <link + linkend="install-macros"><varname>INSTALL_DATA</varname> macro</link> is useful for installing these files.</para> </sect3> @@ -6496,7 +6567,8 @@ USE_XORG= x11 xpm</programlisting> <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> <para>The list of possible categories is available on the - <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop + <link + xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop website</link>. <varname>StartupNotify</varname> indicates whether the application is compatible with <emphasis>startup notifications</emphasis>. These are @@ -6526,8 +6598,8 @@ USE_XORG= x11 xpm</programlisting> <title>Using GNOME</title> <para>The FreeBSD/GNOME project uses its own set of variables to - define which GNOME components a particular port uses. A - <link xlink:href="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive + define which GNOME components a particular port uses. A <link + xlink:href="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive list of these variables</link> exists within the FreeBSD/GNOME project's homepage.</para> </sect1> @@ -6863,8 +6935,9 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_RE <row> <entry><varname>QMAKE_PRO</varname></entry> - <entry>Name of the project <filename>.pro</filename> file. - The default is empty (using autodetection).</entry> + <entry>Name of the project <filename>.pro</filename> + file. The default is empty (using + autodetection).</entry> </row> </tbody> </tgroup> @@ -7490,11 +7563,12 @@ USE_QT4= moc_build qmake_build rcc_build <para>All the features that have been presented in this section are implemented in <filename>bsd.java.mk</filename>. If you ever think that your port needs more sophisticated - Java support, please first have a look at the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk - SVN log</link> as it usually takes some time - to document the latest features. Then, if you think the - support you are lacking would be beneficial to many other - Java ports, feel free to discuss it on the &a.java;.</para> + Java support, please first have a look at the <link + xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk + SVN log</link> as it usually takes some time to document + the latest features. Then, if you think the support you are + lacking would be beneficial to many other Java ports, feel + free to discuss it on the &a.java;.</para> <para>Although there is a <literal>java</literal> category for PRs, it refers to the JDK porting effort from the &os; Java @@ -7531,7 +7605,8 @@ USE_QT4= moc_build qmake_build rcc_build etc. The default APACHE version is <literal>22</literal>. More details are available in <filename>ports/Mk/bsd.apache.mk</filename> and - at <link xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201312081804.rB8I4296081305>