svn commit: r45627 - head/en_US.ISO8859-1/books/porters-handbook/makefiles
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 16 20:12:18 UTC 2014
Author: mat (ports committer)
Date: Tue Sep 16 20:12:18 2014
New Revision: 45627
URL: http://svnweb.freebsd.org/changeset/doc/45627
Log:
igor -Ry and some other rewording and fixes.
Differential Revision: https://reviews.freebsd.org/D643
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Tue Sep 16 19:29:22 2014 (r45626)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Tue Sep 16 20:12:18 2014 (r45627)
@@ -11,35 +11,34 @@
<title>Configuring the Makefile</title>
<para>Configuring the <filename>Makefile</filename> is pretty
- simple, and again we suggest that you look at existing examples
+ simple, and again we suggest looking at existing examples
before starting. Also, there is a
<link linkend="porting-samplem">sample Makefile</link> in this
handbook, so take a look and please follow the ordering of
- variables and sections in that template to make your port easier
+ variables and sections in that template to make the port easier
for others to read.</para>
- <para>Now, consider the following problems in sequence as you
- design your new <filename>Makefile</filename>:</para>
+ <para>Consider these problems in sequence during the
+ design of the new <filename>Makefile</filename>:</para>
<sect1 xml:id="makefile-source">
<title>The Original Source</title>
<para>Does it live in <varname>DISTDIR</varname> as a standard
<command>gzip</command>ped tarball named something like
- <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
- to the next step. If not, you should look at overriding any of
- the <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
+ <filename>foozolix-1.2.tar.gz</filename>? If so, go on
+ to the next step. If not, the distribution file format might
+ require overriding one or more of
+ <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
<varname>EXTRACT_CMD</varname>,
<varname>EXTRACT_BEFORE_ARGS</varname>,
<varname>EXTRACT_AFTER_ARGS</varname>,
- <varname>EXTRACT_SUFX</varname>, or <varname>DISTFILES</varname>
- variables, depending on how alien a format your port's
- distribution file is.</para>
+ <varname>EXTRACT_SUFX</varname>, or
+ <varname>DISTFILES</varname>.</para>
- <para>In the worst case, you can simply create your own
+ <para>In the worst case, create a custom
<buildtarget>do-extract</buildtarget> target to override the
- default, though this should be rarely, if ever,
- necessary.</para>
+ default. This is rarely, if ever, necessary.</para>
</sect1>
<sect1 xml:id="makefile-naming">
@@ -53,17 +52,17 @@
<title><varname>PORTNAME</varname> and
<varname>PORTVERSION</varname></title>
- <para>You should set <varname>PORTNAME</varname> to the base
- name of your port, and <varname>PORTVERSION</varname> to the
+ <para>Set <varname>PORTNAME</varname> to the base
+ name of the port, and <varname>PORTVERSION</varname> to the
version number of the port.</para>
- <warning>
- <para>Package name should be unique among all of the ports
- tree, check that there is not already a port with the same
+ <important>
+ <para>The package name must be unique among all of the ports
+ tree. Make sure that there is not already a port with the same
<varname>PORTNAME</varname> and if there is add one of <link
linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
or <varname>PKGNAMESUFFIX</varname></link>.</para>
- </warning>
+ </important>
</sect2>
<sect2 xml:id="makefile-naming-revepoch">
@@ -73,24 +72,24 @@
<sect3 xml:id="makefile-portrevision">
<title><varname>PORTREVISION</varname></title>
- <para>The <varname>PORTREVISION</varname> variable is a
+ <para><varname>PORTREVISION</varname> is a
monotonically increasing value which is reset to 0 with
- every increase of <varname>PORTVERSION</varname> (i.e.,
- every time a new official vendor release is made), and
- appended to the package name if non-zero. Changes to
+ every increase of <varname>PORTVERSION</varname>, typically
+ every time there is a new official vendor release. If
+ <varname>PORTREVISION</varname> is non-zero, the value is
+ appended to the package name. Changes to
<varname>PORTREVISION</varname> are used by automated tools
- (e.g., <command>pkg version</command>, see
- &man.pkg-version.8;) to highlight the fact that a new
- package is available.</para>
+ like &man.pkg-version.8; to determine that a new package is
+ available.</para>
- <para><varname>PORTREVISION</varname> should be increased each
+ <para><varname>PORTREVISION</varname> must be increased each
time a change is made to the port that changes the generated
package in any way. That includes changes that only affect
a package built with non-default
<link linkend="makefile-options">options</link>.</para>
<para>Examples of when <varname>PORTREVISION</varname>
- should be bumped:</para>
+ must be bumped:</para>
<itemizedlist>
<listitem>
@@ -107,9 +106,9 @@
<listitem>
<para>Changes in the packing list or the install-time
- behavior of the package (e.g., change to a script which
- generates initial data for the package, like ssh host
- keys).</para>
+ behavior of the package. For example, a change to a script which
+ generates initial data for the package, like &man.ssh.1; host
+ keys.</para>
</listitem>
<listitem>
@@ -122,7 +121,7 @@
<listitem>
<para>Silent changes to the port distfile which have
- significant functional differences, i.e., changes to the
+ significant functional differences. For example, changes to the
distfile requiring a correction to
<filename>distinfo</filename> with no corresponding
change to <varname>PORTVERSION</varname>, where a
@@ -150,30 +149,39 @@
<listitem>
<para>Trivial patches to the distfile such as correction
of typos, which are not important enough that users of
- the package should go to the trouble of
+ the package have to go to the trouble of
upgrading.</para>
</listitem>
<listitem>
<para>Build fixes which cause a package to become
- compilable where it was previously failing (as long as
+ compilable where it was previously failing. As long as
the changes do not introduce any functional change on
any other platforms on which the port did previously
- build). Since <varname>PORTREVISION</varname> reflects
+ build. Since <varname>PORTREVISION</varname> reflects
the content of the package, if the package was not
previously buildable then there is no need to increase
<varname>PORTREVISION</varname> to mark a change.</para>
</listitem>
</itemizedlist>
- <para>A rule of thumb is to ask yourself whether a change
- committed to a port is something which everyone would
- benefit from having (either because of an enhancement, fix,
+ <para>A rule of thumb is to decide whether a change
+ committed to a port is something which <emphasis>some</emphasis> people would
+ benefit from having. Either because of an enhancement, fix,
or by virtue that the new package will actually work at
- all), and weigh that against that fact that it will cause
+ all. Then weigh that against that fact that it will cause
everyone who regularly updates their ports tree to be
- compelled to update. If yes, the
- <varname>PORTREVISION</varname> should be bumped.</para>
+ compelled to update. If yes,
+ <varname>PORTREVISION</varname> must be bumped.</para>
+
+ <note>
+ <para>People using binary packages will
+ <emphasis>never</emphasis> see the update if
+ <varname>PORTREVISION</varname> is not bumped. Without
+ increasing <varname>PORTREVISION</varname>, the
+ package builders have no way to detect the change and
+ thus, will not rebuild the package.</para>
+ </note>
</sect3>
<sect3 xml:id="makefile-portepoch">
@@ -194,38 +202,38 @@
two version number strings. For example:</para>
<screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
-></screen>
+ ></screen>
<para>The <literal>></literal> output indicates that
version 0.031 is considered greater than version 0.29,
which may not have been obvious to the porter.</para>
</tip>
- <para>In situations such as this, the
- <varname>PORTEPOCH</varname> version should be increased.
+ <para>In situations such as this,
+ <varname>PORTEPOCH</varname> must be increased.
If <varname>PORTEPOCH</varname> is nonzero it is appended to
the package name as described in section 0 above.
<varname>PORTEPOCH</varname> must never be decreased or
reset to zero, because that would cause comparison to a
- package from an earlier epoch to fail (i.e., the package
- would not be detected as out of date): the new version
- number (e.g., <literal>1.0,1</literal> in the above example)
- is still numerically less than the previous version
- (20000801), but the <literal>,1</literal> suffix is treated
+ package from an earlier epoch to fail. For example, the package
+ would not be detected as out of date. The new version
+ number, <literal>1.0,1</literal> in the above
+ example, is still numerically less than the previous version,
+ 20000801, but the <literal>,1</literal> suffix is treated
specially by automated tools and found to be greater than
the implied suffix <literal>,0</literal> on the earlier
package.</para>
<para>Dropping or resetting <varname>PORTEPOCH</varname>
- incorrectly leads to no end of grief; if you do not
- understand the above discussion, please keep after it until
- you do, or ask questions on the mailing lists.</para>
+ incorrectly leads to no end of grief. If the discussion
+ above was not clear enough, please consult the
+ &a.ports;.</para>
<para>It is expected that <varname>PORTEPOCH</varname> will
not be used for the majority of ports, and that sensible use
of <varname>PORTVERSION</varname> can often preempt it
becoming necessary if a future release of the software
- should change the version structure. However, care is
+ changes the version structure. However, care is
needed by &os; porters when a vendor release is made without
an official version number — such as a code
<quote>snapshot</quote> release. The temptation is to label
@@ -234,11 +242,14 @@
release is made.</para>
<para>For example, if a snapshot release is made on the date
- 20000917, and the previous version of the software was
- version 1.2, the snapshot release should be given a
- <varname>PORTVERSION</varname> of 1.2.20000917 or similar,
- not 20000917, so that the succeeding release, say 1.3, is
- still a numerically greater value.</para>
+ <literal>20000917</literal>, and the previous version of the software was
+ version <literal>1.2</literal>, do not use
+ <literal>20000917</literal> for
+ <varname>PORTVERSION</varname>. The correct way is a
+ <varname>PORTVERSION</varname> of
+ <literal>1.2.20000917</literal>, or similar, so that the
+ succeeding release, say <literal>1.3</literal>, is still a
+ numerically greater value.</para>
</sect3>
<sect3 xml:id="makefile-portrevision-example">
@@ -250,7 +261,7 @@
collection:</para>
<programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10</programlisting>
+ PORTVERSION= 0.10</programlisting>
<para><varname>PKGNAME</varname> becomes
<literal>gtkmumble-0.10</literal>.</para>
@@ -260,8 +271,8 @@ PORTVERSION= 0.10</programlisting>
accordingly.</para>
<programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10
-PORTREVISION= 1</programlisting>
+ PORTVERSION= 0.10
+ PORTREVISION= 1</programlisting>
<para><varname>PKGNAME</varname> becomes
<literal>gtkmumble-0.10_1</literal></para>
@@ -270,9 +281,9 @@ PORTREVISION= 1</programlisting>
<literal>0.2</literal> (it turns out the author actually
intended <literal>0.10</literal> to actually mean
<literal>0.1.0</literal>, not <quote>what comes after
- 0.9</quote> - oops, too late now). Since the new minor
+ 0.9</quote> - oops, too late now). Since the new minor
version <literal>2</literal> is numerically less than the
- previous version <literal>10</literal>, the
+ previous version <literal>10</literal>,
<varname>PORTEPOCH</varname> must be bumped to manually
force the new package to be detected as
<quote>newer</quote>. Since it is a new vendor release of
@@ -280,8 +291,8 @@ PORTREVISION= 1</programlisting>
removed from the <filename>Makefile</filename>).</para>
<programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.2
-PORTEPOCH= 1</programlisting>
+ PORTVERSION= 0.2
+ PORTEPOCH= 1</programlisting>
<para><varname>PKGNAME</varname> becomes
<literal>gtkmumble-0.2,1</literal></para>
@@ -291,8 +302,8 @@ PORTEPOCH= 1</programlisting>
variables are now:</para>
<programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.3
-PORTEPOCH= 1</programlisting>
+ PORTVERSION= 0.3
+ PORTEPOCH= 1</programlisting>
<para><varname>PKGNAME</varname> becomes
<literal>gtkmumble-0.3,1</literal></para>
@@ -321,9 +332,10 @@ PORTEPOCH= 1</programlisting>
<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
Make sure this conforms to our
<link linkend="porting-pkgname">guidelines for a good
- package name</link>. In particular, you are
- <emphasis>not</emphasis> allowed to use a hyphen
- (<literal>-</literal>) in <varname>PORTVERSION</varname>.
+ package name</link>. In particular, the use of a
+ hyphen (<literal>-</literal>) in
+ <varname>PORTVERSION</varname> is <emphasis>not</emphasis>
+ allowed.
Also, if the package name has the
<replaceable>language-</replaceable> or the
<replaceable>-compiled.specifics</replaceable> part (see
@@ -370,8 +382,7 @@ PORTEPOCH= 1</programlisting>
French.</para>
<para>The <replaceable>language-</replaceable> part is
- set in the <varname>PKGNAMEPREFIX</varname>
- variable.</para>
+ set in <varname>PKGNAMEPREFIX</varname>.</para>
</listitem>
</varlistentry>
@@ -379,34 +390,30 @@ PORTEPOCH= 1</programlisting>
<term><filename><replaceable>name</replaceable></filename></term>
<listitem>
- <para>The first letter of the <filename>name</filename>
- part should be lowercase. (The rest of the name may
- contain capital letters, so use your own discretion when
- converting a software name that has some capital letters
- in it.) There is a tradition of naming
- <literal>Perl 5</literal> modules by prepending
- <literal>p5-</literal> and converting the double-colon
- separator to a hyphen. For example, the
- <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>.</para>
-
<para>Make sure that the port's name and version are
- clearly separated and placed into the
+ clearly separated and placed into
<varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> variables. The only
+ <varname>PORTVERSION</varname>. The only
reason for <varname>PORTNAME</varname> to contain a
version part is if the upstream distribution is really
named that way, as in the
- <filename>textproc/libxml2</filename> or
- <filename>japanese/kinput2-freewnn</filename> ports.
- Otherwise, the <varname>PORTNAME</varname> should not
+ <package role="port">textproc/libxml2</package> or
+ <package role="port">japanese/kinput2-freewnn</package> ports.
+ Otherwise, <varname>PORTNAME</varname> cannot
contain any version-specific information. It is quite
normal for several ports to have the same
<varname>PORTNAME</varname>, as the
- <filename>www/apache*</filename> ports do; in that case,
+ <package role="port">www/apache*</package> ports do; in that case,
different versions (and different index entries) are
- distinguished by the <varname>PKGNAMEPREFIX</varname>
+ distinguished by <varname>PKGNAMEPREFIX</varname>
and <varname>PKGNAMESUFFIX</varname> values.</para>
+
+ <para>There is a tradition of naming
+ <literal>Perl 5</literal> modules by prepending
+ <literal>p5-</literal> and converting the double-colon
+ separator to a hyphen. For example, the
+ <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>.</para>
</listitem>
</varlistentry>
@@ -419,13 +426,12 @@ PORTEPOCH= 1</programlisting>
(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
+ states the compiled-in defaults. The hyphen is
+ optional. Examples are paper size and font
units.</para>
<para>The <replaceable>-compiled.specifics</replaceable>
- part is set in the <varname>PKGNAMESUFFIX</varname>
- variable.</para>
+ part is set in <varname>PKGNAMESUFFIX</varname>.</para>
</listitem>
</varlistentry>
@@ -446,9 +452,9 @@ PORTEPOCH= 1</programlisting>
<quote>beta</quote>, <quote>rc</quote>, or
<quote>pre</quote>, take the first letter and put it
immediately after a period. If the version string
- continues after those names, the numbers should follow
+ continues after those names, the numbers follow
the single alphabet without an extra period between
- them.</para>
+ them (for example, <literal>1.0b2</literal>).</para>
<para>The idea is to make it easier to sort ports by
looking at the version string. In particular, make sure
@@ -461,26 +467,28 @@ PORTEPOCH= 1</programlisting>
<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
format. It is important to prefix the version with
<literal>0.0.</literal> in case a release with an actual
- version number is made, which would of course be
+ version number is made, which would be
numerically less than
<literal><replaceable>yyyy</replaceable></literal>.</para>
</listitem>
</varlistentry>
</variablelist>
- <warning>
+ <important>
<para>Package name must be unique among all of the ports
tree, check that there is not already a port with the same
<varname>PORTNAME</varname> and if there is add one of <link
linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
or <varname>PKGNAMESUFFIX</varname></link>.</para>
- </warning>
+ </important>
<para>Here are some (real) examples on how to convert the name
as called by the software authors to a suitable package
name:</para>
- <informaltable frame="none" pgwide="1">
+ <table frame="none" pgwide="1">
+ <title>Package Naming Examples</title>
+
<tgroup cols="6">
<thead>
<row>
@@ -504,6 +512,15 @@ PORTEPOCH= 1</programlisting>
</row>
<row>
+ <entry>mule-1.0.1</entry>
+ <entry>(empty)</entry>
+ <entry>mule</entry>
+ <entry>1</entry>
+ <entry>1.0.1</entry>
+ <entry><literal>mule</literal> already exists</entry>
+ </row>
+
+ <row>
<entry>EmiClock-1.0.2</entry>
<entry>(empty)</entry>
<entry>emiclock</entry>
@@ -608,14 +625,15 @@ PORTEPOCH= 1</programlisting>
</row>
</tbody>
</tgroup>
- </informaltable>
+ </table>
<para>If there is absolutely no trace of version information in
the original source and it is unlikely that the original
author will ever release another version, just set the version
string to <literal>1.0</literal> (like the
<literal>piewm</literal> example above). Otherwise, ask the
- original author or use the date string
+ original author or use the date string the source file was
+ released on
(<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
as the version.</para>
</sect2>
@@ -637,12 +655,12 @@ PORTEPOCH= 1</programlisting>
packages on the FTP site or the CDROM. Please take a look at
the <link linkend="porting-categories">current list of
categories</link> and pick the ones that are suitable for
- your port.</para>
+ the port.</para>
<para>This list also determines where in the ports tree the port
- is imported. If you put more than one category here, it is
- assumed that the port files will be put in the subdirectory
- with the name in the first category. See
+ is imported. If there is more than one category here,
+ the port files must be put in the subdirectory
+ with the name of the first category. See
<link linkend="choosing-categories">below</link> for more
discussion about how to pick the right categories.</para>
</sect2>
@@ -658,8 +676,8 @@ PORTEPOCH= 1</programlisting>
purposes.</para>
<note>
- <para>For non-virtual categories, you will find a one-line
- description in the <varname>COMMENT</varname> in that
+ <para>For non-virtual categories, there is a one-line
+ description in <varname>COMMENT</varname> in that
subdirectory's <filename>Makefile</filename>.</para>
</note>
@@ -740,7 +758,7 @@ PORTEPOCH= 1</programlisting>
<row>
<entry><filename>comms</filename></entry>
<entry>Communication software.</entry>
- <entry>Mostly software to talk to your serial
+ <entry>Mostly software to talk to the serial
port.</entry>
</row>
@@ -767,9 +785,9 @@ PORTEPOCH= 1</programlisting>
<entry><filename>devel</filename></entry>
<entry>Development utilities.</entry>
<entry>Do not put libraries here just because they are
- libraries—unless they truly do not belong
- anywhere else, they should not be in this
- category.</entry>
+ libraries. They should <emphasis>not</emphasis> be
+ in this category unless they truly do not belong
+ anywhere else.</entry>
</row>
<row>
@@ -788,8 +806,10 @@ PORTEPOCH= 1</programlisting>
<entry><filename>editors</filename></entry>
<entry>General editors.</entry>
<entry>Specialized editors go in the section for those
- tools (e.g., a mathematical-formula editor will go
- in <filename>math</filename>).</entry>
+ tools. For example, a mathematical-formula editor will
+ go in <filename>math</filename>, and have
+ <filename>editors</filename> as a second
+ category.</entry>
</row>
<row>
@@ -802,7 +822,7 @@ PORTEPOCH= 1</programlisting>
<entry><filename>emulators</filename></entry>
<entry>Emulators for other operating systems.</entry>
<entry>Terminal emulators do <emphasis>not</emphasis>
- belong here—X-based ones should go to
+ belong here. X-based ones go to
<filename>x11</filename> and text-based ones to
either <filename>comms</filename> or
<filename>misc</filename>, depending on the exact
@@ -824,8 +844,8 @@ PORTEPOCH= 1</programlisting>
<row>
<entry><filename>ftp</filename></entry>
- <entry>FTP client and server utilities.</entry>
- <entry>If your port speaks both FTP and HTTP, put it
+ <entry><acronym>FTP</acronym> client and server utilities.</entry>
+ <entry>If the port speaks both <acronym>FTP</acronym> and <acronym>HTTP</acronym>, put it
in <filename>ftp</filename> with a secondary
category of <filename>www</filename>.</entry>
</row>
@@ -984,10 +1004,10 @@ PORTEPOCH= 1</programlisting>
<row>
<entry><filename>misc</filename></entry>
<entry>Miscellaneous utilities</entry>
- <entry>Basically things that do not belong anywhere
+ <entry>Things that do not belong anywhere
else. If at all possible, try to find a better
- category for your port than <literal>misc</literal>,
- as ports tend to get overlooked in here.</entry>
+ category for the port than <literal>misc</literal>,
+ as ports tend to be overlooked in here.</entry>
</row>
<row>
@@ -1212,7 +1232,7 @@ PORTEPOCH= 1</programlisting>
<entry>The X Window System and friends.</entry>
<entry>This category is only for software that directly
supports the window system. Do not put regular X
- applications here; most of them should go into other
+ applications here. Most of them go into other
<filename>x11-*</filename> categories (see
below).</entry>
</row>
@@ -1288,9 +1308,9 @@ PORTEPOCH= 1</programlisting>
<sect2 xml:id="choosing-categories">
<title>Choosing the Right Category</title>
- <para>As many of the categories overlap, you often have to
- choose which of the categories should be the primary category
- of your port. There are several rules that govern this issue.
+ <para>As many of the categories overlap, choosing which of the
+ categories will be the primary category of the port can be
+ tedious. There are several rules that govern this issue.
Here is the list of priorities, in decreasing order of
precedence:</para>
@@ -1305,16 +1325,16 @@ PORTEPOCH= 1</programlisting>
<listitem>
<para>Language specific categories always come first. For
- example, if your port installs Japanese X11 fonts, then
- your <varname>CATEGORIES</varname> line would read
+ example, if the port installs Japanese X11 fonts, then
+ the <varname>CATEGORIES</varname> line would read
<filename>japanese x11-fonts</filename>.</para>
</listitem>
<listitem>
<para>Specific categories are listed before less-specific
- ones. For instance, an HTML editor should be listed as
+ ones. For instance, an HTML editor is listed as
<filename>www editors</filename>, not the other way
- around. Also, you should not list
+ around. Also, do not list
<filename>net</filename> when the port belongs to any of
<filename>irc</filename>, <filename>mail</filename>,
<filename>news</filename>, <filename>security</filename>,
@@ -1325,49 +1345,50 @@ PORTEPOCH= 1</programlisting>
<listitem>
<para><filename>x11</filename> is used as a secondary
category only when the primary category is a natural
- language. In particular, you should not put
+ language. In particular, do not put
<filename>x11</filename> in the category line for X
applications.</para>
</listitem>
<listitem>
- <para><application>Emacs</application> modes should be
+ <para><application>Emacs</application> modes are
placed in the same ports category as the application
supported by the mode, not in
<filename>editors</filename>. For example, an
<application>Emacs</application> mode to edit source files
- of some programming language should go into
+ of some programming language goes into
<filename>lang</filename>.</para>
</listitem>
<listitem>
- <para>Ports which install loadable kernel modules should
+ <para>Ports installing loadable kernel modules also
have the virtual category <filename>kld</filename> in
their <varname>CATEGORIES</varname> line. This is one of
the things handled automatically by adding
- <literal>kmod</literal> to the <varname>USES</varname>
- line.</para>
+ <literal>USES=kmod</literal>.</para>
</listitem>
<listitem>
- <para><filename>misc</filename> should not appear with any
- other non-virtual category. If you have
- <literal>misc</literal> with something else in your
- <varname>CATEGORIES</varname> line, that means you can
- safely delete <literal>misc</literal> and just put the
- port in that other subdirectory!</para>
+ <para><filename>misc</filename> does not appear with any
+ other non-virtual category. If there is
+ <literal>misc</literal> with something else in
+ <varname>CATEGORIES</varname>, that means
+ <literal>misc</literal> can safely be deleted and the port
+ placed only in the other subdirectory.</para>
</listitem>
<listitem>
- <para>If your port truly does not belong anywhere else,
+ <para>If the port truly does not belong anywhere else,
put it in <filename>misc</filename>.</para>
</listitem>
</itemizedlist>
- <para>If you are not sure about the category, please put a
- comment to that effect in your &man.send-pr.1; submission so
- we can discuss it before we import it. If you are a
- committer, send a note to the &a.ports; so we can discuss it
+ <para>If the category is not clearly defined, please put a
+ comment to that effect in the <link
+ xlink:href="https://bugs.freebsd.org/submit/">port
+ submission</link> in the bug database so
+ we can discuss it before we import it. As a committer,
+ send a note to the &a.ports; so we can discuss it
first. Too often, new ports are imported to the wrong
category only to be moved right away. This causes unnecessary
and undesirable bloat in the master source repository.</para>
@@ -1381,9 +1402,9 @@ PORTEPOCH= 1</programlisting>
<emphasis>virtual</emphasis> categories—those that do
not have a corresponding subdirectory in the ports tree—
or <emphasis>physical</emphasis> categories—those that
- do. The following text discusses the issues involved in
- creating a new physical category so that you can understand
- them before you propose one.</para>
+ do. This section discusses the issues involved in creating a
+ new physical category. Read it thouroughly before proposing a
+ new one.</para>
<para>Our existing practice has been to avoid creating a new
physical category unless either a large number of ports would
@@ -1407,15 +1428,15 @@ PORTEPOCH= 1</programlisting>
<procedure>
<step>
- <para>Propose the new category on &a.ports;. You should
- include a detailed rationale for the new category,
- including why you feel the existing categories are not
+ <para>Propose the new category on &a.ports;. Include
+ a detailed rationale for the new category,
+ including why the existing categories are not
sufficient, and the list of existing ports proposed to
move. (If there are new ports pending in
- <application>GNATS</application> that would fit this
+ <application>Bugzilla</application> that would fit this
category, list them too.) If you are the maintainer
and/or submitter, respectively, mention that as it may
- help you to make your case.</para>
+ help the case.</para>
</step>
<step>
@@ -1423,10 +1444,10 @@ PORTEPOCH= 1</programlisting>
</step>
<step>
- <para>If it seems that there is support for your idea, file
+ <para>If it seems that there is support for the idea, file
a PR which includes both the rationale and the list of
existing ports that need to be moved. Ideally, this PR
- should also include patches for the following:</para>
+ would also include these patches:</para>
<itemizedlist>
<listitem>
@@ -1450,7 +1471,7 @@ PORTEPOCH= 1</programlisting>
</listitem>
<listitem>
- <para>(for extra credit, you can include the other files
+ <para>(for extra credit, include the other files
that have to change, as per the procedure in the
Committer's Guide.)</para>
</listitem>
@@ -1459,9 +1480,9 @@ PORTEPOCH= 1</programlisting>
<step>
<para>Since it affects the ports infrastructure and involves
- not only performing repo-copies but also possibly running
- regression tests on the build cluster, the PR should be
- assigned to the &a.portmgr;.</para>
+ moving and patching many ports but also possibly running
+ regression tests on the build cluster, assign the PR to
+ the &a.portmgr;.</para>
</step>
<step>
@@ -1472,10 +1493,10 @@ PORTEPOCH= 1</programlisting>
</step>
</procedure>
- <para>Proposing a new virtual category should be similar to the
+ <para>Proposing a new virtual category is similar to the
above but much less involved, since no ports will actually
have to move. In this case, the only patches to include in
- the PR would be those to add the new category to the
+ the PR would be those to add the new category to
<varname>CATEGORIES</varname> of the affected ports.</para>
</sect2>
@@ -1489,8 +1510,8 @@ PORTEPOCH= 1</programlisting>
effort involved to retrofit the entire existing ports
collection with any kind of reorganization is daunting to say
the very least. Please read the history of these proposals in
- the mailing list archives before you post this idea;
- furthermore, you should be prepared to be challenged to offer
+ the mailing list archives before posting this idea.
+ Furthermore, be prepared to be challenged to offer
a working prototype.</para>
</sect2>
</sect1>
@@ -1499,8 +1520,8 @@ PORTEPOCH= 1</programlisting>
<title>The Distribution Files</title>
<para>The second part of the <filename>Makefile</filename>
- describes the files that must be downloaded in order to build
- the port, and where they can be downloaded from.</para>
+ describes the files that must be downloaded to build
+ the port, and where they can be downloaded.</para>
<sect2 xml:id="makefile-distversion">
<title><varname>DISTVERSION/DISTNAME</varname></title>
@@ -1528,9 +1549,9 @@ PORTEPOCH= 1</programlisting>
<note>
<para>Only one of <varname>PORTVERSION</varname> and
- <varname>DISTVERSION</varname> can be set at a time. If you
- set <varname>DISTVERSION</varname> and the derived
- <varname>PORTVERSION</varname> is not right, do not use
+ <varname>DISTVERSION</varname> can be set at a time. If
+ <varname>DISTVERSION</varname> does not derive a correct
+ <varname>PORTVERSION</varname>, do not use
<varname>DISTVERSION</varname>, set
<varname>PORTVERSION</varname> to the right value and set
<varname>DISTNAME</varname> with <varname>PORTNAME</varname>
@@ -1539,11 +1560,11 @@ PORTEPOCH= 1</programlisting>
version.</para>
</note>
- <para>The following table lists some examples of
- <varname>DISTVERSION</varname> and the derived
- <varname>PORTVERSION</varname>:</para>
- <informaltable frame="none" pgwide="0">
+ <table frame="none" pgwide="0">
+ <title>Examples of <varname>DISTVERSION</varname> and the
+ Derived <varname>PORTVERSION</varname></title>
+
<tgroup cols="2">
<thead>
<row>
@@ -1574,19 +1595,19 @@ PORTEPOCH= 1</programlisting>
</row>
</tbody>
</tgroup>
- </informaltable>
+ </table>
<note>
<para><varname>PKGNAMEPREFIX</varname> and
<varname>PKGNAMESUFFIX</varname> do not affect
<varname>DISTNAME</varname>. Also note that if
<varname>WRKSRC</varname> is equal to
- <filename>work/${DISTNAME}</filename> while
+ <filename>${WRKDIR}/${DISTNAME}</filename> while
the original source archive is named something other than
<literal>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</literal>,
- you should probably leave <varname>DISTNAME</varname>
- alone— you are better off defining
- <varname>DISTFILES</varname> than having to set both
+ leave <varname>DISTNAME</varname>
+ alone— defining only
+ <varname>DISTFILES</varname> is easier than both
<varname>DISTNAME</varname> and <varname>WRKSRC</varname>
(and possibly <varname>EXTRACT_SUFX</varname>).</para>
</note>
@@ -1604,7 +1625,7 @@ PORTEPOCH= 1</programlisting>
<varname>FETCH</varname> if they cannot find it already on the
system.</para>
- <para>It is recommended that you put multiple sites on this
+ <para>It is recommended that multiple sites are included on this
list, preferably from different continents. This will
safeguard against wide-area network problems. We are even
planning to add support for automatically determining the
@@ -1612,20 +1633,20 @@ PORTEPOCH= 1</programlisting>
sites will go a long way towards helping this effort.</para>
<para>If the original tarball is part of one of the popular
- archives such as SourceForge, GNU, or Perl CPAN, you may be
- able refer to those sites in an easy compact form using
- predefined macros (e.g., <literal>SF</literal>,
- <literal>GNU</literal> or <literal>CPAN</literal>). Simply
- set <varname>MASTER_SITES</varname> to one of these values.
+ archives such as SourceForge, GNU, or Perl CPAN, it may be
+ possible refer to those sites in an easy compact form using
+ predefined macros (for example, <literal>SF</literal>,
+ <literal>GNU</literal> or <literal>CPAN</literal>).
+ Set <varname>MASTER_SITES</varname> to one of these values.
Here is an example:</para>
<programlisting>MASTER_SITES= GNU/make</programlisting>
- <para>Or you can use the older expanded format, though there
- really are no reason to do so:</para>
+ <para>The older expanded format can still be used, although there
+ really is no reason to do so:</para>
<programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
-MASTER_SITE_SUBDIR= make</programlisting>
+ MASTER_SITE_SUBDIR= make</programlisting>
<para>These values and variables are defined in
<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
@@ -1635,7 +1656,7 @@ MASTER_SITE_SUBDIR= make</programlisting
<para>Several <emphasis>magic</emphasis> macros exist for
popular sites with a predictable directory structure. For
these, just use the abbreviation and the system will try to
- guess the correct subdirectory for you.</para>
+ guess the correct subdirectory automatically.</para>
<programlisting>MASTER_SITES= SF</programlisting>
@@ -1647,7 +1668,7 @@ MASTER_SITE_SUBDIR= make</programlisting
<para>This can also be written as</para>
<programlisting>MASTER_SITES= SF
-MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
+ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
<table frame="none" xml:id="makefile-master_sites-popular">
<title>Popular Magic <varname>MASTER_SITES</varname>
@@ -1828,11 +1849,11 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealP
this (slightly stripped for the example):</para>
<programlisting>PORTNAME= pkg
-PORTVERSION= 1.2.7
+ PORTVERSION= 1.2.7
-USE_GITHUB= yes
-GH_ACCOUNT= freebsd
-GH_COMMIT= f53e577</programlisting>
+ USE_GITHUB= yes
+ GH_ACCOUNT= freebsd
+ GH_COMMIT= f53e577</programlisting>
<para>It will automatically have
<varname>MASTER_SITES</varname> set to <literal>GH
@@ -1852,13 +1873,13 @@ GH_COMMIT= f53e577</programlisting>
this (slightly stripped for the example):</para>
<programlisting>PORTNAME= pkg-devel
-PORTVERSION= 1.3.0.a.20140411
+ PORTVERSION= 1.3.0.a.20140411
-USE_GITHUB= yes
-GH_ACCOUNT= freebsd
-GH_PROJECT= pkg
-GH_TAGNAME= ${GH_COMMIT}
-GH_COMMIT= 6dbb17b</programlisting>
+ USE_GITHUB= yes
+ GH_ACCOUNT= freebsd
+ GH_PROJECT= pkg
+ GH_TAGNAME= ${GH_COMMIT}
+ GH_COMMIT= 6dbb17b</programlisting>
<para>It will automatically have
<varname>MASTER_SITES</varname> set to <literal>GH
@@ -1872,16 +1893,16 @@ GH_COMMIT= 6dbb17b</programlisting>
<sect2 xml:id="makefile-extract_sufx">
<title><varname>EXTRACT_SUFX</varname></title>
- <para>If you have one distribution file, and it uses an odd
+ <para>If there is one distribution file, and it uses an odd
suffix to indicate the compression mechanism, set
<varname>EXTRACT_SUFX</varname>.</para>
<para>For example, if the distribution file was named
<filename>foo.tar.gzip</filename> instead of the more normal
- <filename>foo.tar.gz</filename>, you would write:</para>
+ <filename>foo.tar.gz</filename>, write:</para>
<programlisting>DISTNAME= foo
-EXTRACT_SUFX= .tar.gzip</programlisting>
+ EXTRACT_SUFX= .tar.gzip</programlisting>
<para>The
<literal>USES=tar[:<replaceable>xxx</replaceable>]</literal>,
@@ -1893,9 +1914,8 @@ EXTRACT_SUFX= .tar.gzip</programlisting>
<literal>.tar.gz</literal>.</para>
<note>
- <para>You never need to set both
- <varname>EXTRACT_SUFX</varname> and
- <varname>DISTFILES</varname>.</para>
+ <para>As <varname>EXTRACT_SUFX</varname> is only used in
+ <varname>DISTFILES</varname>, only set one of them..</para>
</note>
</sect2>
@@ -1929,11 +1949,11 @@ EXTRACT_SUFX= .tar.gzip</programlisting>
<varname>EXTRACT_ONLY</varname>.</para>
<programlisting>DISTFILES= source.tar.gz manual.html
-EXTRACT_ONLY= source.tar.gz</programlisting>
+ EXTRACT_ONLY= source.tar.gz</programlisting>
- <para>If <emphasis>none</emphasis> of the
- <varname>DISTFILES</varname> should be uncompressed then set
- <varname>EXTRACT_ONLY</varname> to the empty string.</para>
+ <para>When none of the <varname>DISTFILES</varname> need to be
+ uncompressed, set <varname>EXTRACT_ONLY</varname> to the empty
+ string.</para>
<programlisting>EXTRACT_ONLY=</programlisting>
</sect2>
@@ -1941,14 +1961,14 @@ EXTRACT_ONLY= source.tar.gz</programlist
<sect2 xml:id="porting-patchfiles">
<title><varname>PATCHFILES</varname></title>
- <para>If your port requires some additional patches that are
- available by FTP or HTTP, set <varname>PATCHFILES</varname> to
+ <para>If the port requires some additional patches that are
+ available by <acronym>FTP</acronym> or <acronym>HTTP</acronym>, set <varname>PATCHFILES</varname> to
the names of the files and <varname>PATCH_SITES</varname> to
the URL of the directory that contains them (the format is the
same as <varname>MASTER_SITES</varname>).</para>
<para>If the patch is not relative to the top of the source tree
- (i.e., <varname>WRKSRC</varname>) because it contains some
+ (that is, <varname>WRKSRC</varname>) because it contains some
extra pathnames, set <varname>PATCH_DIST_STRIP</varname>
accordingly. For instance, if all the pathnames in the patch
have an extra <literal>foozolix-1.0/</literal> in front of the
@@ -1961,16 +1981,16 @@ EXTRACT_ONLY= source.tar.gz</programlist
<filename>.bz2</filename> or <filename>.xz</filename>.</para>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list