diff --git a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
index b2eda54d57..71897d19c8 100644
--- a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -4,2114 +4,2087 @@
$FreeBSD$
-->
-
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="makefiles">
- <title>Configuring the Makefile</title>
-
- <para>Configuring the <filename>Makefile</filename> is pretty
- simple, and again we suggest that you look 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
- for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your 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>, <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>
-
- <para>In the worst case, you can simply create your own
- <buildtarget>do-extract</buildtarget> target to override the
- default, though this should be rarely, if ever,
- necessary.</para>
- </sect1>
-
- <sect1 xml:id="makefile-naming">
- <title>Naming</title>
-
- <para>The first part of the port's <filename>Makefile</filename>
- names the port, describes its version number, and lists it
- in the correct category.</para>
-
- <sect2>
- <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 version number of the port.</para>
- </sect2>
-
- <sect2 xml:id="makefile-naming-revepoch">
- <title><varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname></title>
-
- <sect3>
- <title><varname>PORTREVISION</varname></title>
-
- <para>The <varname>PORTREVISION</varname> variable 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
- <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>
-
- <para><varname>PORTREVISION</varname> should 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>
-
- <itemizedlist>
- <listitem>
- <para>Addition of patches to correct security
- vulnerabilities, bugs, or to add new functionality to
- the port.</para>
- </listitem>
-
- <listitem>
- <para>Changes to the port <filename>Makefile</filename>
- to enable or disable compile-time options in the
- package.</para>
- </listitem>
-
- <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>
- </listitem>
-
- <listitem>
- <para>Version bump of a port's shared library dependency
- (in this case, someone trying to install the old
- package after installing a newer version of the
- dependency will fail since it will look for the old
- libfoo.x instead of libfoo.(x+1)).</para>
- </listitem>
-
- <listitem>
- <para>Silent changes to the port distfile which have
- significant functional differences, i.e., changes to
- the distfile requiring a correction to
- <filename>distinfo</filename> with no corresponding
- change to <varname>PORTVERSION</varname>, where a
- <command>diff -ru</command> of the old and new
- versions shows non-trivial changes to the code.</para>
- </listitem>
- </itemizedlist>
-
- <para>Examples of changes which do not require a
- <varname>PORTREVISION</varname> bump:</para>
-
- <itemizedlist>
- <listitem>
- <para>Style changes to the port skeleton with no
- functional change to what appears in the resulting
- package.</para>
- </listitem>
-
- <listitem>
- <para>Changes to <varname>MASTER_SITES</varname> or
- other functional changes to the port which do not
- affect the resulting package.</para>
- </listitem>
-
- <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
- upgrading.</para>
- </listitem>
-
- <listitem>
- <para>Build fixes which cause a package to become
- 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 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, or by virtue that the new package will actually work
- at all), and 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>
- </sect3>
-
- <sect3>
- <title><varname>PORTEPOCH</varname></title>
-
- <para>From time to time a software vendor or &os; porter
- will do something silly and release a version of their
- software which is actually numerically less than the
- previous version. An example of this is a port which goes
- from foo-20000801 to foo-1.0 (the former will be
- incorrectly treated as a newer version since 20000801 is a
- numerically greater value than 1).</para>
-
- <tip>
- <para>The results of version number comparisons are not
- always obvious. <command>pkg version</command> (see
- &man.pkg-version.8;) can be used to test the comparison
- of two version number strings. For example:</para>
-
- <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
-></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.
- 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 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>
-
- <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
- 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 the release with the release date, which will cause
- problems as in the example above when a new
- <quote>official</quote> 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>
- </sect3>
-
- <sect3>
- <title>Example of <varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname> Usage</title>
-
- <para>The <literal>gtkmumble</literal> port, version
- <literal>0.10</literal>, is committed to the ports
- collection:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10</literal>.</para>
-
- <para>A security hole is discovered which requires a local
- &os; patch. <varname>PORTREVISION</varname> is bumped
- accordingly.</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10
-PORTREVISION= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10_1</literal></para>
-
- <para>A new version is released by the vendor, numbered
- <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 version <literal>2</literal> is
- numerically less than the previous version
- <literal>10</literal>, the <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 the code,
- <varname>PORTREVISION</varname> is reset to 0 (or removed
- from the <filename>Makefile</filename>).</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.2
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.2,1</literal></para>
-
- <para>The next release is 0.3. Since
- <varname>PORTEPOCH</varname> never decreases, the version
- variables are now:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.3
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.3,1</literal></para>
-
- <note>
- <para>If <varname>PORTEPOCH</varname> were reset to
- <literal>0</literal> with this upgrade, someone who had
- installed the <literal>gtkmumble-0.10_1</literal>
- package would not detect the
- <literal>gtkmumble-0.3</literal> package as newer, since
- <literal>3</literal> is still numerically less than
- <literal>10</literal>. Remember, this is the whole
- point of <varname>PORTEPOCH</varname> in the first
- place.</para>
- </note>
- </sect3>
- </sect2>
-
- <sect2>
- <title><varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname></title>
-
- <para>Two optional variables, <varname>PKGNAMEPREFIX</varname>
- and <varname>PKGNAMESUFFIX</varname>, are combined with
- <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> to form
- <varname>PKGNAME</varname> as
- <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>.
- Also, if the package name has the
- <replaceable>language-</replaceable> or the
- <replaceable>-compiled.specifics</replaceable> part (see
- below), use <varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname>, respectively. Do not make
- them part of <varname>PORTNAME</varname>.</para>
- </sect2>
-
- <sect2 xml:id="porting-pkgname">
- <title>Package Naming Conventions</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already thousands of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like
- <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para>
-
- <para>The package name is defined as
- <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
- Make sure to set the variables to conform to that
- format.</para>
-
- <orderedlist>
- <listitem>
- <para>&os; strives to support the native language of
- its users. The <replaceable>language-</replaceable>
- part should be a two letter abbreviation of the natural
- language defined by ISO-639 if the port is specific to a
- certain language. Examples are <literal>ja</literal>
- for Japanese, <literal>ru</literal> for Russian,
- <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal>
- for Korean and <literal>de</literal> for German.</para>
-
- <para>If the port is specific to a certain region within
- the language area, add the two letter country code as
- well. Examples are <literal>en_US</literal> for US
- English and <literal>fr_CH</literal> for Swiss
- French.</para>
-
- <para>The <replaceable>language-</replaceable> part should
- be set in the <varname>PKGNAMEPREFIX</varname>
- variable.</para>
- </listitem>
-
- <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
- you are 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>
- </listitem>
-
- <listitem>
- <para>Make sure that the port's name and version are
- clearly separated and placed into the
- <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> variables. 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
- 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,
- different versions (and different index entries) are
- distinguished by the <varname>PKGNAMEPREFIX</varname>
- and <varname>PKGNAMESUFFIX</varname> values.</para>
- </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
- <replaceable>-compiled.specifics</replaceable> part
- should state the compiled-in defaults (the hyphen is
- optional). Examples are paper size and font
- units.</para>
-
- <para>The <replaceable>-compiled.specifics</replaceable>
- part should be set in the
- <varname>PKGNAMESUFFIX</varname> variable.</para>
- </listitem>
-
- <listitem>
- <para>The version string should follow a dash
- (<literal>-</literal>) and be a period-separated list of
- integers and single lowercase alphabetics. In
- particular, it is not permissible to have another dash
- inside the version string. The only exception is the
- string <literal>pl</literal> (meaning
- <quote>patchlevel</quote>), which can be used
- <emphasis>only</emphasis> when there are no major and
- minor version numbers in the software. If the software
- version has strings like <quote>alpha</quote>,
- <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
- the single alphabet without an extra period between
- them.</para>
-
- <para>The idea is to make it easier to sort ports by
- looking at the version string. In particular, make sure
- version number components are always delimited by a
- period, and if the date is part of the string, use the
- <literal>0.0.yyyy.mm.dd</literal>
- format, not
- <literal>dd.mm.yyyy</literal>
- or the non-Y2K compliant
- <literal>yy.mm.dd</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
- numerically less than
- <literal>yyyy</literal>.</para>
- </listitem>
- </orderedlist>
-
- <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">
- <tgroup cols="6">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry><varname>PKGNAMEPREFIX</varname></entry>
- <entry><varname>PORTNAME</varname></entry>
- <entry><varname>PKGNAMESUFFIX</varname></entry>
- <entry><varname>PORTVERSION</varname></entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2</entry>
- <entry>(empty)</entry>
- <entry>mule</entry>
- <entry>(empty)</entry>
- <entry>2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>(empty)</entry>
- <entry>emiclock</entry>
- <entry>(empty)</entry>
- <entry>1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>(empty)</entry>
- <entry>rdist</entry>
- <entry>(empty)</entry>
- <entry>1.3.a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>(empty)</entry>
- <entry>es</entry>
- <entry>(empty)</entry>
- <entry>0.9.b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>mailman-2.0rc3</entry>
- <entry>(empty)</entry>
- <entry>mailman</entry>
- <entry>(empty)</entry>
- <entry>2.0.r3</entry>
- <entry>No strings like <literal>rc</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>(empty)</entry>
- <entry>tiff</entry>
- <entry>(empty)</entry>
- <entry>3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>(empty)</entry>
- <entry>tvtwm</entry>
- <entry>(empty)</entry>
- <entry>pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>(empty)</entry>
- <entry>piewm</entry>
- <entry>(empty)</entry>
- <entry>1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>(empty)</entry>
- <entry>xvgr</entry>
- <entry>(empty)</entry>
- <entry>2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-</entry>
- <entry>gawk</entry>
- <entry>(empty)</entry>
- <entry>2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>(empty)</entry>
- <entry>psutils</entry>
- <entry>-letter</entry>
- <entry>1.13</entry>
- <entry>Paper size hardcoded at package build
- time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>(empty)</entry>
- <entry>pkfonts</entry>
- <entry>300</entry>
- <entry>1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <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
- (<literal>0.0.yyyy.mm.dd</literal>)
- as the version.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="makefile-categories">
- <title>Categorization</title>
-
- <sect2>
- <title><varname>CATEGORIES</varname></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of
- these subdirectories are specified by the variable
- <varname>CATEGORIES</varname>. It is intended to make life
- easier for the user when he is wading through the pile of
- 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>
-
- <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
- <link linkend="choosing-categories">below</link> for more
- discussion about how to pick the right categories.</para>
- </sect2>
-
- <sect2 xml:id="porting-categories">
- <title>Current List of Categories</title>
-
- <para>Here is the current list of port categories. Those
- marked with an asterisk (<literal>*</literal>) are
- <emphasis>virtual</emphasis> categories—those that do
- not have a corresponding subdirectory in the ports tree.
- They are only used as secondary categories, and only for
- search purposes.</para>
-
- <note>
- <para>For non-virtual categories, you will find a one-line
- description in the <varname>COMMENT</varname> in that
- subdirectory's <filename>Makefile</filename>.</para>
- </note>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Category</entry>
- <entry>Description</entry>
- <entry>Notes</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><filename>accessibility</filename></entry>
- <entry>Ports to help disabled users.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>afterstep*</filename></entry>
-
- <entry>Ports to support the <link
- xlink:href="http://www.afterstep.org">AfterStep</link>
- window manager.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>arabic</filename></entry>
- <entry>Arabic language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>archivers</filename></entry>
- <entry>Archiving tools.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>astro</filename></entry>
- <entry>Astronomical ports.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>audio</filename></entry>
- <entry>Sound support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>benchmarks</filename></entry>
- <entry>Benchmarking utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>biology</filename></entry>
- <entry>Biology-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>cad</filename></entry>
- <entry>Computer aided design tools.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>chinese</filename></entry>
- <entry>Chinese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>comms</filename></entry>
- <entry>Communication software.</entry>
- <entry>Mostly software to talk to your serial
- port.</entry>
- </row>
-
- <row>
- <entry><filename>converters</filename></entry>
- <entry>Character code converters.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>databases</filename></entry>
- <entry>Databases.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>deskutils</filename></entry>
- <entry>Things that used to be on the desktop before
- computers were invented.</entry>
- <entry/>
- </row>
-
- <row>
- <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>
- </row>
-
- <row>
- <entry><filename>dns</filename></entry>
- <entry>DNS-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>docs*</filename></entry>
- <entry>Meta-ports for &os; documentation.</entry>
- <entry/>
- </row>
-
- <row>
- <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>
- </row>
-
- <row>
- <entry><filename>elisp*</filename></entry>
- <entry>Emacs-lisp ports.</entry>
- <entry/>
- </row>
-
- <row>
- <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
- <filename>x11</filename> and text-based ones to
- either <filename>comms</filename> or
- <filename>misc</filename>, depending on the exact
- functionality.</entry>
- </row>
-
- <row>
- <entry><filename>finance</filename></entry>
- <entry>Monetary, financial and related
- applications.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>french</filename></entry>
- <entry>French language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ftp</filename></entry>
- <entry>FTP client and server utilities.</entry>
- <entry>If your port speaks both FTP and HTTP, put it
- in <filename>ftp</filename> with a secondary
- category of <filename>www</filename>.</entry>
- </row>
-
- <row>
- <entry><filename>games</filename></entry>
- <entry>Games.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>geography*</filename></entry>
- <entry>Geography-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>german</filename></entry>
- <entry>German language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>gnome*</filename></entry>
- <entry>Ports from the
- <link xlink:href="http://www.gnome.org">GNOME</link>
- Project.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>gnustep*</filename></entry>
- <entry>Software related to the GNUstep desktop
- environment.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>graphics</filename></entry>
- <entry>Graphics utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hamradio*</filename></entry>
- <entry>Software for amateur radio.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>haskell*</filename></entry>
- <entry>Software related to the Haskell
- language.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hebrew</filename></entry>
- <entry>Hebrew language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hungarian</filename></entry>
- <entry>Hungarian language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ipv6*</filename></entry>
- <entry>IPv6 related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>irc</filename></entry>
- <entry>Internet Relay Chat utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>japanese</filename></entry>
- <entry>Japanese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>java</filename></entry>
- <entry>Software related to the Java™
- language.</entry>
- <entry>The <filename>java</filename> category must
- not be the only one for a port. Save for ports
- directly related to the Java language, porters are
- also encouraged not to use <filename>java</filename>
- as the main category of a port.</entry>
- </row>
-
- <row>
- <entry><filename>kde*</filename></entry>
- <entry>Ports from the
- <link xlink:href="http://www.kde.org">KDE</link>
- Project.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>kld*</filename></entry>
- <entry>Kernel loadable modules.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>korean</filename></entry>
- <entry>Korean language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>lang</filename></entry>
- <entry>Programming languages.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>linux*</filename></entry>
- <entry>Linux applications and support
- utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>lisp*</filename></entry>
- <entry>Software related to the Lisp language.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>mail</filename></entry>
- <entry>Mail software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>math</filename></entry>
- <entry>Numerical computation software and other
- utilities for mathematics.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>mbone*</filename></entry>
- <entry>MBone applications.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>misc</filename></entry>
- <entry>Miscellaneous utilities</entry>
- <entry>Basically 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>
- </row>
-
- <row>
- <entry><filename>multimedia</filename></entry>
- <entry>Multimedia software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>net</filename></entry>
- <entry>Miscellaneous networking software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>net-im</filename></entry>
- <entry>Instant messaging software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>net-mgmt</filename></entry>
- <entry>Networking management software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>net-p2p</filename></entry>
- <entry>Peer to peer network applications.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>news</filename></entry>
- <entry>USENET news software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>palm</filename></entry>
-
- <entry>Software support for the <link
- xlink:href="http://www.palm.com/">Palm™</link>
- series.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>parallel*</filename></entry>
- <entry>Applications dealing with parallelism in
- computing.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>pear*</filename></entry>
- <entry>Ports related to the Pear PHP
- framework.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>perl5*</filename></entry>
- <entry>Ports that require
- <application>Perl</application> version 5 to
- run.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>plan9*</filename></entry>
-
- <entry>Various programs from <link
- xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>polish</filename></entry>
- <entry>Polish language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ports-mgmt</filename></entry>
- <entry>Ports for managing, installing and developing
- &os; ports and packages.</entry>
- </row>
-
- <row>
- <entry><filename>portuguese</filename></entry>
- <entry>Portuguese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>print</filename></entry>
- <entry>Printing software.</entry>
- <entry>Desktop publishing tools
- (previewers, etc.) belong here too.</entry>
- </row>
-
- <row>
- <entry><filename>python*</filename></entry>
-
- <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>
- language.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>rubygems*</filename></entry>
-
- <entry>Ports of <link
- xlink:href="http://www.rubygems.org/">RubyGems</link>
- packages.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>russian</filename></entry>
- <entry>Russian language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>scheme*</filename></entry>
- <entry>Software related to the Scheme
- language.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>science</filename></entry>
- <entry>Scientific ports that do not fit into other
- categories such as <filename>astro</filename>,
- <filename>biology</filename> and
- <filename>math</filename>.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>security</filename></entry>
- <entry>Security utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>shells</filename></entry>
- <entry>Command line shells.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>spanish*</filename></entry>
- <entry>Spanish language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>sysutils</filename></entry>
- <entry>System utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>tcl*</filename></entry>
- <entry>Ports that use Tcl to run.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>textproc</filename></entry>
- <entry>Text processing utilities.</entry>
- <entry>It does not include desktop publishing tools,
- which go to <filename>print</filename>.</entry>
- </row>
-
- <row>
- <entry><filename>tk*</filename></entry>
- <entry>Ports that use Tk to run.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ukrainian</filename></entry>
- <entry>Ukrainian language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>vietnamese</filename></entry>
- <entry>Vietnamese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>windowmaker*</filename></entry>
- <entry>Ports to support the WindowMaker window
- manager.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>www</filename></entry>
- <entry>Software related to the World Wide Web.</entry>
- <entry>HTML language
- support belongs here too.</entry>
- </row>
-
- <row>
- <entry><filename>x11</filename></entry>
- <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 <filename>x11-*</filename> categories
- (see below).</entry>
- </row>
-
- <row>
- <entry><filename>x11-clocks</filename></entry>
- <entry>X11 clocks.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-drivers</filename></entry>
- <entry>X11 drivers.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-fm</filename></entry>
- <entry>X11 file managers.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-fonts</filename></entry>
- <entry>X11 fonts and font utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-servers</filename></entry>
- <entry>X11 servers.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-themes</filename></entry>
- <entry>X11 themes.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-toolkits</filename></entry>
- <entry>X11 toolkits.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>x11-wm</filename></entry>
- <entry>X11 window managers.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>xfce*</filename></entry>
- <entry>Ports related to the
- <link xlink:href="http://www.xfce.org/">Xfce</link>
- desktop environment.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>zope*</filename></entry>
- <entry><link
- xlink:href="http://www.zope.org/">Zope</link>
- support.</entry>
- <entry/>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect2>
-
- <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. Here is the list of priorities, in decreasing
- order of precedence:</para>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="makefiles">
+
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the <filename>Makefile</filename> is pretty
+ simple, and again we suggest that you look 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
+ for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your 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>,
+ <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>
+
+ <para>In the worst case, you can simply create your own
+ <buildtarget>do-extract</buildtarget> target to override the
+ default, though this should be rarely, if ever,
+ necessary.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-naming">
+ <title>Naming</title>
+
+ <para>The first part of the port's <filename>Makefile</filename>
+ names the port, describes its version number, and lists it in
+ the correct category.</para>
+
+ <sect2>
+ <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
+ version number of the port.</para>
+ </sect2>
+
+ <sect2 xml:id="makefile-naming-revepoch">
+ <title><varname>PORTREVISION</varname> and
+ <varname>PORTEPOCH</varname></title>
+
+ <sect3>
+ <title><varname>PORTREVISION</varname></title>
+
+ <para>The <varname>PORTREVISION</varname> variable 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
+ <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>
+
+ <para><varname>PORTREVISION</varname> should 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>
<itemizedlist>
<listitem>
- <para>The first category must be a physical category (see
- <link linkend="porting-categories">above</link>). This
- is necessary to make the packaging work. Virtual
- categories and physical categories may be intermixed
- after that.</para>
+ <para>Addition of patches to correct security
+ vulnerabilities, bugs, or to add new functionality to
+ the port.</para>
</listitem>
<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
- <filename>japanese x11-fonts</filename>.</para>
+ <para>Changes to the port <filename>Makefile</filename> to
+ enable or disable compile-time options in the
+ package.</para>
</listitem>
<listitem>
- <para>Specific categories are listed before less-specific
- ones. For instance, an HTML editor should be listed as
- <filename>www editors</filename>, not the other way
- around. Also, you should not list
- <filename>net</filename> when the port belongs to any of
- <filename>irc</filename>, <filename>mail</filename>,
- <filename>news</filename>,
- <filename>security</filename>, or
- <filename>www</filename>, as <filename>net</filename> is
- included implicitly.</para>
+ <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>
</listitem>
<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
- <filename>x11</filename> in the category line for X
- applications.</para>
+ <para>Version bump of a port's shared library dependency
+ (in this case, someone trying to install the old package
+ after installing a newer version of the dependency will
+ fail since it will look for the old libfoo.x instead of
+ libfoo.(x+1)).</para>
</listitem>
<listitem>
- <para><application>Emacs</application> modes should be
- 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
- <filename>lang</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Ports which install loadable kernel modules should
- 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>
- </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>
- </listitem>
-
- <listitem>
- <para>If your port truly does not belong anywhere else,
- put it in <filename>misc</filename>.</para>
+ <para>Silent changes to the port distfile which have
+ significant functional differences, i.e., changes to the
+ distfile requiring a correction to
+ <filename>distinfo</filename> with no corresponding
+ change to <varname>PORTVERSION</varname>, where a
+ <command>diff -ru</command> of the old and new versions
+ shows non-trivial changes to the code.</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
- 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>
- </sect2>
+ <para>Examples of changes which do not require a
+ <varname>PORTREVISION</varname> bump:</para>
- <sect2 xml:id="proposing-categories">
- <title>Proposing a New Category</title>
+ <itemizedlist>
+ <listitem>
+ <para>Style changes to the port skeleton with no
+ functional change to what appears in the resulting
+ package.</para>
+ </listitem>
- <para>As the Ports Collection has grown over time, various new
- categories have been introduced. New categories can either
- be <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>
+ <listitem>
+ <para>Changes to <varname>MASTER_SITES</varname> or other
+ functional changes to the port which do not affect the
+ resulting package.</para>
+ </listitem>
- <para>Our existing practice has been to avoid creating a new
- physical category unless either a large number of ports
- would logically belong to it, or the ports that would belong
- to it are a logically distinct group that is of limited
- general interest (for instance, categories related to spoken
- human languages), or preferably both.</para>
+ <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
+ upgrading.</para>
+ </listitem>
- <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
- 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>
+ <listitem>
+ <para>Build fixes which cause a package to become
+ 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
+ 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>Here is the procedure:</para>
+ <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,
+ or by virtue that the new package will actually work at
+ all), and 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>
+ </sect3>
- <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
- sufficient, and the list of existing ports proposed to
- move. (If there are new ports pending in
- <application>GNATS</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>
- </step>
+ <sect3>
+ <title><varname>PORTEPOCH</varname></title>
- <step>
- <para>Participate in the discussion.</para>
- </step>
+ <para>From time to time a software vendor or &os; porter will
+ do something silly and release a version of their software
+ which is actually numerically less than the previous
+ version. An example of this is a port which goes from
+ foo-20000801 to foo-1.0 (the former will be incorrectly
+ treated as a newer version since 20000801 is a numerically
+ greater value than 1).</para>
- <step>
- <para>If it seems that there is support for your 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>
+ <tip>
+ <para>The results of version number comparisons are not
+ always obvious. <command>pkg version</command> (see
+ &man.pkg-version.8;) can be used to test the comparison of
+ two version number strings. For example:</para>
- <itemizedlist>
- <listitem>
- <para><filename>Makefile</filename>s for the
- new ports once they are repocopied</para>
- </listitem>
+ <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
+></screen>
- <listitem>
- <para><filename>Makefile</filename> for the
- new category</para>
- </listitem>
+ <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>
- <listitem>
- <para><filename>Makefile</filename> for the
- old ports' categories</para>
- </listitem>
+ <para>In situations such as this, the
+ <varname>PORTEPOCH</varname> version should 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
+ specially by automated tools and found to be greater than
+ the implied suffix <literal>,0</literal> on the earlier
+ package.</para>
- <listitem>
- <para><filename>Makefile</filename>s for ports
- that depend on the old ports</para>
- </listitem>
+ <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>
- <listitem>
- <para>(for extra credit, you can include the other
- files that have to change, as per the procedure
- in the Committer's Guide.)</para>
- </listitem>
- </itemizedlist>
- </step>
+ <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
+ 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
+ the release with the release date, which will cause problems
+ as in the example above when a new <quote>official</quote>
+ release is made.</para>
- <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>
- </step>
+ <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>
+ </sect3>
- <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>
- </step>
- </procedure>
+ <sect3>
+ <title>Example of <varname>PORTREVISION</varname> and
+ <varname>PORTEPOCH</varname> Usage</title>
- <para>Proposing a new virtual category should be 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 <varname>CATEGORIES</varname> of the affected
- ports.</para>
- </sect2>
+ <para>The <literal>gtkmumble</literal> port, version
+ <literal>0.10</literal>, is committed to the ports
+ collection:</para>
- <sect2 xml:id="proposing-reorg">
- <title>Proposing Reorganizing All the Categories</title>
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.10</programlisting>
- <para>Occasionally someone proposes reorganizing the
- categories with either a 2-level structure, or some other
- kind of keyword structure. To date, nothing has come of any
- of these proposals because, while they are very easy to
- make, the 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 a working prototype.</para>
- </sect2>
- </sect1>
+ <para><varname>PKGNAME</varname> becomes
+ <literal>gtkmumble-0.10</literal>.</para>
- <sect1 xml:id="makefile-distfiles">
- <title>The Distribution Files</title>
+ <para>A security hole is discovered which requires a local
+ &os; patch. <varname>PORTREVISION</varname> is bumped
+ accordingly.</para>
- <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>
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.10
+PORTREVISION= 1</programlisting>
- <sect2>
- <title><varname>DISTVERSION/DISTNAME</varname></title>
+ <para><varname>PKGNAME</varname> becomes
+ <literal>gtkmumble-0.10_1</literal></para>
- <para><varname>DISTNAME</varname> is the name of the port as
- called by the authors of the software.
- <varname>DISTNAME</varname> defaults to
- <literal>${PORTNAME}-${PORTVERSION}</literal>, so override
- it only if necessary. <varname>DISTNAME</varname> is only
- used in two places. First, the distribution file list
- (<varname>DISTFILES</varname>) defaults to
- <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>.
- Second, the distribution file is expected to extract into a
- subdirectory named <varname>WRKSRC</varname>, which defaults
- to
- <filename>work/${DISTNAME}</filename>.</para>
+ <para>A new version is released by the vendor, numbered
+ <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
+ version <literal>2</literal> is numerically less than the
+ previous version <literal>10</literal>, the
+ <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
+ the code, <varname>PORTREVISION</varname> is reset to 0 (or
+ removed from the <filename>Makefile</filename>).</para>
- <para>Some vendor's distribution names which do not fit into
- the <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can
- be handled automatically by setting
- <varname>DISTVERSION</varname>.
- <varname>PORTVERSION</varname> and
- <varname>DISTNAME</varname> will be derived automatically,
- but can of course be overridden. The following table lists
- some examples:</para>
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.2
+PORTEPOCH= 1</programlisting>
- <informaltable frame="none" pgwide="0">
- <tgroup cols="2">
- <thead>
- <row>
- <entry><varname>DISTVERSION</varname></entry>
- <entry><varname>PORTVERSION</varname></entry>
- </row>
- </thead>
+ <para><varname>PKGNAME</varname> becomes
+ <literal>gtkmumble-0.2,1</literal></para>
- <tbody>
- <row>
- <entry>0.7.1d</entry>
- <entry>0.7.1.d</entry>
- </row>
+ <para>The next release is 0.3. Since
+ <varname>PORTEPOCH</varname> never decreases, the version
+ variables are now:</para>
- <row>
- <entry>10Alpha3</entry>
- <entry>10.a3</entry>
- </row>
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.3
+PORTEPOCH= 1</programlisting>
- <row>
- <entry>3Beta7-pre2</entry>
- <entry>3.b7.p2</entry>
- </row>
-
- <row>
- <entry>8:f_17</entry>
- <entry>8f.17</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <para><varname>PKGNAME</varname> becomes
+ <literal>gtkmumble-0.3,1</literal></para>
<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/${PORTNAME}-${PORTVERSION}</filename>
- while the original source archive is named something other
- than
- <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>,
- you should probably leave <varname>DISTNAME</varname>
- alone— you are better off defining
- <varname>DISTFILES</varname> than having to set both
- <varname>DISTNAME</varname> and <varname>WRKSRC</varname>
- (and possibly <varname>EXTRACT_SUFX</varname>).</para>
+ <para>If <varname>PORTEPOCH</varname> were reset to
+ <literal>0</literal> with this upgrade, someone who had
+ installed the <literal>gtkmumble-0.10_1</literal> package
+ would not detect the <literal>gtkmumble-0.3</literal>
+ package as newer, since <literal>3</literal> is still
+ numerically less than <literal>10</literal>. Remember,
+ this is the whole point of <varname>PORTEPOCH</varname> in
+ the first place.</para>
</note>
- </sect2>
+ </sect3>
+ </sect2>
- <sect2>
- <title><varname>MASTER_SITES</varname></title>
+ <sect2>
+ <title><varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname></title>
- <para>Record the directory part of the FTP/HTTP-URL pointing
- at the original tarball in <varname>MASTER_SITES</varname>.
- Do not forget the trailing slash
- (<filename>/</filename>)!</para>
+ <para>Two optional variables, <varname>PKGNAMEPREFIX</varname>
+ and <varname>PKGNAMESUFFIX</varname>, are combined with
+ <varname>PORTNAME</varname> and <varname>PORTVERSION</varname>
+ to form <varname>PKGNAME</varname> as
+ <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>.
+ Also, if the package name has the
+ <replaceable>language-</replaceable> or the
+ <replaceable>-compiled.specifics</replaceable> part (see
+ below), use <varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname>, respectively. Do not make
+ them part of <varname>PORTNAME</varname>.</para>
+ </sect2>
- <para>The <command>make</command> macros will try to use this
- specification for grabbing the distribution file with
- <varname>FETCH</varname> if they cannot find it already on
- the system.</para>
+ <sect2 xml:id="porting-pkgname">
+ <title>Package Naming Conventions</title>
- <para>It is recommended that you put multiple sites 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
- closest master site and fetching from there; having multiple
- sites will go a long way towards helping this effort.</para>
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already thousands of packages and
+ users are going to turn away if they hurt their eyes!</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
- <varname>MASTER_SITE_<replaceable>*</replaceable></varname>
- (e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>,
- <varname>MASTER_SITE_GNU</varname> and
- <varname>MASTER_SITE_PERL_CPAN</varname>). Simply set
- <varname>MASTER_SITES</varname> to one of these variables
- and <varname>MASTER_SITE_SUBDIR</varname> to the path within
- the archive. Here is an example:</para>
+ <para>The package name should look like
+ <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para>
- <programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
+ <para>The package name is defined as
+ <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
+ Make sure to set the variables to conform to that
+ format.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>&os; strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part
+ should be a two letter abbreviation of the natural
+ language defined by ISO-639 if the port is specific to a
+ certain language. Examples are <literal>ja</literal> for
+ Japanese, <literal>ru</literal> for Russian,
+ <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal>
+ for Korean and <literal>de</literal> for German.</para>
+
+ <para>If the port is specific to a certain region within the
+ language area, add the two letter country code as well.
+ Examples are <literal>en_US</literal> for US English and
+ <literal>fr_CH</literal> for Swiss French.</para>
+
+ <para>The <replaceable>language-</replaceable> part should
+ be set in the <varname>PKGNAMEPREFIX</varname>
+ variable.</para>
+ </listitem>
+
+ <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 you are
+ 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>
+ </listitem>
+
+ <listitem>
+ <para>Make sure that the port's name and version are clearly
+ separated and placed into the <varname>PORTNAME</varname>
+ and <varname>PORTVERSION</varname> variables. 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
+ 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,
+ different versions (and different index entries) are
+ distinguished by the <varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname> values.</para>
+ </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
+ <replaceable>-compiled.specifics</replaceable> part should
+ state the compiled-in defaults (the hyphen is optional).
+ Examples are paper size and font units.</para>
+
+ <para>The <replaceable>-compiled.specifics</replaceable>
+ part should be set in the <varname>PKGNAMESUFFIX</varname>
+ variable.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should follow a dash
+ (<literal>-</literal>) and be a period-separated list of
+ integers and single lowercase alphabetics. In particular,
+ it is not permissible to have another dash inside the
+ version string. The only exception is the string
+ <literal>pl</literal> (meaning <quote>patchlevel</quote>),
+ which can be used <emphasis>only</emphasis> when there are
+ no major and minor version numbers in the software. If
+ the software version has strings like
+ <quote>alpha</quote>, <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 the single alphabet without an extra period
+ between them.</para>
+
+ <para>The idea is to make it easier to sort ports by looking
+ at the version string. In particular, make sure version
+ number components are always delimited by a period, and if
+ the date is part of the string, use the
+ <literal>0.0.yyyy.mm.dd</literal> format, not
+ <literal>dd.mm.yyyy</literal> or the non-Y2K compliant
+ <literal>yy.mm.dd</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 numerically less than
+ <literal>yyyy</literal>.</para>
+ </listitem>
+ </orderedlist>
+
+ <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">
+ <tgroup cols="6">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry><varname>PKGNAMEPREFIX</varname></entry>
+ <entry><varname>PORTNAME</varname></entry>
+ <entry><varname>PKGNAMESUFFIX</varname></entry>
+ <entry><varname>PORTVERSION</varname></entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2</entry>
+ <entry>(empty)</entry>
+ <entry>mule</entry>
+ <entry>(empty)</entry>
+ <entry>2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>(empty)</entry>
+ <entry>emiclock</entry>
+ <entry>(empty)</entry>
+ <entry>1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>(empty)</entry>
+ <entry>rdist</entry>
+ <entry>(empty)</entry>
+ <entry>1.3.a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>(empty)</entry>
+ <entry>es</entry>
+ <entry>(empty)</entry>
+ <entry>0.9.b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>mailman-2.0rc3</entry>
+ <entry>(empty)</entry>
+ <entry>mailman</entry>
+ <entry>(empty)</entry>
+ <entry>2.0.r3</entry>
+ <entry>No strings like <literal>rc</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>(empty)</entry>
+ <entry>tiff</entry>
+ <entry>(empty)</entry>
+ <entry>3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>(empty)</entry>
+ <entry>tvtwm</entry>
+ <entry>(empty)</entry>
+ <entry>pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>(empty)</entry>
+ <entry>piewm</entry>
+ <entry>(empty)</entry>
+ <entry>1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>(empty)</entry>
+ <entry>xvgr</entry>
+ <entry>(empty)</entry>
+ <entry>2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-</entry>
+ <entry>gawk</entry>
+ <entry>(empty)</entry>
+ <entry>2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>(empty)</entry>
+ <entry>psutils</entry>
+ <entry>-letter</entry>
+ <entry>1.13</entry>
+ <entry>Paper size hardcoded at package build
+ time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>(empty)</entry>
+ <entry>pkfonts</entry>
+ <entry>300</entry>
+ <entry>1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <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
+ (<literal>0.0.yyyy.mm.dd</literal>) as the version.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="makefile-categories">
+ <title>Categorization</title>
+
+ <sect2>
+ <title><varname>CATEGORIES</varname></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable
+ <varname>CATEGORIES</varname>. It is intended to make life
+ easier for the user when he is wading through the pile of
+ 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>
+
+ <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
+ <link linkend="choosing-categories">below</link> for more
+ discussion about how to pick the right categories.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-categories">
+ <title>Current List of Categories</title>
+
+ <para>Here is the current list of port categories. Those marked
+ with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do
+ not have a corresponding subdirectory in the ports tree. They
+ are only used as secondary categories, and only for search
+ purposes.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <varname>COMMENT</varname> in that
+ subdirectory's <filename>Makefile</filename>.</para>
+ </note>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ <entry>Notes</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>accessibility</filename></entry>
+ <entry>Ports to help disabled users.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>afterstep*</filename></entry>
+
+ <entry>Ports to support the <link
+ xlink:href="http://www.afterstep.org">AfterStep</link>
+ window manager.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>arabic</filename></entry>
+ <entry>Arabic language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software.</entry>
+ <entry>Mostly software to talk to your serial
+ port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <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>
+ </row>
+
+ <row>
+ <entry><filename>dns</filename></entry>
+ <entry>DNS-related software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>docs*</filename></entry>
+ <entry>Meta-ports for &os; documentation.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <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>
+ </row>
+
+ <row>
+ <entry><filename>elisp*</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <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
+ <filename>x11</filename> and text-based ones to
+ either <filename>comms</filename> or
+ <filename>misc</filename>, depending on the exact
+ functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>finance</filename></entry>
+ <entry>Monetary, financial and related
+ applications.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>french</filename></entry>
+ <entry>French language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ftp</filename></entry>
+ <entry>FTP client and server utilities.</entry>
+ <entry>If your port speaks both FTP and HTTP, put it
+ in <filename>ftp</filename> with a secondary
+ category of <filename>www</filename>.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>geography*</filename></entry>
+ <entry>Geography-related software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>gnome*</filename></entry>
+ <entry>Ports from the
+ <link xlink:href="http://www.gnome.org">GNOME</link>
+ Project.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>gnustep*</filename></entry>
+ <entry>Software related to the GNUstep desktop
+ environment.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>hamradio*</filename></entry>
+ <entry>Software for amateur radio.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>haskell*</filename></entry>
+ <entry>Software related to the Haskell
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>hebrew</filename></entry>
+ <entry>Hebrew language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>hungarian</filename></entry>
+ <entry>Hungarian language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ipv6*</filename></entry>
+ <entry>IPv6 related software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>irc</filename></entry>
+ <entry>Internet Relay Chat utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>java</filename></entry>
+ <entry>Software related to the Java™
+ language.</entry>
+ <entry>The <filename>java</filename> category must not
+ be the only one for a port. Save for ports directly
+ related to the Java language, porters are also
+ encouraged not to use <filename>java</filename> as the
+ main category of a port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports from the
+ <link xlink:href="http://www.kde.org">KDE</link>
+ Project.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>kld*</filename></entry>
+ <entry>Kernel loadable modules.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>linux*</filename></entry>
+ <entry>Linux applications and support
+ utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>lisp*</filename></entry>
+ <entry>Software related to the Lisp language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other
+ utilities for mathematics.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>mbone*</filename></entry>
+ <entry>MBone applications.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities</entry>
+ <entry>Basically 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>
+ </row>
+
+ <row>
+ <entry><filename>multimedia</filename></entry>
+ <entry>Multimedia software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>net-im</filename></entry>
+ <entry>Instant messaging software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>net-mgmt</filename></entry>
+ <entry>Networking management software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>net-p2p</filename></entry>
+ <entry>Peer to peer network applications.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>palm</filename></entry>
+
+ <entry>Software support for the <link
+ xlink:href="http://www.palm.com/">Palm™</link>
+ series.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>parallel*</filename></entry>
+ <entry>Applications dealing with parallelism in
+ computing.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>pear*</filename></entry>
+ <entry>Ports related to the Pear PHP
+ framework.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require
+ <application>Perl</application> version 5 to
+ run.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>plan9*</filename></entry>
+
+ <entry>Various programs from <link
+ xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>polish</filename></entry>
+ <entry>Polish language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ports-mgmt</filename></entry>
+ <entry>Ports for managing, installing and developing
+ &os; ports and packages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>portuguese</filename></entry>
+ <entry>Portuguese language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software.</entry>
+ <entry>Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+
+ <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>
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>rubygems*</filename></entry>
+
+ <entry>Ports of <link
+ xlink:href="http://www.rubygems.org/">RubyGems</link>
+ packages.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>scheme*</filename></entry>
+ <entry>Software related to the Scheme
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>science</filename></entry>
+ <entry>Scientific ports that do not fit into other
+ categories such as <filename>astro</filename>,
+ <filename>biology</filename> and
+ <filename>math</filename>.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>spanish*</filename></entry>
+ <entry>Spanish language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>tcl*</filename></entry>
+ <entry>Ports that use Tcl to run.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities.</entry>
+ <entry>It does not include desktop publishing tools,
+ which go to <filename>print</filename>.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk*</filename></entry>
+ <entry>Ports that use Tk to run.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ukrainian</filename></entry>
+ <entry>Ukrainian language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>windowmaker*</filename></entry>
+ <entry>Ports to support the WindowMaker window
+ manager.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web.</entry>
+ <entry>HTML language
+ support belongs here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11</filename></entry>
+ <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
+ <filename>x11-*</filename> categories (see
+ below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-drivers</filename></entry>
+ <entry>X11 drivers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-servers</filename></entry>
+ <entry>X11 servers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-themes</filename></entry>
+ <entry>X11 themes.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>xfce*</filename></entry>
+ <entry>Ports related to the
+ <link xlink:href="http://www.xfce.org/">Xfce</link>
+ desktop environment.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>zope*</filename></entry>
+ <entry><link
+ xlink:href="http://www.zope.org/">Zope</link>
+ support.</entry>
+ <entry/>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <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.
+ Here is the list of priorities, in decreasing order of
+ precedence:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The first category must be a physical category (see
+ <link linkend="porting-categories">above</link>). This is
+ necessary to make the packaging work. Virtual categories
+ and physical categories may be intermixed after
+ that.</para>
+ </listitem>
+
+ <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
+ <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
+ <filename>www editors</filename>, not the other way
+ around. Also, you should not list
+ <filename>net</filename> when the port belongs to any of
+ <filename>irc</filename>, <filename>mail</filename>,
+ <filename>news</filename>, <filename>security</filename>,
+ or <filename>www</filename>, as <filename>net</filename>
+ is included implicitly.</para>
+ </listitem>
+
+ <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
+ <filename>x11</filename> in the category line for X
+ applications.</para>
+ </listitem>
+
+ <listitem>
+ <para><application>Emacs</application> modes should be
+ 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
+ <filename>lang</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Ports which install loadable kernel modules should
+ 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>
+ </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>
+ </listitem>
+
+ <listitem>
+ <para>If your 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
+ 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>
+ </sect2>
+
+ <sect2 xml:id="proposing-categories">
+ <title>Proposing a New Category</title>
+
+ <para>As the Ports Collection has grown over time, various new
+ categories have been introduced. New categories can either be
+ <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>
+
+ <para>Our existing practice has been to avoid creating a new
+ physical category unless either a large number of ports would
+ logically belong to it, or the ports that would belong to it
+ are a logically distinct group that is of limited general
+ interest (for instance, categories related to spoken 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
+ 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>
+
+ <para>Here is the procedure:</para>
+
+ <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
+ sufficient, and the list of existing ports proposed to
+ move. (If there are new ports pending in
+ <application>GNATS</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>
+ </step>
+
+ <step>
+ <para>Participate in the discussion.</para>
+ </step>
+
+ <step>
+ <para>If it seems that there is support for your 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>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>Makefile</filename>s for the new ports
+ once they are repocopied</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>Makefile</filename> for the new
+ category</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>Makefile</filename> for the old ports'
+ categories</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>Makefile</filename>s for ports that
+ depend on the old ports</para>
+ </listitem>
+
+ <listitem>
+ <para>(for extra credit, you can include the other files
+ that have to change, as per the procedure in the
+ Committer's Guide.)</para>
+ </listitem>
+ </itemizedlist>
+ </step>
+
+ <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>
+ </step>
+
+ <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>
+ </step>
+ </procedure>
+
+ <para>Proposing a new virtual category should be 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
+ <varname>CATEGORIES</varname> of the affected ports.</para>
+ </sect2>
+
+ <sect2 xml:id="proposing-reorg">
+ <title>Proposing Reorganizing All the Categories</title>
+
+ <para>Occasionally someone proposes reorganizing the
+ categories with either a 2-level structure, or some other kind
+ of keyword structure. To date, nothing has come of any of
+ these proposals because, while they are very easy to make, the
+ 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
+ a working prototype.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="makefile-distfiles">
+ <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>
+
+ <sect2>
+ <title><varname>DISTVERSION/DISTNAME</varname></title>
+
+ <para><varname>DISTNAME</varname> is the name of the port as
+ called by the authors of the software.
+ <varname>DISTNAME</varname> defaults to
+ <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it
+ only if necessary. <varname>DISTNAME</varname> is only used
+ in two places. First, the distribution file list
+ (<varname>DISTFILES</varname>) defaults to
+ <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>.
+ Second, the distribution file is expected to extract into a
+ subdirectory named <varname>WRKSRC</varname>, which defaults
+ to <filename>work/${DISTNAME}</filename>.</para>
+
+ <para>Some vendor's distribution names which do not fit into the
+ <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be
+ handled automatically by setting
+ <varname>DISTVERSION</varname>.
+ <varname>PORTVERSION</varname> and <varname>DISTNAME</varname>
+ will be derived automatically, but can of course be
+ overridden. The following table lists some examples:</para>
+
+ <informaltable frame="none" pgwide="0">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry><varname>DISTVERSION</varname></entry>
+ <entry><varname>PORTVERSION</varname></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>0.7.1d</entry>
+ <entry>0.7.1.d</entry>
+ </row>
+
+ <row>
+ <entry>10Alpha3</entry>
+ <entry>10.a3</entry>
+ </row>
+
+ <row>
+ <entry>3Beta7-pre2</entry>
+ <entry>3.b7.p2</entry>
+ </row>
+
+ <row>
+ <entry>8:f_17</entry>
+ <entry>8f.17</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <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/${PORTNAME}-${PORTVERSION}</filename> while
+ the original source archive is named something other than
+ <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>,
+ you should probably leave <varname>DISTNAME</varname>
+ alone— you are better off defining
+ <varname>DISTFILES</varname> than having to set both
+ <varname>DISTNAME</varname> and <varname>WRKSRC</varname>
+ (and possibly <varname>EXTRACT_SUFX</varname>).</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title><varname>MASTER_SITES</varname></title>
+
+ <para>Record the directory part of the FTP/HTTP-URL pointing at
+ the original tarball in <varname>MASTER_SITES</varname>. Do
+ not forget the trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this
+ specification for grabbing the distribution file with
+ <varname>FETCH</varname> if they cannot find it already on the
+ system.</para>
+
+ <para>It is recommended that you put multiple sites 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
+ closest master site and fetching from there; having multiple
+ 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
+ <varname>MASTER_SITE_<replaceable>*</replaceable></varname>
+ (e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>,
+ <varname>MASTER_SITE_GNU</varname> and
+ <varname>MASTER_SITE_PERL_CPAN</varname>). Simply set
+ <varname>MASTER_SITES</varname> to one of these variables and
+ <varname>MASTER_SITE_SUBDIR</varname> to the path within the
+ archive. Here is an example:</para>
+
+ <programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
MASTER_SITE_SUBDIR= make</programlisting>
- <para>Or you can use a condensed format:</para>
+ <para>Or you can use a condensed format:</para>
- <programlisting>MASTER_SITES= GNU/make</programlisting>
+ <programlisting>MASTER_SITES= GNU/make</programlisting>
- <para>These variables are defined in
- <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
- new entries added all the time, so make sure to check the
- latest version of this file before submitting a port.</para>
+ <para>These variables are defined in
+ <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
+ new entries added all the time, so make sure to check the
+ latest version of this file before submitting a port.</para>
- <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>
+ <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>
- <programlisting>MASTER_SITES= SF</programlisting>
+ <programlisting>MASTER_SITES= SF</programlisting>
- <para>If the guess is incorrect, it can be overridden as
- follows.</para>
+ <para>If the guess is incorrect, it can be overridden as
+ follows.</para>
- <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
+ <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
- <para>This can also be written as</para>
+ <para>This can also be written as</para>
- <programlisting>MASTER_SITES= SF
+ <programlisting>MASTER_SITES= SF
MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
- <table frame="none">
- <title>Popular Magic <varname>MASTER_SITES</varname>
- Macros</title>
+ <table frame="none">
+ <title>Popular Magic <varname>MASTER_SITES</varname>
+ Macros</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Macro</entry>
- <entry>Assumed subdirectory</entry>
- </row>
- </thead>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Macro</entry>
+ <entry>Assumed subdirectory</entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry><varname>APACHE_JAKARTA</varname></entry>
- <entry><varname>/dist/jakarta/${PORTNAME:S,-,,/,}/source</varname></entry>
- </row>
+ <tbody>
+ <row>
+ <entry><varname>APACHE_JAKARTA</varname></entry>
+ <entry><varname>/dist/jakarta/${PORTNAME:S,-,,/,}/source</varname></entry>
+ </row>
- <row>
- <entry><varname>BERLIOS</varname></entry>
- <entry><varname>/${PORTNAME:L}</varname></entry>
- </row>
+ <row>
+ <entry><varname>BERLIOS</varname></entry>
+ <entry><varname>/${PORTNAME:L}</varname></entry>
+ </row>
- <row>
- <entry><varname>CHEESESHOP</varname></entry>
- <entry><varname>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</varname></entry>
- </row>
+ <row>
+ <entry><varname>CHEESESHOP</varname></entry>
+ <entry><varname>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</varname></entry>
+ </row>
- <row>
- <entry><varname>DEBIAN</varname></entry>
- <entry><varname>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</varname></entry>
- </row>
+ <row>
+ <entry><varname>DEBIAN</varname></entry>
+ <entry><varname>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</varname></entry>
+ </row>
- <row>
- <entry><varname>GCC</varname></entry>
- <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry>
- </row>
+ <row>
+ <entry><varname>GCC</varname></entry>
+ <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry>
+ </row>
- <row>
- <entry><varname>GNOME</varname></entry>
- <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry>
- </row>
+ <row>
+ <entry><varname>GNOME</varname></entry>
+ <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry>
+ </row>
- <row>
- <entry><varname>GNU</varname></entry>
- <entry><varname>/gnu/${PORTNAME}</varname></entry>
- </row>
+ <row>
+ <entry><varname>GNU</varname></entry>
+ <entry><varname>/gnu/${PORTNAME}</varname></entry>
+ </row>
- <row>
- <entry><varname>MOZDEV</varname></entry>
- <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry>
- </row>
+ <row>
+ <entry><varname>MOZDEV</varname></entry>
+ <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry>
+ </row>
- <row>
- <entry><varname>PERL_CPAN</varname></entry>
- <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry>
- </row>
+ <row>
+ <entry><varname>PERL_CPAN</varname></entry>
+ <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry>
+ </row>
- <row>
- <entry><varname>PYTHON</varname></entry>
- <entry><varname>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</varname></entry>
- </row>
+ <row>
+ <entry><varname>PYTHON</varname></entry>
+ <entry><varname>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</varname></entry>
+ </row>
- <row>
- <entry><varname>RUBYFORGE</varname></entry>
- <entry><varname>/${PORTNAME:L}</varname></entry>
- </row>
+ <row>
+ <entry><varname>RUBYFORGE</varname></entry>
+ <entry><varname>/${PORTNAME:L}</varname></entry>
+ </row>
- <row>
- <entry><varname>SAVANNAH</varname></entry>
- <entry><varname>/${PORTNAME:L}</varname></entry>
- </row>
+ <row>
+ <entry><varname>SAVANNAH</varname></entry>
+ <entry><varname>/${PORTNAME:L}</varname></entry>
+ </row>
- <row>
- <entry><varname>SF</varname></entry>
- <entry><varname>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</varname></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
+ <row>
+ <entry><varname>SF</varname></entry>
+ <entry><varname>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</varname></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
- <sect2>
- <title><varname>EXTRACT_SUFX</varname></title>
+ <sect2>
+ <title><varname>EXTRACT_SUFX</varname></title>
- <para>If you have one distribution file, and it uses an odd
- suffix to indicate the compression mechanism, set
- <varname>EXTRACT_SUFX</varname>.</para>
+ <para>If you have 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.tgz</filename> instead of the more normal
- <filename>foo.tar.gz</filename>, you would write:</para>
+ <para>For example, if the distribution file was named
+ <filename>foo.tgz</filename> instead of the more normal
+ <filename>foo.tar.gz</filename>, you would write:</para>
- <programlisting>DISTNAME= foo
+ <programlisting>DISTNAME= foo
EXTRACT_SUFX= .tgz</programlisting>
- <para>The <varname>USE_BZIP2</varname>,
- <varname>USE_XZ</varname> and
- <varname>USE_ZIP</varname> variables automatically set
- <varname>EXTRACT_SUFX</varname> to
- <literal>.tar.bz2</literal>, <literal>.tar.xz</literal>
- or <literal>.zip</literal> as necessary. If neither of
- these are set then <varname>EXTRACT_SUFX</varname>
- defaults to <literal>.tar.gz</literal>.</para>
+ <para>The <varname>USE_BZIP2</varname>,
+ <varname>USE_XZ</varname> and <varname>USE_ZIP</varname>
+ variables automatically set <varname>EXTRACT_SUFX</varname> to
+ <literal>.tar.bz2</literal>, <literal>.tar.xz</literal> or
+ <literal>.zip</literal> as necessary. If neither of these are
+ set then <varname>EXTRACT_SUFX</varname> defaults to
+ <literal>.tar.gz</literal>.</para>
- <note>
- <para>You never need to set both
- <varname>EXTRACT_SUFX</varname> and
- <varname>DISTFILES</varname>.</para>
- </note>
- </sect2>
+ <note>
+ <para>You never need to set both
+ <varname>EXTRACT_SUFX</varname> and
+ <varname>DISTFILES</varname>.</para>
+ </note>
+ </sect2>
- <sect2>
- <title><varname>DISTFILES</varname></title>
+ <sect2>
+ <title><varname>DISTFILES</varname></title>
- <para>Sometimes the names of the files to be downloaded have
- no resemblance to the name of the port. For example, it
- might be called <filename>source.tar.gz</filename> or
- similar. In other cases the application's source code might
- be in several different archives, all of which must be
- downloaded.</para>
+ <para>Sometimes the names of the files to be downloaded have no
+ resemblance to the name of the port. For example, it might be
+ called <filename>source.tar.gz</filename> or similar. In
+ other cases the application's source code might be in several
+ different archives, all of which must be downloaded.</para>
- <para>If this is the case, set <varname>DISTFILES</varname> to
- be a space separated list of all the files that must be
- downloaded.</para>
+ <para>If this is the case, set <varname>DISTFILES</varname> to
+ be a space separated list of all the files that must be
+ downloaded.</para>
- <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>
+ <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>
- <para>If not explicitly set, <varname>DISTFILES</varname>
- defaults to
- <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
- </sect2>
+ <para>If not explicitly set, <varname>DISTFILES</varname>
+ defaults to
+ <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
+ </sect2>
- <sect2>
- <title><varname>EXTRACT_ONLY</varname></title>
+ <sect2>
+ <title><varname>EXTRACT_ONLY</varname></title>
- <para>If only some of the <varname>DISTFILES</varname> must be
- extracted—for example, one of them is the source code,
- while another is an uncompressed document—list the
- filenames that must be extracted in
- <varname>EXTRACT_ONLY</varname>.</para>
+ <para>If only some of the <varname>DISTFILES</varname> must be
+ extracted—for example, one of them is the source code,
+ while another is an uncompressed document—list the
+ filenames that must be extracted in
+ <varname>EXTRACT_ONLY</varname>.</para>
- <programlisting>DISTFILES= source.tar.gz manual.html
+ <programlisting>DISTFILES= source.tar.gz manual.html
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>If <emphasis>none</emphasis> of the
+ <varname>DISTFILES</varname> should be uncompressed then set
+ <varname>EXTRACT_ONLY</varname> to the empty string.</para>
- <programlisting>EXTRACT_ONLY=</programlisting>
- </sect2>
+ <programlisting>EXTRACT_ONLY=</programlisting>
+ </sect2>
- <sect2 xml:id="porting-patchfiles">
- <title><varname>PATCHFILES</varname></title>
+ <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 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 your port requires some additional patches that are
+ available by FTP or HTTP, 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 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 filenames,
- then set <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <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
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
- <para>Do not worry if the patches are compressed; they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or <filename>.Z</filename>.</para>
+ <para>Do not worry if the patches are compressed; they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or <filename>.Z</filename>.</para>
- <para>If the patch is distributed with some other files, such
- as documentation, in a <command>gzip</command>ped tarball,
- you cannot just use <varname>PATCHFILES</varname>. If that
- is the case, add the name and the location of the patch
- tarball to <varname>DISTFILES</varname> and
- <varname>MASTER_SITES</varname>. Then, use the
- <varname>EXTRA_PATCHES</varname> variable to point to those
- files and <filename>bsd.port.mk</filename> will
- automatically apply them for you. In particular, do
- <emphasis>not</emphasis> copy patch files into the
- <varname>PATCHDIR</varname> directory—that directory
- may not be writable.</para>
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a <command>gzip</command>ped tarball, you
+ cannot just use <varname>PATCHFILES</varname>. If that is the
+ case, add the name and the location of the patch tarball to
+ <varname>DISTFILES</varname> and
+ <varname>MASTER_SITES</varname>. Then, use the
+ <varname>EXTRA_PATCHES</varname> variable to point to those
+ files and <filename>bsd.port.mk</filename> will automatically
+ apply them for you. In particular, do
+ <emphasis>not</emphasis> copy patch files into the
+ <varname>PATCHDIR</varname> directory—that directory may
+ not be writable.</para>
- <note>
- <para>The tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly
- extract it if it is a regular <command>gzip</command>ped
- or <command>compress</command>ed tarball. If you do the
- latter, take extra care not to overwrite something that
- already exists in that directory. Also, do not forget to
- add a command to remove the copied patch in the
- <buildtarget>pre-clean</buildtarget> target.</para>
- </note>
- </sect2>
+ <note>
+ <para>The tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular <command>gzip</command>ped or
+ <command>compress</command>ed tarball. If you do the
+ latter, take extra care not to overwrite something that
+ already exists in that directory. Also, do not forget to
+ add a command to remove the copied patch in the
+ <buildtarget>pre-clean</buildtarget> target.</para>
+ </note>
+ </sect2>
- <sect2 xml:id="porting-master-sites-n">
- <title>Multiple Distribution Files or Patches from Different
- Sites and Subdirectories
- (<literal>MASTER_SITES:n</literal>)</title>
+ <sect2 xml:id="porting-master-sites-n">
+ <title>Multiple Distribution Files or Patches from Different
+ Sites and Subdirectories
+ (<literal>MASTER_SITES:n</literal>)</title>
- <para>(Consider this to be a somewhat
- <quote>advanced topic</quote>; those new to this document
- may wish to skip this section at first).</para>
+ <para>(Consider this to be a somewhat
+ <quote>advanced topic</quote>; those new to this document
+ may wish to skip this section at first).</para>
- <para>This section has information on the fetching mechanism
- known as both <literal>MASTER_SITES:n</literal> and
- <literal>MASTER_SITES_NN</literal>. We will refer to this
- mechanism as <literal>MASTER_SITES:n</literal>.</para>
+ <para>This section has information on the fetching mechanism
+ known as both <literal>MASTER_SITES:n</literal> and
+ <literal>MASTER_SITES_NN</literal>. We will refer to this
+ mechanism as <literal>MASTER_SITES:n</literal>.</para>
- <para>A little background first. OpenBSD has a neat feature
- inside the <varname>DISTFILES</varname> and
- <varname>PATCHFILES</varname> variables which allows files
- and patches to be postfixed with <literal>:n</literal>
- identifiers. Here, <literal>n</literal> can be both
- <literal>[0-9]</literal> and denote a group designation.
- For example:</para>
+ <para>A little background first. OpenBSD has a neat feature
+ inside the <varname>DISTFILES</varname> and
+ <varname>PATCHFILES</varname> variables which allows files and
+ patches to be postfixed with <literal>:n</literal>
+ identifiers. Here, <literal>n</literal> can be both
+ <literal>[0-9]</literal> and denote a group designation. For
+ example:</para>
- <programlisting>DISTFILES= alpha:0 beta:1</programlisting>
+ <programlisting>DISTFILES= alpha:0 beta:1</programlisting>
- <para>In OpenBSD, distribution file <filename>alpha</filename>
- will be associated with variable
- <varname>MASTER_SITES0</varname> instead of our common
- <varname>MASTER_SITES</varname> and
- <filename>beta</filename> with
- <varname>MASTER_SITES1</varname>.</para>
+ <para>In OpenBSD, distribution file <filename>alpha</filename>
+ will be associated with variable
+ <varname>MASTER_SITES0</varname> instead of our common
+ <varname>MASTER_SITES</varname> and
+ <filename>beta</filename> with
+ <varname>MASTER_SITES1</varname>.</para>
- <para>This is a very interesting feature which can decrease
- that endless search for the correct download site.</para>
+ <para>This is a very interesting feature which can decrease
+ that endless search for the correct download site.</para>
- <para>Just picture 2 files in <varname>DISTFILES</varname> and
- 20 sites in <varname>MASTER_SITES</varname>, the sites slow
- as hell where <filename>beta</filename> is carried by all
- sites in <varname>MASTER_SITES</varname>, and
- <filename>alpha</filename> can only be found in the 20th
- site. It would be such a waste to check all of them if the
- maintainer knew this beforehand, would it not? Not a good
- start for that lovely weekend!</para>
+ <para>Just picture 2 files in <varname>DISTFILES</varname> and
+ 20 sites in <varname>MASTER_SITES</varname>, the sites slow as
+ hell where <filename>beta</filename> is carried by all sites
+ in <varname>MASTER_SITES</varname>, and
+ <filename>alpha</filename> can only be found in the 20th site.
+ It would be such a waste to check all of them if the
+ maintainer knew this beforehand, would it not? Not a good
+ start for that lovely weekend!</para>
- <para>Now that you have the idea, just imagine more
- <varname>DISTFILES</varname> and more
- <varname>MASTER_SITES</varname>. Surely our
- <quote>distfiles survey meister</quote> would appreciate the
- relief to network strain that this would bring.</para>
+ <para>Now that you have the idea, just imagine more
+ <varname>DISTFILES</varname> and more
+ <varname>MASTER_SITES</varname>. Surely our
+ <quote>distfiles survey meister</quote> would appreciate the
+ relief to network strain that this would bring.</para>
- <para>In the next sections, information will follow on the
- &os; implementation of this idea. We improved a bit on
- OpenBSD's concept.</para>
+ <para>In the next sections, information will follow on the
+ &os; implementation of this idea. We improved a bit on
+ OpenBSD's concept.</para>
- <sect3>
- <title>Simplified Information</title>
+ <sect3>
+ <title>Simplified Information</title>
- <para>This section tells you how to quickly prepare fine
- grained fetching of multiple distribution files and
- patches from different sites and subdirectories. We
- describe here a case of simplified
- <literal>MASTER_SITES:n</literal> usage. This will be
- sufficient for most scenarios. However, if you need
- further information, you will have to refer to the next
- section.</para>
+ <para>This section tells you how to quickly prepare fine
+ grained fetching of multiple distribution files and patches
+ from different sites and subdirectories. We describe here a
+ case of simplified <literal>MASTER_SITES:n</literal> usage.
+ This will be sufficient for most scenarios. However, if you
+ need further information, you will have to refer to the next
+ section.</para>
- <para>Some applications consist of multiple distribution
- files that must be downloaded from a number of different
- sites. For example,
- <application>Ghostscript</application> consists of the
- core of the program, and then a large number of driver
- files that are used depending on the user's printer. Some
- of these driver files are supplied with the core, but many
- others must be downloaded from a variety of different
- sites.</para>
+ <para>Some applications consist of multiple distribution files
+ that must be downloaded from a number of different sites.
+ For example, <application>Ghostscript</application> consists
+ of the core of the program, and then a large number of
+ driver files that are used depending on the user's printer.
+ Some of these driver files are supplied with the core, but
+ many others must be downloaded from a variety of different
+ sites.</para>
- <para>To support this, each entry in
- <varname>DISTFILES</varname> may be followed by a colon
- and a <quote>tag name</quote>. Each site listed in
- <varname>MASTER_SITES</varname> is then followed by a
- colon, and the tag that indicates which distribution files
- should be downloaded from this site.</para>
+ <para>To support this, each entry in
+ <varname>DISTFILES</varname> may be followed by a colon and
+ a <quote>tag name</quote>. Each site listed in
+ <varname>MASTER_SITES</varname> is then followed by a colon,
+ and the tag that indicates which distribution files should
+ be downloaded from this site.</para>
- <para>For example, consider an application with the source
- split in two parts, <filename>source1.tar.gz</filename>
- 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>
+ <para>For example, consider an application with the source
+ split in two parts, <filename>source1.tar.gz</filename> 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>
- <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>
+ <title>Simplified Use of <literal>MASTER_SITES:n</literal>
+ with One File Per Site</title>
- <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
+ <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2</programlisting>
- </example>
+ </example>
- <para>Multiple distribution files can have the same tag.
- Continuing the previous example, suppose that there was a
- third distfile, <filename>source3.tar.gz</filename>, that
- 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>
+ <para>Multiple distribution files can have the same tag.
+ Continuing the previous example, suppose that there was a
+ third distfile, <filename>source3.tar.gz</filename>, that
+ 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>
- <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>
+ <title>Simplified Use of <literal>MASTER_SITES:n</literal>
+ with More Than One File Per Site</title>
- <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
+ <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2 \
source3.tar.gz:source2</programlisting>
- </example>
- </sect3>
+ </example>
+ </sect3>
- <sect3>
- <title>Detailed Information</title>
+ <sect3>
+ <title>Detailed Information</title>
- <para>Okay, so the previous section example did not reflect
- your needs? In this section we will explain in detail
- how the fine grained fetching mechanism
- <literal>MASTER_SITES:n</literal> works and how you can
- modify your ports to use it.</para>
+ <para>Okay, so the previous section example did not reflect
+ your needs? In this section we will explain in detail how
+ the fine grained fetching mechanism
+ <literal>MASTER_SITES:n</literal> works and how you can
+ modify your ports to use it.</para>
- <orderedlist>
- <listitem>
- <para>Elements can be postfixed with
- <literal>:n</literal> where
- <replaceable>n</replaceable> is
- <literal>[^:,]+</literal>, i.e.,
- <replaceable>n</replaceable> could conceptually be any
- alphanumeric string but we will limit it to
- <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
- now.</para>
+ <orderedlist>
+ <listitem>
+ <para>Elements can be postfixed with <literal>:n</literal>
+ where <replaceable>n</replaceable> is
+ <literal>[^:,]+</literal>, i.e.,
+ <replaceable>n</replaceable> could conceptually be any
+ alphanumeric string but we will limit it to
+ <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
+ now.</para>
- <para>Moreover, string matching is case sensitive;
- i.e., <literal>n</literal> is different from
- <literal>N</literal>.</para>
+ <para>Moreover, string matching is case sensitive; i.e.,
+ <literal>n</literal> is different from
+ <literal>N</literal>.</para>
- <para>However, the following words cannot be used for
- 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"/>).
- Furthermore, <literal>DEFAULT</literal> is a special
- purpose word (check item <xref
- linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
- </listitem>
+ <para>However, the following words cannot be used for
+ 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"/>).
+ Furthermore, <literal>DEFAULT</literal> is a special
+ purpose word (check item <xref
+ linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
+ </listitem>
- <listitem>
- <para>Elements postfixed with <literal>:n</literal>
- belong to the group <literal>n</literal>,
- <literal>:m</literal> belong to group
- <literal>m</literal> and so forth.</para>
- </listitem>
+ <listitem>
+ <para>Elements postfixed with <literal>:n</literal>
+ belong to the group <literal>n</literal>,
+ <literal>:m</literal> belong to group
+ <literal>m</literal> and so forth.</para>
+ </listitem>
- <listitem xml:id="porting-master-sites-n-DEFAULT-group">
- <para>Elements without a postfix are groupless, i.e.,
- they all belong to the special group
- <literal>DEFAULT</literal>. If you postfix any
- 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>
+ <listitem xml:id="porting-master-sites-n-DEFAULT-group">
+ <para>Elements without a postfix are groupless, i.e., they
+ all belong to the special group
+ <literal>DEFAULT</literal>. If you postfix any 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>
- <para>The following examples are equivalent but the
- first one is preferred:</para>
+ <para>The following examples are equivalent but the first
+ one is preferred:</para>
- <programlisting>MASTER_SITES= alpha</programlisting>
+ <programlisting>MASTER_SITES= alpha</programlisting>
- <programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>
- </listitem>
+ <programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>
+ </listitem>
- <listitem>
- <para>Groups are not exclusive, an element may belong to
- several different groups at the same time and a group
- can either have either several different elements or
- none at all. Repeated elements within the same group
- will be simply that, repeated elements.</para>
- </listitem>
+ <listitem>
+ <para>Groups are not exclusive, an element may belong to
+ several different groups at the same time and a group
+ can either have either several different elements or
+ none at all. Repeated elements within the same group
+ will be simply that, repeated elements.</para>
+ </listitem>
- <listitem xml:id="porting-master-sites-n-comma-operator">
- <para>When you want an element to belong to several
- groups at the same time, you can use the comma
- operator (<literal>,</literal>).</para>
+ <listitem xml:id="porting-master-sites-n-comma-operator">
+ <para>When you want an element to belong to several groups
+ at the same time, you can use the comma operator
+ (<literal>,</literal>).</para>
- <para>Instead of repeating it several times, each time
- with a different postfix, we can list several groups
- at once in a single postfix. For instance,
- <literal>:m,n,o</literal> marks an element that
- belongs to group <literal>m</literal>,
- <literal>n</literal> and <literal>o</literal>.</para>
+ <para>Instead of repeating it several times, each time
+ with a different postfix, we can list several groups at
+ once in a single postfix. For instance,
+ <literal>:m,n,o</literal> marks an element that belongs
+ to group <literal>m</literal>, <literal>n</literal> and
+ <literal>o</literal>.</para>
- <para>All the following examples are equivalent but the
- last one is preferred:</para>
+ <para>All the following examples are equivalent but the
+ last one is preferred:</para>
- <programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting>
+ <programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting>
- <programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting>
+ <programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting>
- <programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting>
+ <programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting>
- <programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
- </listitem>
+ <programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
+ </listitem>
- <listitem>
- <para>All sites within a given group are sorted
- according to <varname>MASTER_SORT_AWK</varname>. All
- groups within <varname>MASTER_SITES</varname> and
- <varname>PATCH_SITES</varname> are sorted as
- well.</para>
- </listitem>
+ <listitem>
+ <para>All sites within a given group are sorted according
+ to <varname>MASTER_SORT_AWK</varname>. All groups
+ within <varname>MASTER_SITES</varname> and
+ <varname>PATCH_SITES</varname> are sorted as
+ well.</para>
+ </listitem>
- <listitem xml:id="porting-master-sites-n-group-semantics">
- <para>Group semantics can be used in any of the
- following variables <varname>MASTER_SITES</varname>,
- <varname>PATCH_SITES</varname>,
- <varname>MASTER_SITE_SUBDIR</varname>,
- <varname>PATCH_SITE_SUBDIR</varname>,
- <varname>DISTFILES</varname>, and
- <varname>PATCHFILES</varname> according to the
- following syntax:</para>
+ <listitem xml:id="porting-master-sites-n-group-semantics">
+ <para>Group semantics can be used in any of the following
+ variables <varname>MASTER_SITES</varname>,
+ <varname>PATCH_SITES</varname>,
+ <varname>MASTER_SITE_SUBDIR</varname>,
+ <varname>PATCH_SITE_SUBDIR</varname>,
+ <varname>DISTFILES</varname>, and
+ <varname>PATCHFILES</varname> according to the following
+ syntax:</para>
- <orderedlist>
- <listitem>
- <para>All <varname>MASTER_SITES</varname>,
- <varname>PATCH_SITES</varname>,
- <varname>MASTER_SITE_SUBDIR</varname> and
- <varname>PATCH_SITE_SUBDIR</varname> elements must
- 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>MASTER_SITES:n</literal> mechanism relies
- on the existence of the terminator
- <literal>/</literal> to avoid confusing elements
- where a <literal>:n</literal> is a valid part of
- the element with occurrences where
- <literal>:n</literal> denotes group
- <literal>n</literal>. For compatibility purposes,
- since the <literal>/</literal> terminator was not
- 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>
- 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>
+ <orderedlist>
+ <listitem>
+ <para>All <varname>MASTER_SITES</varname>,
+ <varname>PATCH_SITES</varname>,
+ <varname>MASTER_SITE_SUBDIR</varname> and
+ <varname>PATCH_SITE_SUBDIR</varname> elements must
+ 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>MASTER_SITES:n</literal> mechanism relies
+ on the existence of the terminator
+ <literal>/</literal> to avoid confusing elements
+ where a <literal>:n</literal> is a valid part of the
+ element with occurrences where <literal>:n</literal>
+ denotes group <literal>n</literal>. For
+ compatibility purposes, since the
+ <literal>/</literal> terminator was not 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>
+ 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>
- <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
- <varname>MASTER_SITE_SUBDIR</varname></title>
+ <title>Detailed Use of
+ <literal>MASTER_SITES:n</literal> in
+ <varname>MASTER_SITE_SUBDIR</varname></title>
- <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting>
+ <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting>
- <itemizedlist>
- <listitem>
- <para>Directories within group
- <literal>DEFAULT</literal> ->
- old:n</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Directories within group
+ <literal>DEFAULT</literal> ->
+ old:n</para>
+ </listitem>
- <listitem>
- <para>Directories within group
- <literal>NEW</literal> -> new</para>
- </listitem>
- </itemizedlist>
- </example>
+ <listitem>
+ <para>Directories within group
+ <literal>NEW</literal> -> new</para>
+ </listitem>
+ </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
- Multiple Subdirectories</title>
+ <title>Detailed Use of
+ <literal>MASTER_SITES:n</literal> with Comma
+ Operator, Multiple Files, Multiple Sites and
+ Multiple Subdirectories</title>
- <programlisting>MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
+ <programlisting>MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
http://site3/:group3 http://site4/:group4 \
http://site5/:group5 http://site6/:group6 \
http://site7/:DEFAULT,group6 \
@@ -2124,1015 +2097,995 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
directory-one/:group6,DEFAULT \
directory</programlisting>
- <para>The previous example results in the
- following fine grained fetching. Sites are
- listed in the exact order they will be
- used.</para>
+ <para>The previous example results in the following
+ fine grained fetching. Sites are listed in the
+ exact order they will be used.</para>
- <itemizedlist>
- <listitem>
- <para><filename>file1</filename> will be
- fetched from</para>
+ <itemizedlist>
+ <listitem>
+ <para><filename>file1</filename> will be
+ fetched from</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para>http://site1/directory-trial:1/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory-trial:1/</para>
+ </listitem>
- <listitem>
- <para>http://site1/directory-one/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory-one/</para>
+ </listitem>
- <listitem>
- <para>http://site1/directory/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory/</para>
+ </listitem>
- <listitem>
- <para>http://site2/</para>
- </listitem>
+ <listitem>
+ <para>http://site2/</para>
+ </listitem>
- <listitem>
- <para>http://site7/</para>
- </listitem>
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para><filename>file2</filename> will be
- fetched exactly as
- <filename>file1</filename> since they
- both belong to the same group</para>
+ <listitem>
+ <para><filename>file2</filename> will be fetched
+ exactly as <filename>file1</filename> since
+ they both belong to the same group</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para>http://site1/directory-trial:1/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory-trial:1/</para>
+ </listitem>
- <listitem>
- <para>http://site1/directory-one/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory-one/</para>
+ </listitem>
- <listitem>
- <para>http://site1/directory/</para>
- </listitem>
+ <listitem>
+ <para>http://site1/directory/</para>
+ </listitem>
- <listitem>
- <para>http://site2/</para>
- </listitem>
+ <listitem>
+ <para>http://site2/</para>
+ </listitem>
- <listitem>
- <para>http://site7/</para>
- </listitem>
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para><filename>file3</filename> will be
- fetched from</para>
+ <listitem>
+ <para><filename>file3</filename> will be fetched
+ from</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para>http://site3/</para>
- </listitem>
+ <listitem>
+ <para>http://site3/</para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para><filename>file4</filename> will be
- fetched from</para>
+ <listitem>
+ <para><filename>file4</filename> will be
+ fetched from</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para>http://site4/</para>
- </listitem>
+ <listitem>
+ <para>http://site4/</para>
+ </listitem>
- <listitem>
- <para>http://site5/</para>
- </listitem>
+ <listitem>
+ <para>http://site5/</para>
+ </listitem>
- <listitem>
- <para>http://site6/</para>
- </listitem>
+ <listitem>
+ <para>http://site6/</para>
+ </listitem>
- <listitem>
- <para>http://site7/</para>
- </listitem>
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
- <listitem>
- <para>http://site8/directory-one/</para>
- </listitem>
+ <listitem>
+ <para>http://site8/directory-one/</para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para><filename>file5</filename> will be
- fetched from</para>
+ <listitem>
+ <para><filename>file5</filename> will be fetched
+ from</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para><filename>file6</filename> will be
- fetched from</para>
+ <listitem>
+ <para><filename>file6</filename> will be fetched
+ from</para>
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
- <listitem>
- <para>http://site8/</para>
- </listitem>
+ <listitem>
+ <para>http://site8/</para>
+ </listitem>
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </example>
- </listitem>
- </orderedlist>
- </listitem>
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </example>
+ </listitem>
+ </orderedlist>
+ </listitem>
- <listitem>
- <para>How do I group one of the special variables from
- <filename>bsd.sites.mk</filename>, e.g.,
- <varname>MASTER_SITE_SOURCEFORGE</varname>?</para>
+ <listitem>
+ <para>How do I group one of the special variables from
+ <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>
+ <title>Detailed Use of <literal>MASTER_SITES:n</literal>
+ with
+ <varname>MASTER_SITE_SOURCEFORGE</varname></title>
- <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
+ <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
DISTFILES= something.tar.gz:sourceforge</programlisting>
- </example>
+ </example>
- <para><filename>something.tar.gz</filename> will be
- fetched from all sites within
- <varname>MASTER_SITE_SOURCEFORGE</varname>.</para>
- </listitem>
+ <para><filename>something.tar.gz</filename> will be
+ fetched from all sites within
+ <varname>MASTER_SITE_SOURCEFORGE</varname>.</para>
+ </listitem>
- <listitem>
- <para>How do I use this with <varname>PATCH*</varname>
- variables?</para>
+ <listitem>
+ <para>How do I use this with <varname>PATCH*</varname>
+ variables?</para>
- <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>
+ <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>
- <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>
+ <title>Simplified Use of
+ <literal>MASTER_SITES:n</literal> with
+ <varname>PATCH_SITES</varname></title>
- <programlisting>PATCH_SITES= http://site1/ http://site2/:test
+ <programlisting>PATCH_SITES= http://site1/ http://site2/:test
PATCHFILES= patch1:test</programlisting>
- </example>
- </listitem>
- </orderedlist>
- </sect3>
+ </example>
+ </listitem>
+ </orderedlist>
+ </sect3>
- <sect3>
- <title>What Does Change for Ports? What Does Not?</title>
+ <sect3>
+ <title>What Does Change for Ports? What Does Not?</title>
- <orderedlist numeration="lowerroman">
- <listitem>
- <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>
- </listitem>
+ <orderedlist numeration="lowerroman">
+ <listitem>
+ <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>
+ </listitem>
- <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>fetch-list</buildtarget>,
- <buildtarget>master-sites</buildtarget> and
- <buildtarget>patch-sites</buildtarget>.</para>
+ <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>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
- <varname>DISTFILES</varname> and
- <varname>PATCHFILES</varname> with their matching
- group elements within both
- <varname>MASTER_SITES</varname> and
- <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>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><buildtarget>do-fetch</buildtarget>: deploys
+ the new grouping postfixed
+ <varname>DISTFILES</varname> and
+ <varname>PATCHFILES</varname> with their matching
+ group elements within both
+ <varname>MASTER_SITES</varname> and
+ <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>
+ </listitem>
- <listitem>
- <para><buildtarget>fetch-list</buildtarget>: works
- like old <buildtarget>fetch-list</buildtarget>
- with the exception that it groups just like
- <buildtarget>do-fetch</buildtarget>.</para>
- </listitem>
+ <listitem>
+ <para><buildtarget>fetch-list</buildtarget>: works
+ like old <buildtarget>fetch-list</buildtarget> with
+ the exception that it groups just like
+ <buildtarget>do-fetch</buildtarget>.</para>
+ </listitem>
- <listitem>
- <para><buildtarget>master-sites</buildtarget> and
- <buildtarget>patch-sites</buildtarget>:
- (incompatible with older versions) only return the
- elements of group <literal>DEFAULT</literal>; in
- fact, they execute targets
- <buildtarget>master-sites-default</buildtarget>
- and <buildtarget>patch-sites-default</buildtarget>
- respectively.</para>
+ <listitem>
+ <para><buildtarget>master-sites</buildtarget> and
+ <buildtarget>patch-sites</buildtarget>:
+ (incompatible with older versions) only return the
+ elements of group <literal>DEFAULT</literal>; in
+ fact, they execute targets
+ <buildtarget>master-sites-default</buildtarget> and
+ <buildtarget>patch-sites-default</buildtarget>
+ respectively.</para>
- <para>Furthermore, using target either
- <buildtarget>master-sites-all</buildtarget> or
- <buildtarget>patch-sites-all</buildtarget> is
- preferred to directly checking either
- <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"/>
- for more information on these new port
- targets.</para>
- </listitem>
- </itemizedlist>
- </listitem>
+ <para>Furthermore, using target either
+ <buildtarget>master-sites-all</buildtarget> or
+ <buildtarget>patch-sites-all</buildtarget> is
+ preferred to directly checking either
+ <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"/>
+ for more information on these new port
+ targets.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para>New port targets</para>
+ <listitem>
+ <para>New port targets</para>
- <orderedlist>
- <listitem>
- <para>There are
- <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget>
- and
- <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget>
- targets which will list the elements of the
- respective group <replaceable>n</replaceable>
- 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
- <literal>DEFAULT</literal>,
- <buildtarget>master-sites-test</buildtarget> and
- <buildtarget>patch-sites-test</buildtarget> of
- group <literal>test</literal>, and thereon.</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>There are
+ <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget>
+ and
+ <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget>
+ targets which will list the elements of the
+ respective group <replaceable>n</replaceable>
+ 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
+ <literal>DEFAULT</literal>,
+ <buildtarget>master-sites-test</buildtarget> and
+ <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">
- <para>There are new targets
- <buildtarget>master-sites-all</buildtarget> and
- <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
- belonged to the same group with the caveat that it
- lists as many
- <varname>MASTER_SITE_BACKUP</varname> and
- <varname>MASTER_SITE_OVERRIDE</varname> as there
- are groups defined within either
- <varname>DISTFILES</varname> or
- <varname>PATCHFILES</varname>; respectively for
- <buildtarget>master-sites-all</buildtarget> and
- <buildtarget>patch-sites-all</buildtarget>.</para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
+ <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>master-sites</buildtarget> and
+ <buildtarget>patch-sites</buildtarget> ones. They
+ return the elements of all groups as if they all
+ belonged to the same group with the caveat that it
+ lists as many <varname>MASTER_SITE_BACKUP</varname>
+ and <varname>MASTER_SITE_OVERRIDE</varname> as there
+ are groups defined within either
+ <varname>DISTFILES</varname> or
+ <varname>PATCHFILES</varname>; respectively for
+ <buildtarget>master-sites-all</buildtarget> and
+ <buildtarget>patch-sites-all</buildtarget>.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
- <sect2>
- <title><varname>DIST_SUBDIR</varname></title>
+ <sect2>
+ <title><varname>DIST_SUBDIR</varname></title>
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port
- requires a lot of files to be fetched, or contains a file
- that has a name that might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set
- <varname>DIST_SUBDIR</varname> to the name of the port
- (<literal>${PORTNAME}</literal> or
- <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work
- fine). This will change <varname>DISTDIR</varname> from the
- default <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>,
- and in effect puts everything that is required for your port
- into that subdirectory.</para>
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set
+ <varname>DIST_SUBDIR</varname> to the name of the port
+ (<literal>${PORTNAME}</literal> or
+ <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work
+ fine). This will change <varname>DISTDIR</varname> from the
+ default <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, and in
+ effect puts everything that is required for your port into
+ that subdirectory.</para>
- <para>It will also look at the subdirectory with the same name
- on the backup master site at
- <filename>ftp.FreeBSD.org</filename>. (Setting
- <varname>DISTDIR</varname> explicitly in your
- <varname>Makefile</varname> will not accomplish this, so
- please use <varname>DIST_SUBDIR</varname>.)</para>
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.FreeBSD.org</filename>. (Setting
+ <varname>DISTDIR</varname> explicitly in your
+ <varname>Makefile</varname> will not accomplish this, so
+ please use <varname>DIST_SUBDIR</varname>.)</para>
- <note>
- <para>This does not affect the
- <varname>MASTER_SITES</varname> you define in your
- <filename>Makefile</filename>.</para>
- </note>
- </sect2>
+ <note>
+ <para>This does not affect the
+ <varname>MASTER_SITES</varname> you define in your
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect2>
- <sect2>
- <title><varname>ALWAYS_KEEP_DISTFILES</varname></title>
+ <sect2>
+ <title><varname>ALWAYS_KEEP_DISTFILES</varname></title>
- <para>If your port uses binary distfiles and has a license
- that requires that the source code is provided with packages
- distributed in binary form, e.g., GPL,
- <varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the
- &os; build cluster to keep a copy of the files specified in
- <varname>DISTFILES</varname>. Users of these ports will
- generally not need these files, so it is a good idea to only
- add the source distfiles to <varname>DISTFILES</varname>
- when <varname>PACKAGE_BUILDING</varname> is defined.</para>
+ <para>If your port uses binary distfiles and has a license that
+ requires that the source code is provided with packages
+ distributed in binary form, e.g., GPL,
+ <varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the
+ &os; build cluster to keep a copy of the files specified in
+ <varname>DISTFILES</varname>. Users of these ports will
+ generally not need these files, so it is a good idea to only
+ 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>
+ <title>Use of
+ <varname>ALWAYS_KEEP_DISTFILES</varname></title>
- <programlisting>.if defined(PACKAGE_BUILDING)
+ <programlisting>.if defined(PACKAGE_BUILDING)
DISTFILES+= <replaceable>foo.tar.gz</replaceable>
ALWAYS_KEEP_DISTFILES= yes
.endif</programlisting>
- </example>
+ </example>
- <para>When adding extra files to <varname>DISTFILES</varname>,
- make sure you also add them to
- <filename>distinfo</filename>. Also, the additional files
- will normally be extracted into <varname>WRKDIR</varname> as
- well, which for some ports may lead to undesirable side
- effects and require special handling.</para>
- </sect2>
- </sect1>
+ <para>When adding extra files to <varname>DISTFILES</varname>,
+ make sure you also add them to <filename>distinfo</filename>.
+ Also, the additional files will normally be extracted into
+ <varname>WRKDIR</varname> as well, which for some ports may
+ lead to undesirable side effects and require special
+ handling.</para>
+ </sect2>
+ </sect1>
- <sect1 xml:id="makefile-maintainer">
- <title><varname>MAINTAINER</varname></title>
+ <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
- format used should be <literal>user@hostname.domain</literal>.
- Please do not include any descriptive text such as your real
- name in this entry—that merely confuses
- <filename>bsd.port.mk</filename>.</para>
+ <para>Note that only a single address without the comment part is
+ allowed as a <varname>MAINTAINER</varname> value. The format
+ used should be <literal>user@hostname.domain</literal>. Please
+ do not include any descriptive text such as your real name in
+ this entry—that merely confuses
+ <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
- challenge for port maintainers</link> section.</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
+ challenge for port maintainers</link> section.</para>
- <para>Changes to the port will be sent to the maintainer of a
- port for review and approval before being committed. If the
- maintainer does not respond to an update request after two
- weeks (excluding major public holidays), then that is
- considered a maintainer timeout, and the update may be made
- without explicit maintainer approval. If the maintainer does
- not respond within three months, then that maintainer is
- considered absent without leave, and can be replaced as the
- maintainer of the particular port in question. Exceptions to
- this are anything maintained by the &a.portmgr;, or the
- &a.security-officer;. No unauthorized commits may ever be
- made to ports maintained by those groups.</para>
+ <para>Changes to the port will be sent to the maintainer of a port
+ for review and approval before being committed. If the
+ maintainer does not respond to an update request after two weeks
+ (excluding major public holidays), then that is considered a
+ maintainer timeout, and the update may be made without explicit
+ maintainer approval. If the maintainer does not respond within
+ three months, then that maintainer is considered absent without
+ leave, and can be replaced as the maintainer of the particular
+ port in question. Exceptions to this are anything maintained by
+ the &a.portmgr;, or the &a.security-officer;. No unauthorized
+ commits may ever be made to ports maintained by those
+ groups.</para>
- <para>We reserve the right to modify the maintainer's submission
- to better match existing policies and style of the Ports
- Collection without explicit blessing from the submitter.
- Also, large infrastructural changes can result in a port being
- modified without the maintainer's consent. These kinds of
- changes will never affect the port's functionality.</para>
+ <para>We reserve the right to modify the maintainer's submission
+ to better match existing policies and style of the Ports
+ Collection without explicit blessing from the submitter. Also,
+ large infrastructural changes can result in a port being
+ modified without the maintainer's consent. These kinds of
+ changes will never affect the port's functionality.</para>
- <para>The &a.portmgr; reserves the right to revoke or override
- anyone's maintainership for any reason, and the
- &a.security-officer; reserves the right to revoke or override
- maintainership for security reasons.</para>
- </sect1>
+ <para>The &a.portmgr; reserves the right to revoke or override
+ anyone's maintainership for any reason, and the
+ &a.security-officer; reserves the right to revoke or override
+ maintainership for security reasons.</para>
+ </sect1>
- <sect1 xml:id="makefile-comment">
- <title><varname>COMMENT</varname></title>
+ <sect1 xml:id="makefile-comment">
+ <title><varname>COMMENT</varname></title>
- <para>This is a one-line description of the port.
- Please respect the following rules:</para>
+ <para>This is a one-line description of the port. Please respect
+ the following rules:</para>
- <orderedlist>
- <listitem>
- <para>Try to keep the COMMENT value at no longer than 70
- characters, as this line will be used by <command>pkg
- info</command> (see &man.pkg-info.8;) to display a
- one-line summary of the port;</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Try to keep the COMMENT value at no longer than 70
+ characters, as this line will be used by
+ <command>pkg info</command> (see &man.pkg-info.8;) to
+ display a one-line summary of the port;</para>
+ </listitem>
- <listitem>
- <para>Do <emphasis>not</emphasis> include the package
- name (or version number of the software);</para>
- </listitem>
+ <listitem>
+ <para>Do <emphasis>not</emphasis> include the package name (or
+ version number of the software);</para>
+ </listitem>
- <listitem>
- <para>The comment should begin with a capital and end
- without a period;</para>
- </listitem>
+ <listitem>
+ <para>The comment should begin with a capital and end without
+ a period;</para>
+ </listitem>
- <listitem>
- <para>Do not start with an indefinite article (i.e.,
- A or An);</para>
- </listitem>
+ <listitem>
+ <para>Do not start with an indefinite article (i.e., A or
+ An);</para>
+ </listitem>
- <listitem>
- <para>Names are capitalized (for example, Apache,
- JavaScript, Perl);</para>
- </listitem>
+ <listitem>
+ <para>Names are capitalized (for example, Apache, JavaScript,
+ Perl);</para>
+ </listitem>
- <listitem>
- <para>For lists of words, use the Oxford comma (e.g.,
- green, red<emphasis>,</emphasis> and blue);</para>
- </listitem>
+ <listitem>
+ <para>For lists of words, use the Oxford comma (e.g., green,
+ red<emphasis>,</emphasis> and blue);</para>
+ </listitem>
- <listitem>
- <para>Spell check the text.</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>Spell check the text.</para>
+ </listitem>
+ </orderedlist>
- <para>Here is an example:</para>
+ <para>Here is an example:</para>
- <programlisting>COMMENT= Cat chasing a mouse all over the screen</programlisting>
+ <programlisting>COMMENT= Cat chasing a mouse all over the screen</programlisting>
- <para>The COMMENT variable should immediately follow the
- MAINTAINER variable in the
- <filename>Makefile</filename>.</para>
- </sect1>
+ <para>The COMMENT variable should immediately follow the
+ MAINTAINER variable in the <filename>Makefile</filename>.</para>
+ </sect1>
- <sect1 xml:id="makefile-portscout">
- <title><varname>PORTSCOUT</varname></title>
+ <sect1 xml:id="makefile-portscout">
+ <title><varname>PORTSCOUT</varname></title>
- <para><application>Portscout</application> is an automated
- distfile check utility for the &os; Ports Collection,
- described in detail in
- <xref linkend="distfile-survey"/>.</para>
+ <para><application>Portscout</application> is an automated
+ distfile check utility for the &os; Ports Collection,
+ described in detail in <xref linkend="distfile-survey"/>.</para>
- <para>The <varname>PORTSCOUT</varname> variable defines
- special conditions within which the
- <application>Portscout</application> distfile
- scanner should be restricted.</para>
+ <para>The <varname>PORTSCOUT</varname> variable defines special
+ conditions within which the <application>Portscout</application>
+ distfile scanner should be restricted.</para>
- <para>Situations where the <varname>PORTSCOUT</varname>
- variable should be set include:</para>
+ <para>Situations where the <varname>PORTSCOUT</varname> variable
+ should be set include:</para>
- <itemizedlist>
- <listitem>
- <para>When distfiles should be ignored, whether for
- specific versions, or specific minor revisions. For
- example, to exclude version
- <replaceable>8.2</replaceable> from distfile version
- checks because it is known to be broken, add:</para>
+ <itemizedlist>
+ <listitem>
+ <para>When distfiles should be ignored, whether for specific
+ versions, or specific minor revisions. For example, to
+ exclude version <replaceable>8.2</replaceable> from distfile
+ version checks because it is known to be broken, add:</para>
- <programlisting>PORTSCOUT= ignore:8.2</programlisting>
- </listitem>
+ <programlisting>PORTSCOUT= ignore:8.2</programlisting>
+ </listitem>
- <listitem>
- <para>When specific versions or specific major and minor
- revisions of a distfile should be checked. For
- example, if only version
- <replaceable>0.6.4</replaceable> should be monitored
- because newer versions have compatablity issues with
- &os;, add:</para>
+ <listitem>
+ <para>When specific versions or specific major and minor
+ revisions of a distfile should be checked. For example, if
+ only version <replaceable>0.6.4</replaceable> should be
+ monitored because newer versions have compatablity issues
+ with &os;, add:</para>
- <programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>
- </listitem>
+ <programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>
+ </listitem>
- <listitem>
- <para>When URLs listing the available versions differ
- from the download URLs. For example, to limit
- distfile version checks to the download page for the
- <package role="port">databases/pgtune</package>
- port, add:</para>
+ <listitem>
+ <para>When URLs listing the available versions differ from the
+ download URLs. For example, to limit distfile version
+ checks to the download page for the
+ <package role="port">databases/pgtune</package> port,
+ add:</para>
- <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting>
- </listitem>
- </itemizedlist>
- </sect1>
+ <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect1>
- <sect1 xml:id="makefile-depend">
- <title>Dependencies</title>
+ <sect1 xml:id="makefile-depend">
+ <title>Dependencies</title>
- <para>Many ports depend on other ports. This is a very
- convenient feature of most Unix-like operating systems,
- including &os;. Multiple ports can share a common dependency,
- rather than bundling that dependency with every port or
- package that needs it. There are seven variables that can be
- used to ensure that all the required bits will be on the
- user's machine. There are also some pre-supported dependency
- variables for common cases, plus a few more to control the
- behavior of dependencies.</para>
+ <para>Many ports depend on other ports. This is a very convenient
+ feature of most Unix-like operating systems, including &os;.
+ Multiple ports can share a common dependency, rather than
+ bundling that dependency with every port or package that needs
+ it. There are seven variables that can be used to ensure that
+ all the required bits will be on the user's machine. There are
+ also some pre-supported dependency variables for common cases,
+ plus a few more to control the behavior of dependencies.</para>
- <sect2>
- <title><varname>LIB_DEPENDS</varname></title>
+ <sect2>
+ <title><varname>LIB_DEPENDS</varname></title>
- <para>This variable specifies the shared libraries this port
- depends on. It is a list of
- <replaceable>lib</replaceable>:<replaceable>dir</replaceable>
- tuples where <replaceable>lib</replaceable> is the name of
- the shared library, <replaceable>dir</replaceable> is the
- directory in which to find it in case it is not available.
- For example,</para>
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of
+ <replaceable>lib</replaceable>:<replaceable>dir</replaceable>
+ tuples where <replaceable>lib</replaceable> is the name of
+ the shared library, <replaceable>dir</replaceable> is the
+ directory in which to find it in case it is not available.
+ For example,</para>
- <programlisting>LIB_DEPENDS= libjpeg.so:${PORTSDIR}/graphics/jpeg</programlisting>
+ <programlisting>LIB_DEPENDS= libjpeg.so:${PORTSDIR}/graphics/jpeg</programlisting>
- <para>will check for a shared jpeg library with any version,
- and descend into the <filename>graphics/jpeg</filename>
- subdirectory of your ports tree to build and install it if
- it is not found.</para>
+ <para>will check for a shared jpeg library with any version, and
+ descend into the <filename>graphics/jpeg</filename>
+ subdirectory of your ports tree to build and install it if it
+ is not found.</para>
- <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
- <command>pkg install</command> (see &man.pkg-install.8;)
- will automatically install it if it is not on the user's
- system.</para>
- </sect2>
+ <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
+ <command>pkg install</command> (see &man.pkg-install.8;) will
+ automatically install it if it is not on the user's
+ system.</para>
+ </sect2>
- <sect2>
- <title><varname>RUN_DEPENDS</varname></title>
+ <sect2>
+ <title><varname>RUN_DEPENDS</varname></title>
- <para>This variable specifies executables or files this port
- depends on during run-time. It is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples where <replaceable>path</replaceable> is the name of
- the executable or file, <replaceable>dir</replaceable> is
- the directory in which to find it in case it is not
- available, and <replaceable>target</replaceable> is the
- target to call in that directory. If
- <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its
- existence is tested with <command>test -e</command>;
- otherwise, it is assumed to be an executable, and
- <command>which -s</command> is used to determine if the
- program exists in the search path.</para>
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
+ tuples where <replaceable>path</replaceable> is the name of
+ the executable or file, <replaceable>dir</replaceable> is the
+ directory in which to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If <replaceable>path</replaceable> starts
+ with a slash (<literal>/</literal>), it is treated as a file
+ and its existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the search path.</para>
- <para>For example,</para>
+ <para>For example,</para>
- <programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \
+ <programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \
xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting>
- <para>will check if the file or directory
- <filename>/usr/local/news/bin/innd</filename> exists, and
- build and install it from the <filename>news/inn</filename>
- subdirectory of the ports tree if it is not found. It will
- also see if an executable called
- <command>xmlcatmgr</command> is in the search path, and
- descend into the <filename>textproc/xmlcatmgr</filename>
- subdirectory of your ports tree to build and install it if
- it is not found.</para>
+ <para>will check if the file or directory
+ <filename>/usr/local/news/bin/innd</filename> exists, and
+ build and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>xmlcatmgr</command>
+ is in the search path, and descend into the
+ <filename>textproc/xmlcatmgr</filename> subdirectory of your
+ ports tree to build and install it if it is not found.</para>
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not
- expected to be in the search path, you should use the full
- pathname.</para>
- </note>
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in the search path, you should use the full
+ pathname.</para>
+ </note>
- <note>
- <para>The official search <envar>PATH</envar> used on the
- ports build cluster is</para>
+ <note>
+ <para>The official search <envar>PATH</envar> used on the
+ ports build cluster is</para>
- <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>
- </note>
+ <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>
+ </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
- <command>pkg install</command> (see &man.pkg-install.8;)
- 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
- <varname>DEPENDS_TARGET</varname>.</para>
+ <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
+ <command>pkg install</command> (see &man.pkg-install.8;) 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 <varname>DEPENDS_TARGET</varname>.</para>
- <para>A quite common situation is when
- <varname>RUN_DEPENDS</varname> is literally the same as
- <varname>BUILD_DEPENDS</varname>, especially if ported
- software is written in a scripted language or if it requires
- the same build and run-time environment. In this
- case, it is both tempting and intuitive to directly
- assign one to the other:</para>
+ <para>A quite common situation is when
+ <varname>RUN_DEPENDS</varname> is literally the same as
+ <varname>BUILD_DEPENDS</varname>, especially if ported
+ software is written in a scripted language or if it requires
+ the same build and run-time environment. In this case, it is
+ both tempting and intuitive to directly assign one to the
+ other:</para>
- <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>
+ <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>
- <para>However, such assignment can pollute run-time
- dependencies with entries not defined in the port's original
- <varname>BUILD_DEPENDS</varname>. This happens because of
- &man.make.1;'s lazy evaluation of variable assignment.
- Consider a <filename>Makefile</filename> with
+ <para>However, such assignment can pollute run-time
+ dependencies with entries not defined in the port's original
+ <varname>BUILD_DEPENDS</varname>. This happens because of
+ &man.make.1;'s lazy evaluation of variable assignment.
+ Consider a <filename>Makefile</filename> with
+ <varname>USE_<replaceable>*</replaceable></varname> variables,
+ which are processed by <filename>ports/Mk/bsd.*.mk</filename>
+ to augment initial build dependencies. For example,
+ <literal>USES= gmake</literal> adds
+ <package role="port">devel/gmake</package> to
+ <varname>BUILD_DEPENDS</varname>. To prevent such additional
+ dependencies from polluting <varname>RUN_DEPENDS</varname>,
+ take care to assign with expansion, i.e., expand the value
+ before assigning it to the variable:</para>
+
+ <programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title><varname>BUILD_DEPENDS</varname></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <varname>RUN_DEPENDS</varname>, it
+ is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
+ tuples. For example,</para>
+
+ <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ <para>will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not found.</para>
+
+ <note>
+ <para><quote>build</quote> here means everything from
+ extraction to compilation. The dependency is checked from
+ within the <buildtarget>extract</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname></para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title><varname>FETCH_DEPENDS</varname></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
+ tuples. For example,</para>
+
+ <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ <para>will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <buildtarget>fetch</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <varname>DEPENDS_TARGET</varname>.</para>
+ </sect2>
+
+ <sect2>
+ <title><varname>EXTRACT_DEPENDS</varname></title>
+
+ <para>This variable specifies executables or files this port
+ requires for extraction. Like the previous, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
+ tuples. For example,</para>
+
+ <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ <para>will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <buildtarget>extract</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname>.</para>
+
+ <note>
+ <para>Use this variable only if the extraction does not
+ already work (the default assumes <command>gzip</command>)
+ and cannot be made to work using <varname>USE_ZIP</varname>
+ or <varname>USE_BZIP2</varname> described in
+ <xref linkend="use-vars"/>.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title><varname>PATCH_DEPENDS</varname></title>
+
+ <para>This variable specifies executables or files this port
+ requires to patch. Like the previous, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
+ tuples. For example,</para>
+
+ <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>
+
+ <para>will descend into the <filename>java/jfc</filename>
+ subdirectory of your ports tree to extract it.</para>
+
+ <para>The dependency is checked from within the
+ <buildtarget>patch</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname>.</para>
+ </sect2>
+
+ <sect2 xml:id="uses">
+ <title><varname>USES</varname></title>
+
+ <para>Parameters can be added to define different features and
+ dependencies used by the port. They are specified by adding
+ this line to the <filename>Makefile</filename>:</para>
+
+ <programlisting>USES= feature[:arguments]</programlisting>
+
+ <para>For the complete list of values, please see
+ <xref linkend="uses-values"/>.</para>
+
+ <warning>
+ <para><varname>USES</varname> cannot be assigned after
+ inclusion of <filename>bsd.port.pre.mk</filename>.</para>
+ </warning>
+ </sect2>
+
+ <sect2 xml:id="use-vars">
+ <title><varname>USE_<replaceable>*</replaceable></varname></title>
+
+ <para>Several variables exist to define common dependencies
+ shared by many ports. Their use is optional, but helps to
+ reduce the verbosity of the port
+ <filename>Makefile</filename>s. Each of them is styled as
+ <varname>USE_<replaceable>*</replaceable></varname>. These
+ variables may be used only in the port
+ <filename>Makefile</filename>s and
+ <filename>ports/Mk/bsd.*.mk</filename>. They are not meant
+ for user-settable options — use
+ <varname>PORT_OPTIONS</varname> for that purpose.</para>
+
+ <note>
+ <para>It is <emphasis>always</emphasis> incorrect to set any
+ <varname>USE_<replaceable>*</replaceable></varname> in
+ <filename>/etc/make.conf</filename>. For instance,
+ setting</para>
+
+ <programlisting>USE_GCC=X.Y</programlisting>
+
+ <para>(where X.Y is version number) would add a dependency
+ on gccXY for every port, including
+ <literal>lang/gccXY</literal> itself!</para>
+ </note>
+
+ <table frame="none">
+ <title>The
<varname>USE_<replaceable>*</replaceable></varname>
- variables, which are processed by
- <filename>ports/Mk/bsd.*.mk</filename> to augment initial
- build dependencies. For example,
- <literal>USES= gmake</literal> adds
- <package role="port">devel/gmake</package> to
- <varname>BUILD_DEPENDS</varname>. To prevent such
- additional dependencies from polluting
- <varname>RUN_DEPENDS</varname>, take care to assign with
- expansion, i.e., expand the value before assigning it to the
- variable:</para>
+ Variables</title>
- <programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting>
- </sect2>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Means</entry>
+ </row>
+ </thead>
- <sect2>
- <title><varname>BUILD_DEPENDS</varname></title>
+ <tbody>
+ <row>
+ <entry><varname>USE_BZIP2</varname></entry>
+ <entry>The port's tarballs are compressed with
+ <command>bzip2</command>.</entry>
+ </row>
- <para>This variable specifies executables or files this port
- requires to build. Like <varname>RUN_DEPENDS</varname>, it
- is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example,</para>
+ <row>
+ <entry><varname>USE_ZIP</varname></entry>
+ <entry>The port's tarballs are compressed with
+ <command>zip</command>.</entry>
+ </row>
- <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+ <row>
+ <entry><varname>USE_GCC</varname></entry>
+ <entry>The port requires GCC (<command>gcc</command> or
+ <command>g++</command>) to build. Some ports need any
+ GCC version, some require modern, recent versions. It
+ is typically set to <literal>any</literal> (in this
+ case, GCC from base would be used on versions of &os;
+ that still have it, or <literal>lang/gcc</literal>
+ port would be installed when default C/C++ compiler is
+ Clang); or <literal>yes</literal> (means always use
+ stable, modern GCC from <literal>lang/gcc</literal>
+ port). The exact version can also be specified, with
+ a value such as <literal>4.7</literal>. The minimal
+ required version can be specified as
+ <literal>4.6+</literal>. The GCC from the base system
+ is used when it satisfies the requested version,
+ otherwise an appropriate compiler in built from the
+ port, and the <varname>CC</varname> and
+ <varname>CXX</varname> variables are adjusted
+ accordingly.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <para>will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
+ <para>Variables related to <application>gmake</application> and
+ the <filename>configure</filename> script are described in
+ <xref linkend="building"/>, while
+ <application>autoconf</application>,
+ <application>automake</application> and
+ <application>libtool</application> are described in
+ <xref linkend="using-autotools"/>.
+ <application>Perl</application> related variables are
+ described in <xref linkend="using-perl"/>. X11 variables are
+ listed in <xref linkend="using-x11"/>.
+ <xref linkend="using-gnome"/> deals with GNOME and
+ <xref linkend="using-kde"/> with KDE related variables.
+ <xref linkend="using-java"/> documents Java variables, while
+ <xref linkend="using-php"/> contains information on
+ <application>Apache</application>,
+ <application>PHP</application> and PEAR modules.
+ <application>Python</application> is discussed in
+ <xref linkend="using-python"/>, while
+ <application>Ruby</application> in
+ <xref linkend="using-ruby"/>. <xref linkend="using-sdl"/>
+ provides variables used for <application>SDL</application>
+ applications and finally, <xref linkend="using-xfce"/>
+ contains information on
+ <application>Xfce</application>.</para>
+ </sect2>
- <note>
- <para><quote>build</quote> here means everything from
- extraction to compilation. The dependency is checked from
- within the <buildtarget>extract</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if
- it is the same as <varname>DEPENDS_TARGET</varname></para>
- </note>
- </sect2>
+ <sect2>
+ <title>Minimal Version of a Dependency</title>
- <sect2>
- <title><varname>FETCH_DEPENDS</varname></title>
+ <para>A minimal version of a dependency can be specified in any
+ <varname>*_DEPENDS</varname> variable except
+ <varname>LIB_DEPENDS</varname> using the following
+ syntax:</para>
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example,</para>
+ <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>
- <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+ <para>The first field contains a dependent package name, which
+ must match the entry in the package database, a comparison
+ sign, and a package version. The dependency is satisfied if
+ p5-Spiffy-0.26 or newer is installed on the machine.</para>
+ </sect2>
- <para>will check for an executable called
- <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports
- tree to build and install it if it is not found.</para>
+ <sect2>
+ <title>Notes on Dependencies</title>
- <para>The dependency is checked from within the
- <buildtarget>fetch</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it
- is the same as <varname>DEPENDS_TARGET</varname>.</para>
- </sect2>
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to
+ <literal>install</literal>. This is a user variable; it is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <varname>*_DEPENDS</varname> variables instead of redefining
+ <varname>DEPENDS_TARGET</varname>.</para>
- <sect2>
- <title><varname>EXTRACT_DEPENDS</varname></title>
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not
+ wish this to happen, define the variable
+ <varname>NOCLEANDEPENDS</varname> in your environment. This
+ may be particularly desirable if the port has something that
+ takes a long time to rebuild in its dependency list, such as
+ KDE, GNOME or Mozilla.</para>
- <para>This variable specifies executables or files this port
- requires for extraction. Like the previous, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example,</para>
+ <para>To depend on another port unconditionally, use the
+ variable <varname>${NONEXISTENT}</varname> as the first field
+ of <varname>BUILD_DEPENDS</varname> or
+ <varname>RUN_DEPENDS</varname>. Use this only when you need
+ to get the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance</para>
- <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+ <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
- <para>will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
+ <para>will always descend to the <literal>jpeg</literal> port
+ and extract it.</para>
+ </sect2>
- <para>The dependency is checked from within the
- <buildtarget>extract</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it
- is the same as <varname>DEPENDS_TARGET</varname>.</para>
+ <sect2>
+ <title>Circular Dependencies Are Fatal</title>
- <note>
- <para>Use this variable only if the extraction does not
- already work (the default assumes <command>gzip</command>)
- and cannot be made to work using
- <varname>USE_ZIP</varname> or <varname>USE_BZIP2</varname>
- described in <xref linkend="use-vars"/>.</para>
- </note>
- </sect2>
+ <important>
+ <para>Do not introduce any circular dependencies into the
+ ports tree!</para>
+ </important>
- <sect2>
- <title><varname>PATCH_DEPENDS</varname></title>
+ <para>The ports building technology does not tolerate circular
+ dependencies. If you introduce one, you will have someone,
+ somewhere in the world, whose &os; installation will break
+ almost immediately, with many others quickly to follow. These
+ can really be hard to detect; if in doubt, before you make
+ that change, make sure you have done the following:
+ <command>cd /usr/ports; make index</command>. That process
+ can be quite slow on older machines, but you may be able to
+ save a large number of people—including yourself—
+ a lot of grief in the process.</para>
+ </sect2>
- <para>This variable specifies executables or files this port
- requires to patch. Like the previous, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example,</para>
+ <sect2>
+ <title>Problems Caused by Automatic Dependencies</title>
- <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>
+ <para>Dependencies must be declared either explicitly or by
+ 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>
- <para>will descend into the <filename>java/jfc</filename>
- subdirectory of your ports tree to extract it.</para>
+ <example>
+ <title>Wrong Declaration of an Optional Dependency</title>
- <para>The dependency is checked from within the
- <buildtarget>patch</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it
- is the same as <varname>DEPENDS_TARGET</varname>.</para>
- </sect2>
-
- <sect2 xml:id="uses">
- <title><varname>USES</varname></title>
-
- <para>Parameters can be added to define different
- features and dependencies used by the port.
- They are specified by adding this line to the
- <filename>Makefile</filename>:</para>
-
- <programlisting>USES= feature[:arguments]</programlisting>
-
- <para>For the complete list of values, please see
- <xref linkend="uses-values"/>.</para>
-
- <warning>
- <para><varname>USES</varname> cannot be assigned after
- inclusion of <filename>bsd.port.pre.mk</filename>.</para>
- </warning>
- </sect2>
-
- <sect2 xml:id="use-vars">
- <title><varname>USE_<replaceable>*</replaceable></varname></title>
-
- <para>Several variables exist to define
- common dependencies shared by many ports. Their
- use is optional, but helps to reduce the verbosity of
- the port <filename>Makefile</filename>s. Each of them is
- styled as
- <varname>USE_<replaceable>*</replaceable></varname>.
- These variables may be used only in the port
- <filename>Makefile</filename>s and
- <filename>ports/Mk/bsd.*.mk</filename>. They are not meant
- for user-settable options — use
- <varname>PORT_OPTIONS</varname> for that purpose.</para>
-
- <note>
- <para>It is <emphasis>always</emphasis> incorrect to set any
- <varname>USE_<replaceable>*</replaceable></varname> in
- <filename>/etc/make.conf</filename>. For instance,
- setting</para>
-
- <programlisting>USE_GCC=X.Y</programlisting>
-
- <para>(where X.Y is version number) would add a dependency
- on gccXY for every port, including
- <literal>lang/gccXY</literal> itself!</para>
- </note>
-
- <table frame="none">
- <title>The
- <varname>USE_<replaceable>*</replaceable></varname>
- Variables</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>USE_BZIP2</varname></entry>
- <entry>The port's tarballs are compressed with
- <command>bzip2</command>.</entry>
- </row>
-
- <row>
- <entry><varname>USE_ZIP</varname></entry>
- <entry>The port's tarballs are compressed with
- <command>zip</command>.</entry>
- </row>
-
- <row>
- <entry><varname>USE_GCC</varname></entry>
- <entry>The port requires GCC (<command>gcc</command>
- or <command>g++</command>) to build. Some ports
- need any GCC version, some require modern, recent
- versions. It is typically set to
- <literal>any</literal> (in this case, GCC from base
- would be used on versions of &os; that still have
- it, or <literal>lang/gcc</literal> port would be
- installed when default C/C++ compiler is Clang); or
- <literal>yes</literal> (means always use stable,
- modern GCC from <literal>lang/gcc</literal> port).
- The exact version can also be specified, with a
- value such as <literal>4.7</literal>. The minimal
- required version can be specified as
- <literal>4.6+</literal>. The GCC from the base
- system is used when it satisfies the requested
- version, otherwise an appropriate compiler in built
- from the port, and the <varname>CC</varname> and
- <varname>CXX</varname> variables are adjusted
- accordingly.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Variables related to <application>gmake</application>
- and the <filename>configure</filename> script are described
- in <xref linkend="building"/>, while
- <application>autoconf</application>,
- <application>automake</application> and
- <application>libtool</application> are described in
- <xref linkend="using-autotools"/>.
- <application>Perl</application> related variables are
- described in <xref linkend="using-perl"/>. X11 variables
- are listed in <xref linkend="using-x11"/>.
- <xref linkend="using-gnome"/> deals with GNOME and
- <xref linkend="using-kde"/> with KDE related variables.
- <xref linkend="using-java"/> documents Java variables, while
- <xref linkend="using-php"/> contains information on
- <application>Apache</application>,
- <application>PHP</application> and PEAR modules.
- <application>Python</application> is discussed in
- <xref linkend="using-python"/>, while
- <application>Ruby</application> in
- <xref linkend="using-ruby"/>. <xref linkend="using-sdl"/>
- provides variables used for <application>SDL</application>
- applications and finally, <xref linkend="using-xfce"/>
- contains information on
- <application>Xfce</application>.</para>
- </sect2>
-
- <sect2>
- <title>Minimal Version of a Dependency</title>
-
- <para>A minimal version of a dependency can be specified in
- any <varname>*_DEPENDS</varname> variable except
- <varname>LIB_DEPENDS</varname> using the following
- syntax:</para>
-
- <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>
-
- <para>The first field contains a dependent package name, which
- must match the entry in the package database, a comparison
- sign, and a package version. The dependency is satisfied if
- p5-Spiffy-0.26 or newer is installed on the machine.</para>
- </sect2>
-
- <sect2>
- <title>Notes on Dependencies</title>
-
- <para>As mentioned above, the default target to call when a
- dependency is required is
- <buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to
- <literal>install</literal>. This is a user variable; it is
- never defined in a port's <filename>Makefile</filename>. If
- your port needs a special way to handle a dependency, use
- the <literal>:target</literal> part of the
- <varname>*_DEPENDS</varname> variables instead of redefining
- <varname>DEPENDS_TARGET</varname>.</para>
-
- <para>When you type <command>make clean</command>, its
- dependencies are automatically cleaned too. If you do not
- wish this to happen, define the variable
- <varname>NOCLEANDEPENDS</varname> in your environment. This
- may be particularly desirable if the port has something that
- takes a long time to rebuild in its dependency list, such as
- KDE, GNOME or Mozilla.</para>
-
- <para>To depend on another port unconditionally, use the
- variable <varname>${NONEXISTENT}</varname> as the first
- field of <varname>BUILD_DEPENDS</varname> or
- <varname>RUN_DEPENDS</varname>. Use this only when you need
- to get the source of the other port. You can often save
- compilation time by specifying the target too. For
- instance</para>
-
- <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
-
- <para>will always descend to the <literal>jpeg</literal> port
- and extract it.</para>
- </sect2>
-
- <sect2>
- <title>Circular Dependencies Are Fatal</title>
-
- <important>
- <para>Do not introduce any circular dependencies into the
- ports tree!</para>
- </important>
-
- <para>The ports building technology does not tolerate circular
- dependencies. If you introduce one, you will have someone,
- somewhere in the world, whose &os; installation will
- break almost immediately, with many others quickly to
- follow. These can really be hard to detect; if in doubt,
- before you make that change, make sure you have done the
- following: <command>cd /usr/ports; make index</command>.
- That process can be quite slow on older machines, but you
- may be able to save a large number of people—including
- yourself— a lot of grief in the process.</para>
- </sect2>
-
- <sect2>
- <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 other methods like automatic detection complicates
- indexing, which causes problems for port and package
- management.</para>
-
- <example>
- <title>Wrong Declaration of an Optional Dependency</title>
-
- <programlisting>.include <bsd.port.pre.mk>
+ <programlisting>.include <bsd.port.pre.mk>
.if exists(${LOCALBASE}/bin/foo)
LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar
.endif</programlisting>
- </example>
+ </example>
- <para>The problem with trying to automatically add
- dependencies is that files and settings outside an
- individual port can change at any time. For example: an
- index is built, then a batch of ports are installed. But
- one of the ports installs the tested file. The index is now
- incorrect, because an installed port unexpectedly has a new
- dependency. The index may still be wrong even after
- rebuilding if other ports also determine their need for
- dependencies based on the existence of other files.</para>
+ <para>The problem with trying to automatically add dependencies
+ is that files and settings outside an individual port can
+ change at any time. For example: an index is built, then a
+ batch of ports are installed. But one of the ports installs
+ the tested file. The index is now incorrect, because an
+ installed port unexpectedly has a new dependency. The index
+ may still be wrong even after rebuilding if other ports also
+ determine their need for dependencies based on the existence
+ of other files.</para>
- <example>
- <title>Correct Declaration of an Optional Dependency</title>
+ <example>
+ <title>Correct Declaration of an Optional Dependency</title>
- <programlisting>OPTIONS_DEFINE= BAR
+ <programlisting>OPTIONS_DEFINE= BAR
BAR_DESC= Bar support
.include <bsd.port.options.mk>
@@ -3140,74 +3093,73 @@ BAR_DESC= Bar support
.if ${PORT_OPTIONS:MBAR}
LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar
.endif</programlisting>
- </example>
+ </example>
- <para>Testing option variables is the correct method. It will
- not cause inconsistencies in the index of a batch of ports,
- provided the options were defined prior to the index build.
- Simple scripts can then be used to automate the building,
- installation, and updating of these ports and their
- packages.</para>
- </sect2>
+ <para>Testing option variables is the correct method. It will
+ not cause inconsistencies in the index of a batch of ports,
+ provided the options were defined prior to the index build.
+ Simple scripts can then be used to automate the building,
+ installation, and updating of these ports and their
+ packages.</para>
+ </sect2>
- <sect2 xml:id="use-want">
- <title><varname>USE_</varname> and
- <varname>WANT_</varname></title>
+ <sect2 xml:id="use-want">
+ <title><varname>USE_</varname> and
+ <varname>WANT_</varname></title>
- <para><varname>USE_</varname> variables are set by the port
- maintainer to define software on which this port depends. A
- port that needs Firefox would set</para>
+ <para><varname>USE_</varname> variables are set by the port
+ maintainer to define software on which this port depends. A
+ port that needs Firefox would set</para>
- <programlisting>USE_FIREFOX= yes</programlisting>
+ <programlisting>USE_FIREFOX= yes</programlisting>
- <para>Some <varname>USE_</varname> variables can accept
- version numbers or other parameters. For example, a port
- that requires Apache 2.2 would set</para>
+ <para>Some <varname>USE_</varname> variables can accept version
+ numbers or other parameters. For example, a port that
+ requires Apache 2.2 would set</para>
- <programlisting>USE_APACHE= 22</programlisting>
+ <programlisting>USE_APACHE= 22</programlisting>
- <para>For more control over dependencies in some cases,
- <varname>WANT_</varname> variables are available to more
- precisely specify what is needed. For example, consider the
- <package role="port">mail/squirrelmail</package> port.
- This port needs some PHP modules, which are listed in the
- <varname>USE_PHP</varname> variable:</para>
+ <para>For more control over dependencies in some cases,
+ <varname>WANT_</varname> variables are available to more
+ precisely specify what is needed. For example, consider the
+ <package role="port">mail/squirrelmail</package> port. This
+ port needs some PHP modules, which are listed in the
+ <varname>USE_PHP</varname> variable:</para>
- <programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting>
+ <programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting>
- <para>Those modules may be available in CLI or web versions,
- so the web version is selected with a
- <varname>WANT_</varname> variable:</para>
+ <para>Those modules may be available in CLI or web versions, so
+ the web version is selected with a
+ <varname>WANT_</varname> variable:</para>
- <programlisting>WANT_PHP_WEB= yes</programlisting>
+ <programlisting>WANT_PHP_WEB= yes</programlisting>
- <para>Available <varname>USE_</varname> and
- <varname>WANT_</varname> variables are defined in the files
- in <filename class="directory">/usr/ports/Mk</filename>.</para>
- </sect2>
- </sect1>
+ <para>Available <varname>USE_</varname> and
+ <varname>WANT_</varname> variables are defined in the files in
+ <filename class="directory">/usr/ports/Mk</filename>.</para>
+ </sect2>
+ </sect1>
- <sect1 xml:id="makefile-masterdir">
- <title><varname>MASTERDIR</varname></title>
+ <sect1 xml:id="makefile-masterdir">
+ <title><varname>MASTERDIR</varname></title>
- <para>If your port needs to build slightly different versions of
- packages by having a variable (for instance, resolution, or
- paper size) take different values, create one subdirectory per
- package to make it easier for users to see what to do, but try
- to share as many files as possible between ports. Typically
- you only need a very short <filename>Makefile</filename> in
- all but one of the directories if you use variables cleverly.
- 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>
- so the packages will have different names.</para>
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or
+ paper size) take different values, create one subdirectory per
+ package to make it easier for users to see what to do, but try
+ to share as many files as possible between ports. Typically you
+ only need a very short <filename>Makefile</filename> in all but
+ one of the directories if you use variables cleverly. 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>
+ so the packages will have different names.</para>
- <para>This will be best demonstrated by an example. This is
- part of <filename>japanese/xdvi300/Makefile</filename>;</para>
+ <para>This will be best demonstrated by an example. This is part
+ of <filename>japanese/xdvi300/Makefile</filename>;</para>
- <programlisting>PORTNAME= xdvi
+ <programlisting>PORTNAME= xdvi
PORTVERSION= 17
PKGNAMEPREFIX= ja-
PKGNAMESUFFIX= ${RESOLUTION}
@@ -3221,294 +3173,290 @@ RESOLUTION?= 300
@${FALSE}
.endif</programlisting>
- <para><package role="port">japanese/xdvi300</package> also
- has all the regular patches, package files, etc. If you type
- <command>make</command> there, it will take the default value
- for the resolution (300) and build the port normally.</para>
+ <para><package role="port">japanese/xdvi300</package> also has all
+ the regular patches, package files, etc. If you type
+ <command>make</command> there, it will take the default value
+ for the resolution (300) and build the port normally.</para>
- <para>As for other resolutions, this is the
- <emphasis>entire</emphasis>
- <filename>xdvi118/Makefile</filename>:</para>
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>:</para>
- <programlisting>RESOLUTION= 118
+ <programlisting>RESOLUTION= 118
MASTERDIR= ${.CURDIR}/../xdvi300
.include "${MASTERDIR}/Makefile"</programlisting>
- <para>(<filename>xdvi240/Makefile</filename> and
- <filename>xdvi400/Makefile</filename> are similar). The
- <varname>MASTERDIR</varname> definition tells
- <filename>bsd.port.mk</filename> that the regular set of
- subdirectories like <varname>FILESDIR</varname> and
- <varname>SCRIPTDIR</varname> are to be found under
- <filename>xdvi300</filename>. The
- <literal>RESOLUTION=118</literal> line will override the
- <literal>RESOLUTION=300</literal> line in
- <filename>xdvi300/Makefile</filename> and the port will be
- built with resolution set to 118.</para>
- </sect1>
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <varname>MASTERDIR</varname> definition tells
+ <filename>bsd.port.mk</filename> that the regular set of
+ subdirectories like <varname>FILESDIR</varname> and
+ <varname>SCRIPTDIR</varname> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect1>
- <sect1 xml:id="makefile-manpages">
- <title>Man Pages</title>
+ <sect1 xml:id="makefile-manpages">
+ <title>Man Pages</title>
- <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>
- </sect1>
+ <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>
+ </sect1>
- <sect1 xml:id="makefile-info">
- <title>Info Files</title>
+ <sect1 xml:id="makefile-info">
+ <title>Info Files</title>
- <para>If your package needs to install GNU info files, they
- should be listed in the <varname>INFO</varname> variable
- (without the trailing <literal>.info</literal>), one entry per
- document. These files are assumed to be installed to
- <filename>PREFIX/INFO_PATH</filename>.
- You can change <varname>INFO_PATH</varname> if your package
- uses a different location. However, this is not recommended.
- These entries contain just the path relative to
- <filename>PREFIX/INFO_PATH</filename>.
- For example, <package role="port">lang/gcc34</package>
- installs info files to
- <filename>PREFIX/INFO_PATH/gcc34</filename>,
- and <varname>INFO</varname> will be something like
- this:</para>
+ <para>If your package needs to install GNU info files, they should
+ be listed in the <varname>INFO</varname> variable (without the
+ trailing <literal>.info</literal>), one entry per document.
+ These files are assumed to be installed to
+ <filename>PREFIX/INFO_PATH</filename>. You can change
+ <varname>INFO_PATH</varname> if your package uses a different
+ location. However, this is not recommended. These entries
+ contain just the path relative to
+ <filename>PREFIX/INFO_PATH</filename>. For example,
+ <package role="port">lang/gcc34</package> installs info files to
+ <filename>PREFIX/INFO_PATH/gcc34</filename>, and
+ <varname>INFO</varname> will be something like this:</para>
- <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting>
+ <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting>
- <para>Appropriate installation/de-installation code will be
- automatically added to the temporary
- <filename>pkg-plist</filename> before package
- registration.</para>
- </sect1>
+ <para>Appropriate installation/de-installation code will be
+ automatically added to the temporary
+ <filename>pkg-plist</filename> before package
+ registration.</para>
+ </sect1>
- <sect1 xml:id="makefile-options">
- <title>Makefile Options</title>
+ <sect1 xml:id="makefile-options">
+ <title>Makefile Options</title>
- <para>Many applications can be built with optional or differing
- configurations. Examples include choice of natural (human)
- language, GUI versus command-line, or type of database to
- support. Users may need a different configuration than the
- default, so the ports system provides hooks the port author
- can use to control which variant will be built. Supporting
- these options properly will make users happy, and effectively
- provide two or more ports for the price of one.</para>
+ <para>Many applications can be built with optional or differing
+ configurations. Examples include choice of natural (human)
+ language, GUI versus command-line, or type of database to
+ support. Users may need a different configuration than the
+ default, so the ports system provides hooks the port author can
+ use to control which variant will be built. Supporting these
+ options properly will make users happy, and effectively provide
+ two or more ports for the price of one.</para>
- <sect2>
- <title>Knobs</title>
+ <sect2>
+ <title>Knobs</title>
- <sect3>
- <title><varname>WITH_<replaceable>*</replaceable></varname>
- and
- <varname>WITHOUT_<replaceable>*</replaceable></varname></title>
+ <sect3>
+ <title><varname>WITH_<replaceable>*</replaceable></varname>
+ and
+ <varname>WITHOUT_<replaceable>*</replaceable></varname></title>
- <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>
- file.</para>
+ <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>
+ file.</para>
- <para>When creating a port, do not make knob names specific
- to a given application. For example in Avahi port, use
- <varname>WITHOUT_MDNS</varname> instead of
- <varname>WITHOUT_AVAHI_MDNS</varname>.</para>
+ <para>When creating a port, do not make knob names specific to
+ a given application. For example in Avahi port, use
+ <varname>WITHOUT_MDNS</varname> instead of
+ <varname>WITHOUT_AVAHI_MDNS</varname>.</para>
- <note>
- <para>You should not assume that a
- <varname>WITH_<replaceable>*</replaceable></varname>
- necessarily has a corresponding
- <varname>WITHOUT_<replaceable>*</replaceable></varname>
- variable and vice versa. In general, the default is
- simply assumed.</para>
- </note>
+ <note>
+ <para>You should not assume that a
+ <varname>WITH_<replaceable>*</replaceable></varname>
+ necessarily has a corresponding
+ <varname>WITHOUT_<replaceable>*</replaceable></varname>
+ variable and vice versa. In general, the default is
+ simply assumed.</para>
+ </note>
- <note>
- <para>Unless otherwise specified, these variables are only
- tested for being set or not set, rather than being set
- to a specific value such as <literal>YES</literal>
- or <literal>NO</literal>.</para>
- </note>
+ <note>
+ <para>Unless otherwise specified, these variables are only
+ tested for being set or not set, rather than being set to
+ a specific value such as <literal>YES</literal> or
+ <literal>NO</literal>.</para>
+ </note>
- <table frame="none">
- <title>Common
- <varname>WITH_<replaceable>*</replaceable></varname> and
- <varname>WITHOUT_<replaceable>*</replaceable></varname>
- Variables</title>
+ <table frame="none">
+ <title>Common
+ <varname>WITH_<replaceable>*</replaceable></varname> and
+ <varname>WITHOUT_<replaceable>*</replaceable></varname>
+ Variables</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Means</entry>
- </row>
- </thead>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Means</entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry><varname>WITH_OPENSSL_BASE</varname></entry>
- <entry>Use the version of OpenSSL in the base
- system.</entry>
- </row>
+ <tbody>
+ <row>
+ <entry><varname>WITH_OPENSSL_BASE</varname></entry>
+ <entry>Use the version of OpenSSL in the base
+ system.</entry>
+ </row>
- <row>
- <entry><varname>WITH_OPENSSL_PORT</varname></entry>
- <entry>Installs the version of OpenSSL from
- <package role="port">security/openssl</package>,
- even if the base is up to date.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect3>
+ <row>
+ <entry><varname>WITH_OPENSSL_PORT</varname></entry>
+ <entry>Installs the version of OpenSSL from
+ <package role="port">security/openssl</package>,
+ even if the base is up to date.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect3>
- <sect3>
- <title>Knob Naming</title>
+ <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>
- file.</para>
+ <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.
- When a port has a lib-prefix in the
- <varname>PORTNAME</varname> the lib-prefix should be
- dropped in knob naming.</para>
- </sect3>
- </sect2>
+ <para>Knob names should reflect what the knob is and does.
+ When a port has a lib-prefix in the
+ <varname>PORTNAME</varname> the lib-prefix should be
+ dropped in knob naming.</para>
+ </sect3>
+ </sect2>
- <sect2>
- <title><varname>OPTIONS</varname></title>
+ <sect2>
+ <title><varname>OPTIONS</varname></title>
- <sect3>
- <title>Background</title>
+ <sect3>
+ <title>Background</title>
- <para>The <varname>OPTIONS_*</varname> variables give the
- user installing the port a dialog showing the available
- options, and then saves those options to
- <filename>/var/db/ports/${UNIQUENAME}/options</filename>.
- The next time the port is built, the options are
- reused.</para>
+ <para>The <varname>OPTIONS_*</varname> variables give the
+ user installing the port a dialog showing the available
+ options, and then saves those options to
+ <filename>/var/db/ports/${UNIQUENAME}/options</filename>.
+ The next time the port is built, the options are
+ reused.</para>
- <para>When the user runs <command>make config</command> (or
- runs <command>make build</command> for the first time),
- the framework checks for
- <filename>/var/db/ports/${UNIQUENAME}/options</filename>.
- If that file does not exist, the values of
- <varname>OPTIONS_*</varname> are used, and a dialog box is
- displayed where the options can be enabled or disabled.
- Then the <filename>options</filename> file is saved and
- the configured variables are used when building the
- port.</para>
+ <para>When the user runs <command>make config</command> (or
+ runs <command>make build</command> for the first time), the
+ framework checks for
+ <filename>/var/db/ports/${UNIQUENAME}/options</filename>.
+ If that file does not exist, the values of
+ <varname>OPTIONS_*</varname> are used, and a dialog box is
+ displayed where the options can be enabled or disabled.
+ Then the <filename>options</filename> file is saved and the
+ configured variables are used when building the port.</para>
- <para>If a new version of the port adds new
- <varname>OPTIONS</varname>, the dialog will be presented
- to the user with the saved values of old
- <varname>OPTIONS</varname> prefilled.</para>
+ <para>If a new version of the port adds new
+ <varname>OPTIONS</varname>, the dialog will be presented to
+ the user with the saved values of old
+ <varname>OPTIONS</varname> prefilled.</para>
- <para><command>make showconfig</command> shows the
- saved configuration. Use <command>make rmconfig</command>
- to remove the saved configuration.</para>
- </sect3>
+ <para><command>make showconfig</command> shows the saved
+ configuration. Use <command>make rmconfig</command>
+ to remove the saved configuration.</para>
+ </sect3>
- <sect3>
- <title>Syntax</title>
+ <sect3>
+ <title>Syntax</title>
- <para><varname>OPTIONS_DEFINE</varname> contains a list of
- <varname>OPTIONS</varname> to be used. These are
- independent of each other and are not grouped:</para>
+ <para><varname>OPTIONS_DEFINE</varname> contains a list of
+ <varname>OPTIONS</varname> to be used. These are
+ independent of each other and are not grouped:</para>
- <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting>
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting>
- <para>Once defined, <varname>OPTIONS</varname> are
- described (optional, but strongly recommended):</para>
+ <para>Once defined, <varname>OPTIONS</varname> are
+ described (optional, but strongly recommended):</para>
- <programlisting>OPT1_DESC= Describe OPT1
+ <programlisting>OPT1_DESC= Describe OPT1
OPT2_DESC= Describe OPT2
OPT3_DESC= Describe OPT3
OPT4_DESC= Describe OPT4
OPT5_DESC= Describe OPT5
OPT6_DESC= Describe OPT6</programlisting>
- <tip>
- <para><filename>ports/Mk/bsd.options.desc.mk</filename>
- has descriptions for many common
- <varname>OPTIONS</varname>; there is usually no need
- to override these.</para>
- </tip>
+ <tip>
+ <para><filename>ports/Mk/bsd.options.desc.mk</filename>
+ has descriptions for many common
+ <varname>OPTIONS</varname>; there is usually no need to
+ override these.</para>
+ </tip>
- <tip>
- <para>When describing options, view it from the
- perspective of the user: <quote>What does it do?</quote>
- and <quote>Why would I want to enable this?</quote> Do
- not just repeat the name. For example, describing the
- <literal>NLS</literal> option as
- <quote>include NLS support</quote> does not help the
- user, who can already see the option name but may not
- know what it means. Describing it as <quote>Native
- Language Support via gettext utilities</quote> is
- much more helpful.</para>
- </tip>
+ <tip>
+ <para>When describing options, view it from the
+ perspective of the user: <quote>What does it do?</quote>
+ and <quote>Why would I want to enable this?</quote>
+ Do not just repeat the name. For example, describing the
+ <literal>NLS</literal> option as
+ <quote>include NLS support</quote> does not help the user,
+ who can already see the option name but may not know what
+ it means. Describing it as <quote>Native Language Support
+ via gettext utilities</quote> is much more
+ helpful.</para>
+ </tip>
- <para><varname>OPTIONS</varname> can be grouped as radio
- choices, where only one choice from each group is
- allowed:</para>
+ <para><varname>OPTIONS</varname> can be grouped as radio
+ choices, where only one choice from each group is
+ allowed:</para>
- <programlisting>OPTIONS_SINGLE= SG1
+ <programlisting>OPTIONS_SINGLE= SG1
OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting>
- <para><varname>OPTIONS</varname> can be grouped as radio
- choices, where none or only one choice from each group
- is allowed:</para>
+ <para><varname>OPTIONS</varname> can be grouped as radio
+ choices, where none or only one choice from each group
+ is allowed:</para>
- <programlisting>OPTIONS_RADIO= RG1
+ <programlisting>OPTIONS_RADIO= RG1
OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting>
- <para><varname>OPTIONS</varname> can also be grouped as
- <quote>multiple-choice</quote> lists, where
- <emphasis>at least one</emphasis> option must be
- enabled:</para>
+ <para><varname>OPTIONS</varname> can also be grouped as
+ <quote>multiple-choice</quote> lists, where
+ <emphasis>at least one</emphasis> option must be
+ enabled:</para>
- <programlisting>OPTIONS_MULTI= MG1
+ <programlisting>OPTIONS_MULTI= MG1
OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting>
- <para><varname>OPTIONS</varname> can also be grouped as
- <quote>multiple-choice</quote> lists, where none or any
- option can be enabled:</para>
+ <para><varname>OPTIONS</varname> can also be grouped as
+ <quote>multiple-choice</quote> lists, where none or any
+ option can be enabled:</para>
- <programlisting>OPTIONS_GROUP= GG1
+ <programlisting>OPTIONS_GROUP= GG1
OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting>
- <para><varname>OPTIONS</varname> are unset by default,
- unless they are listed in
- <varname>OPTIONS_DEFAULT</varname>:</para>
+ <para><varname>OPTIONS</varname> are unset by default,
+ unless they are listed in
+ <varname>OPTIONS_DEFAULT</varname>:</para>
- <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting>
+ <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting>
- <para><varname>OPTIONS</varname> definitions must appear
- before the inclusion of
- <filename>bsd.port.options.mk</filename>. The
- <varname>PORT_OPTIONS</varname> variable can only be
- tested after the inclusion of
- <filename>bsd.port.options.mk</filename>. Inclusion of
- <filename>bsd.port.pre.mk</filename> can be used instead,
- too, and is still widely used in ports written before the
- introduction of <filename>bsd.port.options.mk</filename>.
- But be aware that some variables will not work as expected
- after the inclusion of
- <filename>bsd.port.pre.mk</filename>, typically some
- <varname>USE_*</varname> flags.</para>
+ <para><varname>OPTIONS</varname> definitions must appear
+ before the inclusion of
+ <filename>bsd.port.options.mk</filename>. The
+ <varname>PORT_OPTIONS</varname> variable can only be tested
+ after the inclusion of
+ <filename>bsd.port.options.mk</filename>. Inclusion of
+ <filename>bsd.port.pre.mk</filename> can be used instead,
+ too, and is still widely used in ports written before the
+ introduction of <filename>bsd.port.options.mk</filename>.
+ But be aware that some variables will not work as expected
+ after the inclusion of <filename>bsd.port.pre.mk</filename>,
+ typically some <varname>USE_*</varname> flags.</para>
- <example xml:id="ports-options-simple-use">
- <title>Simple Use of <varname>OPTIONS</varname></title>
+ <example xml:id="ports-options-simple-use">
+ <title>Simple Use of <varname>OPTIONS</varname></title>
- <programlisting>OPTIONS_DEFINE= FOO BAR
+ <programlisting>OPTIONS_DEFINE= FOO BAR
FOO_DESC= Enable option foo
BAR_DESC= Support feature bar
@@ -3527,21 +3475,21 @@ RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar
.endif
.include <bsd.port.mk></programlisting>
- </example>
+ </example>
- <example xml:id="ports-options-check-unset">
- <title>Check for Unset Port
- <varname>OPTIONS</varname></title>
+ <example xml:id="ports-options-check-unset">
+ <title>Check for Unset Port
+ <varname>OPTIONS</varname></title>
- <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}
+ <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}
CONFIGURE_ARGS+=--without-examples
.endif</programlisting>
- </example>
+ </example>
- <example xml:id="ports-options-practical-use">
- <title>Practical Use of <varname>OPTIONS</varname></title>
+ <example xml:id="ports-options-practical-use">
+ <title>Practical Use of <varname>OPTIONS</varname></title>
- <programlisting>OPTIONS_DEFINE= EXAMPLES
+ <programlisting>OPTIONS_DEFINE= EXAMPLES
OPTIONS_SINGLE= BACKEND
OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB
@@ -3579,120 +3527,120 @@ CONFIGURE_ARGS+= --without-examples
# Check other OPTIONS
.include <bsd.port.mk></programlisting>
- </example>
- </sect3>
+ </example>
+ </sect3>
- <sect3>
- <title>Default Options</title>
+ <sect3>
+ <title>Default Options</title>
- <para>The following options are always on by default.</para>
+ <para>The following options are always on by default.</para>
- <itemizedlist>
- <listitem>
- <para><literal>DOCS</literal> — build and install
- documentation.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><literal>DOCS</literal> — build and install
+ documentation.</para>
+ </listitem>
- <listitem>
- <para><literal>NLS</literal> — Native Language
- Support.</para>
- </listitem>
+ <listitem>
+ <para><literal>NLS</literal> — Native Language
+ Support.</para>
+ </listitem>
- <listitem>
- <para><literal>EXAMPLES</literal> — build and
- install examples.</para>
- </listitem>
+ <listitem>
+ <para><literal>EXAMPLES</literal> — build and
+ install examples.</para>
+ </listitem>
- <listitem>
- <para><literal>IPV6</literal> — IPv6 protocol
- support.</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><literal>IPV6</literal> — IPv6 protocol
+ support.</para>
+ </listitem>
+ </itemizedlist>
- <note>
- <para>There is no need to add these to
- <varname>OPTIONS_DEFAULT</varname>. To have them show
- up in the options selection dialog, however, they must
- be added to <varname>OPTIONS_DEFINE</varname>.</para>
- </note>
- </sect3>
- </sect2>
+ <note>
+ <para>There is no need to add these to
+ <varname>OPTIONS_DEFAULT</varname>. To have them show up
+ in the options selection dialog, however, they must be
+ added to <varname>OPTIONS_DEFINE</varname>.</para>
+ </note>
+ </sect3>
+ </sect2>
- <sect2>
- <title>Feature Auto-Activation</title>
+ <sect2>
+ <title>Feature Auto-Activation</title>
- <para>When using a GNU configure script, keep an eye on which
- optional features are activated by auto-detection.
- Explicitly disable optional features you do not wish to be
- used by passing respective <literal>--without-xxx</literal>
- or <literal>--disable-xxx</literal> in
- <varname>CONFIGURE_ARGS</varname>.</para>
+ <para>When using a GNU configure script, keep an eye on which
+ optional features are activated by auto-detection. Explicitly
+ disable optional features you do not wish to be used by
+ passing respective <literal>--without-xxx</literal> or
+ <literal>--disable-xxx</literal> in
+ <varname>CONFIGURE_ARGS</varname>.</para>
- <example>
- <title>Wrong Handling of an Option</title>
+ <example>
+ <title>Wrong Handling of an Option</title>
- <programlisting>.if ${PORT_OPTIONS:MFOO}
+ <programlisting>.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo
CONFIGURE_ARGS+= --enable-foo
.endif</programlisting>
- </example>
+ </example>
- <para>In the example above, imagine a library libfoo is
- installed on the system. The user does not want this
- application to use libfoo, so he toggled the option off in
- the <literal>make config</literal> dialog. But the
- application's configure script detects the library present
- in the system and includes its support in the resulting
- executable. Now when the user decides to remove libfoo from
- the system, the ports system does not protest (no dependency
- on libfoo was recorded) but the application breaks.</para>
+ <para>In the example above, imagine a library libfoo is
+ installed on the system. The user does not want this
+ application to use libfoo, so he toggled the option off in the
+ <literal>make config</literal> dialog. But the application's
+ configure script detects the library present in the system and
+ includes its support in the resulting executable. Now when
+ the user decides to remove libfoo from the system, the ports
+ system does not protest (no dependency on libfoo was recorded)
+ but the application breaks.</para>
- <example>
- <title>Correct Handling of an Option</title>
+ <example>
+ <title>Correct Handling of an Option</title>
- <programlisting>.if ${PORT_OPTIONS:MFOO}
+ <programlisting>.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo
CONFIGURE_ARGS+= --enable-foo
.else
CONFIGURE_ARGS+= --disable-foo
.endif</programlisting>
- </example>
+ </example>
- <para>In the second example, the library libfoo is explicitly
- disabled. The configure script does not enable related
- features in the application, despite library's presence in
- the system.</para>
+ <para>In the second example, the library libfoo is explicitly
+ disabled. The configure script does not enable related
+ features in the application, despite library's presence in the
+ system.</para>
- <note>
- <para>Under some circumstances, the shorthand conditional
- syntax can cause problems with complex constructs. If you
- receive errors such as
- <literal>Malformed conditional</literal>, an alternative
- syntax can be used.</para>
+ <note>
+ <para>Under some circumstances, the shorthand conditional
+ syntax can cause problems with complex constructs. If you
+ receive errors such as
+ <literal>Malformed conditional</literal>, an alternative
+ syntax can be used.</para>
- <programlisting>.if !empty(VARIABLE:MVALUE)
+ <programlisting>.if !empty(VARIABLE:MVALUE)
# as an alternative to
.if ${VARIABLE:MVALUE}</programlisting>
- </note>
- </sect2>
+ </note>
+ </sect2>
- <sect2>
- <title>Options Helpers</title>
+ <sect2>
+ <title>Options Helpers</title>
- <para>There are some macros to help simplify conditional
- values which differ based on the options set.</para>
+ <para>There are some macros to help simplify conditional values
+ which differ based on the options set.</para>
- <para>If <varname>OPTIONS_SUB</varname> is set to
- <literal>yes</literal> then each of the options added
- to <varname>OPTIONS_DEFINE</varname> will be added to
- <varname>PLIST_SUB</varname>, for example:</para>
+ <para>If <varname>OPTIONS_SUB</varname> is set to
+ <literal>yes</literal> then each of the options added to
+ <varname>OPTIONS_DEFINE</varname> will be added to
+ <varname>PLIST_SUB</varname>, for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPTIONS_SUB= yes</programlisting>
- <para> is equivalent to:</para>
+ <para> is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3702,18 +3650,18 @@ PLIST_SUB+= OPT1=""
PLIST_SUB+= OPT1="@comment "
.endif</programlisting>
- <para>If <varname>X_CONFIGURE_ENABLE</varname> is set then
- <literal>--enable-${X_CONFIGURE_ENABLE}</literal> or
- <literal>--disable-${X_CONFIGURE_ENABLE}</literal> will be
- added to <varname>CONFIGURE_ARGS</varname> depending on the
- value of the option<varname>X</varname>, for example:</para>
+ <para>If <varname>X_CONFIGURE_ENABLE</varname> is set then
+ <literal>--enable-${X_CONFIGURE_ENABLE}</literal> or
+ <literal>--disable-${X_CONFIGURE_ENABLE}</literal> will be
+ added to <varname>CONFIGURE_ARGS</varname> depending on the
+ value of the option<varname>X</varname>, for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CONFIGURE_ENABLE= test</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3723,19 +3671,18 @@ CONFIGURE_ARGS+= --enable-test
CONFIGURE_ARGS+= --disable-test
.endif</programlisting>
- <para>If <varname>X_CONFIGURE_WITH</varname> is set then
- <literal>--with-${X_CONFIGURE_WITH}</literal>
- or <literal>--without-${X_CONFIGURE_WITH}</literal> will
- be added to <varname>CONFIGURE_ARGS</varname> depending
- on the status of the option <varname>X</varname>,
- for example:</para>
+ <para>If <varname>X_CONFIGURE_WITH</varname> is set then
+ <literal>--with-${X_CONFIGURE_WITH}</literal> or
+ <literal>--without-${X_CONFIGURE_WITH}</literal> will be added
+ to <varname>CONFIGURE_ARGS</varname> depending on the status
+ of the option <varname>X</varname>, for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CONFIGURE_WITH= test</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3745,17 +3692,17 @@ CONFIGURE_ARGS+= --with-test
CONFIGURE_ARGS+= --without-test
.endif</programlisting>
- <para>If <varname>X_CONFIGURE_ON</varname> is set then its
- value will be appended to <varname>CONFIGURE_ARGS</varname>
- depending on the status of the option <varname>X</varname>,
- for example:</para>
+ <para>If <varname>X_CONFIGURE_ON</varname> is set then its
+ value will be appended to <varname>CONFIGURE_ARGS</varname>
+ depending on the status of the option <varname>X</varname>,
+ for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CONFIGURE_ON= --add-test</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3763,17 +3710,17 @@ OPT1_CONFIGURE_ON= --add-test</programlisting>
CONFIGURE_ARGS+= --add-test
.endif</programlisting>
- <para>If <varname>X_CONFIGURE_OFF</varname> is set then its
- value will be appended to <varname>CONFIGURE_ARGS</varname>
- depending on the status of the option <varname>X</varname>,
- for example:</para>
+ <para>If <varname>X_CONFIGURE_OFF</varname> is set then its
+ value will be appended to <varname>CONFIGURE_ARGS</varname>
+ depending on the status of the option <varname>X</varname>,
+ for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CONFIGURE_OFF= --no-test</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3781,17 +3728,17 @@ OPT1_CONFIGURE_OFF= --no-test</programlisting>
CONFIGURE_ARGS+= --no-test
.endif</programlisting>
- <para>If <varname>X_CMAKE_ON</varname> is set then its value
- will be appended to <varname>CMAKE_ARGS</varname> depending
- on the status of the option <varname>X</varname>, for
- example:</para>
+ <para>If <varname>X_CMAKE_ON</varname> is set then its value
+ will be appended to <varname>CMAKE_ARGS</varname> depending on
+ the status of the option <varname>X</varname>, for
+ example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CMAKE_ON= -DTEST:BOOL=true</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3799,17 +3746,17 @@ OPT1_CMAKE_ON= -DTEST:BOOL=true</programlisting>
CMAKE_ARGS+= -DTEST:BOOL=true
.endif</programlisting>
- <para>If <varname>X_CMAKE_OFF</varname> is set then its value
- will be appended to <varname>CMAKE_ARGS</varname> depending
- on the status of the option <varname>X</varname>, for
- example:</para>
+ <para>If <varname>X_CMAKE_OFF</varname> is set then its value
+ will be appended to <varname>CMAKE_ARGS</varname> depending on
+ the status of the option <varname>X</varname>, for
+ example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_CMAKE_OFF= -DTEST:BOOL=false</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3817,94 +3764,94 @@ OPT1_CMAKE_OFF= -DTEST:BOOL=false</programlisting>
CMAKE_ARGS+= -DTEST:BOOL=false
.endif</programlisting>
- <para>For any of the following variables:</para>
+ <para>For any of the following variables:</para>
- <itemizedlist>
- <listitem>
- <para><varname>ALL_TARGET</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>ALL_TARGET</varname></para>
+ </listitem>
- <listitem>
- <para><varname>CATEGORIES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>CATEGORIES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>CFLAGS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>CFLAGS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>CPPFLAGS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>CPPFLAGS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>CXXFLAGS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>CXXFLAGS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>CONFIGURE_ENV</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>CONFIGURE_ENV</varname></para>
+ </listitem>
- <listitem>
- <para><varname>DISTFILES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>DISTFILES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>EXTRA_PATCHES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>EXTRA_PATCHES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_TARGET</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>INSTALL_TARGET</varname></para>
+ </listitem>
- <listitem>
- <para><varname>LDFLAGS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>LDFLAGS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>MAKE_ARGS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>MAKE_ARGS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>MAKE_ENV</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>MAKE_ENV</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PATCH_SITES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PATCH_SITES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PATCHFILES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PATCHFILES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PLIST_FILES</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PLIST_FILES</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PLIST_DIRS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PLIST_DIRS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PLIST_DIRSTRY</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PLIST_DIRSTRY</varname></para>
+ </listitem>
- <listitem>
- <para><varname>USES</varname></para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><varname>USES</varname></para>
+ </listitem>
+ </itemizedlist>
- <para>If <varname>X_ABOVEVARIABLE</varname> is defined then
- its value will be appended to
- <varname>ABOVEVARIABLE</varname> depending on the status of
- the option <varname>X</varname>, for example:</para>
+ <para>If <varname>X_ABOVEVARIABLE</varname> is defined then
+ its value will be appended to
+ <varname>ABOVEVARIABLE</varname> depending on the status of
+ the option <varname>X</varname>, for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_USES= gmake
OPT1_CFLAGS= -DTEST</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3913,17 +3860,17 @@ USES+= gmake
CFLAGS+= -DTEST
.endif</programlisting>
- <para>If <varname>X_ABOVEVARIABLE_OFF</varname> is set then a
- flag <literal>ABOVEVARIABLE</literal> will be automatically
- set when option <literal>X</literal> is not selected. For
- example:</para>
+ <para>If <varname>X_ABOVEVARIABLE_OFF</varname> is set then a
+ flag <literal>ABOVEVARIABLE</literal> will be automatically
+ set when option <literal>X</literal> is not selected. For
+ example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_USES_OFF=gmake</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3931,49 +3878,49 @@ OPT1_USES_OFF=gmake</programlisting>
USES+= gmake
.endif</programlisting>
- <para>For any of the following dependency type:</para>
+ <para>For any of the following dependency type:</para>
- <itemizedlist>
- <listitem>
- <para><varname>PKG_DEPENDS</varname></para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>PKG_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>EXTRACT_DEPENDS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>EXTRACT_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>PATCH_DEPENDS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>PATCH_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>FETCH_DEPENDS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>FETCH_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>BUILD_DEPENDS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>BUILD_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>LIB_DEPENDS</varname></para>
- </listitem>
+ <listitem>
+ <para><varname>LIB_DEPENDS</varname></para>
+ </listitem>
- <listitem>
- <para><varname>RUN_DEPENDS</varname></para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><varname>RUN_DEPENDS</varname></para>
+ </listitem>
+ </itemizedlist>
- <para>If <varname>X_ABOVEVARIABLE</varname> is defined then
- its value will be appended to
- <varname>ABOVEVARIABLE</varname> depending on the status
- of the option <varname>X</varname>, for example:</para>
+ <para>If <varname>X_ABOVEVARIABLE</varname> is defined then
+ its value will be appended to
+ <varname>ABOVEVARIABLE</varname> depending on the status
+ of the option <varname>X</varname>, for example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
@@ -3981,457 +3928,444 @@ OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a</programlisting>
LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a
.endif</programlisting>
- <para>If <varname>X_ABOVEVARIABLE_OFF</varname> is set then a
- dependency of type <literal>ABOVEVARIABLE</literal> will be
- added when option <literal>X</literal> is not selected. For
- example:</para>
+ <para>If <varname>X_ABOVEVARIABLE_OFF</varname> is set then a
+ dependency of type <literal>ABOVEVARIABLE</literal> will be
+ added when option <literal>X</literal> is not selected. For
+ example:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
OPT1_LIB_DEPENDS_OFF= liba.so:${PORTSDIR}/devel/a</programlisting>
- <para>is equivalent to:</para>
+ <para>is equivalent to:</para>
- <programlisting>OPTIONS_DEFINE= OPT1
+ <programlisting>OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
. if ! ${PORT_OPTIONS:MOPT1}
LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a
.endif</programlisting>
- </sect2>
- </sect1>
+ </sect2>
+ </sect1>
- <sect1 xml:id="makefile-wrkdir">
- <title>Specifying the Working Directory</title>
+ <sect1 xml:id="makefile-wrkdir">
+ <title>Specifying the Working Directory</title>
- <para>Each port is extracted in to a working directory, which
- must be writable. The ports system defaults to having the
- <varname>DISTFILES</varname> unpack in to a directory called
- <literal>${DISTNAME}</literal>. In other words, if you have
- set:</para>
+ <para>Each port is extracted in to a working directory, which must
+ be writable. The ports system defaults to having the
+ <varname>DISTFILES</varname> unpack in to a directory called
+ <literal>${DISTNAME}</literal>. In other words, if you have
+ set:</para>
- <programlisting>PORTNAME= foo
+ <programlisting>PORTNAME= foo
PORTVERSION= 1.0</programlisting>
- <para>then the port's distribution files contain a top-level
- directory, <filename>foo-1.0</filename>, and the rest of the
- files are located under that directory.</para>
+ <para>then the port's distribution files contain a top-level
+ directory, <filename>foo-1.0</filename>, and the rest of the
+ files are located under that directory.</para>
- <para>There are a number of variables you can override if that
- is not the case.</para>
+ <para>There are a number of variables you can override if that is
+ not the case.</para>
- <sect2>
- <title><varname>WRKSRC</varname></title>
+ <sect2>
+ <title><varname>WRKSRC</varname></title>
- <para>The variable lists the name of the directory that is
- created when the application's distfiles are extracted. If
- our previous example extracted into a directory called
- <filename>foo</filename> (and not
- <filename>foo-1.0</filename>) you would write:</para>
+ <para>The variable lists the name of the directory that is
+ created when the application's distfiles are extracted. If
+ our previous example extracted into a directory called
+ <filename>foo</filename> (and not
+ <filename>foo-1.0</filename>) you would write:</para>
- <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting>
+ <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting>
- <para>or possibly</para>
+ <para>or possibly</para>
- <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
- </sect2>
+ <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
+ </sect2>
- <sect2>
- <title><varname>NO_WRKSUBDIR</varname></title>
+ <sect2>
+ <title><varname>NO_WRKSUBDIR</varname></title>
- <para>If the port does not extract in to a subdirectory at all
- then you should set <varname>NO_WRKSUBDIR</varname> to
- indicate that.</para>
+ <para>If the port does not extract in to a subdirectory at all
+ then you should set <varname>NO_WRKSUBDIR</varname> to
+ indicate that.</para>
- <programlisting>NO_WRKSUBDIR= yes</programlisting>
- </sect2>
- </sect1>
+ <programlisting>NO_WRKSUBDIR= yes</programlisting>
+ </sect2>
+ </sect1>
- <sect1 xml:id="conflicts">
- <title>Conflict Handling</title>
+ <sect1 xml:id="conflicts">
+ <title>Conflict Handling</title>
- <para>There are three different variables to register a conflict
- between packages and ports: <varname>CONFLICTS</varname>,
- <varname>CONFLICTS_INSTALL</varname> and
- <varname>CONFLICTS_BUILD</varname>.</para>
+ <para>There are three different variables to register a conflict
+ between packages and ports: <varname>CONFLICTS</varname>,
+ <varname>CONFLICTS_INSTALL</varname> and
+ <varname>CONFLICTS_BUILD</varname>.</para>
- <note>
- <para>The conflict variables automatically set the variable
- <varname>IGNORE</varname>, which is more fully documented
- in <xref linkend="dads-noinstall"/>.</para>
- </note>
+ <note>
+ <para>The conflict variables automatically set the variable
+ <varname>IGNORE</varname>, which is more fully documented in
+ <xref linkend="dads-noinstall"/>.</para>
+ </note>
- <para>When removing one of several conflicting ports, it is
- advisable to retain the <varname>CONFLICTS</varname> entries
- in those other ports for a few months to cater for users who
- only update once in a while.</para>
+ <para>When removing one of several conflicting ports, it is
+ advisable to retain the <varname>CONFLICTS</varname> entries in
+ those other ports for a few months to cater for users who only
+ update once in a while.</para>
- <sect2>
- <title><varname>CONFLICTS_INSTALL</varname></title>
+ <sect2>
+ <title><varname>CONFLICTS_INSTALL</varname></title>
- <para>If your package cannot coexist with other packages
- (because of file conflicts, runtime incompatibilities,
- etc.), list the other package names in the
- <varname>CONFLICTS_INSTALL</varname> variable. You can use
- shell globs like <literal>*</literal> and
- <literal>?</literal> here. Package names should be
- enumerated the same way they appear in
- <filename>/var/db/pkg</filename>. Please make sure that
- <varname>CONFLICTS_INSTALL</varname> does not match this
- port's package itself. Otherwise enforcing its installation
- with <varname>FORCE_PKG_REGISTER</varname> will no longer
- work. The CONFLICTS_INSTALL check is done after the build
- stage and prior to the install stage.</para>
- </sect2>
+ <para>If your package cannot coexist with other packages
+ (because of file conflicts, runtime incompatibilities, etc.),
+ list the other package names in the
+ <varname>CONFLICTS_INSTALL</varname> variable. You can use
+ shell globs like <literal>*</literal> and <literal>?</literal>
+ here. Package names should be enumerated the same way they
+ appear in <filename>/var/db/pkg</filename>. Please make sure
+ that <varname>CONFLICTS_INSTALL</varname> does not match this
+ port's package itself. Otherwise enforcing its installation
+ with <varname>FORCE_PKG_REGISTER</varname> will no longer
+ work. The CONFLICTS_INSTALL check is done after the build
+ stage and prior to the install stage.</para>
+ </sect2>
- <sect2>
- <title><varname>CONFLICTS_BUILD</varname></title>
+ <sect2>
+ <title><varname>CONFLICTS_BUILD</varname></title>
- <para>If your port cannot be built if a certain port is
- already installed, list the other port names in the
- <varname>CONFLICTS_BUILD</varname> variable. You can use
- shell globs like <literal>*</literal> and
- <literal>?</literal> here. Package names should be
- enumerated the same way they appear in
- <filename>/var/db/pkg</filename>. The CONFLICTS_BUILD check
- is done prior to the build stage. Build conflicts are not
- recorded in the resulting package.</para>
- </sect2>
+ <para>If your port cannot be built if a certain port is already
+ installed, list the other port names in the
+ <varname>CONFLICTS_BUILD</varname> variable. You can use
+ shell globs like <literal>*</literal> and <literal>?</literal>
+ here. Package names should be enumerated the same way they
+ appear in <filename>/var/db/pkg</filename>. The
+ CONFLICTS_BUILD check is done prior to the build stage. Build
+ conflicts are not recorded in the resulting package.</para>
+ </sect2>
- <sect2>
- <title><varname>CONFLICTS</varname></title>
+ <sect2>
+ <title><varname>CONFLICTS</varname></title>
- <para>If your port cannot be built if a certain port is
- already installed and the resulting package cannot coexist
- with the other package, list the other package name in the
- <varname>CONFLICTS</varname> variable. You can use shell
- globs like <literal>*</literal> and <literal>?</literal>
- here. Packages names should be enumerated the same way they
- appear in <filename>/var/db/pkg</filename>. Please make
- sure that <varname>CONFLICTS_INSTALL</varname> does not
- match this port's package itself. Otherwise enforcing its
- installation with <varname>FORCE_PKG_REGISTER</varname> will
- no longer work. The CONFLICTS check is done prior to the
- build stage and prior to the install stage.</para>
- </sect2>
- </sect1>
+ <para>If your port cannot be built if a certain port is already
+ installed and the resulting package cannot coexist with the
+ other package, list the other package name in the
+ <varname>CONFLICTS</varname> variable. You can use shell
+ globs like <literal>*</literal> and <literal>?</literal> here.
+ Packages names should be enumerated the same way they appear
+ in <filename>/var/db/pkg</filename>. Please make sure that
+ <varname>CONFLICTS_INSTALL</varname> does not match this
+ port's package itself. Otherwise enforcing its installation
+ with <varname>FORCE_PKG_REGISTER</varname> will no longer
+ work. The CONFLICTS check is done prior to the build stage
+ and prior to the install stage.</para>
+ </sect2>
+ </sect1>
- <sect1 xml:id="install">
- <title>Installing Files</title>
+ <sect1 xml:id="install">
+ <title>Installing Files</title>
- <sect2 xml:id="install-macros">
- <title><varname>INSTALL_*</varname> Macros</title>
+ <sect2 xml:id="install-macros">
+ <title><varname>INSTALL_*</varname> Macros</title>
- <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
- <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>
+ <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
+ <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>
- <itemizedlist>
- <listitem>
+ <itemizedlist>
+ <listitem>
- <para><varname>INSTALL_PROGRAM</varname> is a command to
- install binary executables.</para>
- </listitem>
+ <para><varname>INSTALL_PROGRAM</varname> is a command to
+ install binary executables.</para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_SCRIPT</varname> is a command to
- install executable scripts.</para>
- </listitem>
+ <listitem>
+ <para><varname>INSTALL_SCRIPT</varname> is a command to
+ install executable scripts.</para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_LIB</varname> is a command to
- install shared libraries.</para>
- </listitem>
+ <listitem>
+ <para><varname>INSTALL_LIB</varname> is a command to
+ install shared libraries.</para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_KLD</varname> is a command to
- install kernel loadable modules. Some architectures
- do not like having the modules stripped, so
- use this command instead of
- <varname>INSTALL_PROGRAM</varname>.</para>
- </listitem>
+ <listitem>
+ <para><varname>INSTALL_KLD</varname> is a command to
+ install kernel loadable modules. Some architectures
+ do not like having the modules stripped, so
+ use this command instead of
+ <varname>INSTALL_PROGRAM</varname>.</para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_DATA</varname> is a command to
- install sharable data.</para>
- </listitem>
+ <listitem>
+ <para><varname>INSTALL_DATA</varname> is a command to
+ install sharable data.</para>
+ </listitem>
- <listitem>
- <para><varname>INSTALL_MAN</varname> is a command to
- install manpages and other documentation (it does not
- compress anything).</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><varname>INSTALL_MAN</varname> is a command to
+ install manpages and other documentation (it does not
+ compress anything).</para>
+ </listitem>
+ </itemizedlist>
- <para>These are basically the <command>install</command>
- command with all the appropriate flags.</para>
- </sect2>
+ <para>These are basically the <command>install</command>
+ command with all the appropriate flags.</para>
+ </sect2>
- <sect2 xml:id="install-strip">
- <title>Stripping Binaries and Shared Libraries</title>
+ <sect2 xml:id="install-strip">
+ <title>Stripping Binaries and Shared Libraries</title>
- <para>Do not strip binaries manually unless you have to. All
- binaries should be stripped, but the
- <varname>INSTALL_PROGRAM</varname> macro will install and
- strip a binary at the same time (see the next section). The
- <varname>INSTALL_LIB</varname> macro does the same thing to
- shared libraries.</para>
+ <para>Do not strip binaries manually unless you have to. All
+ binaries should be stripped, but the
+ <varname>INSTALL_PROGRAM</varname> macro will install and
+ strip a binary at the same time (see the next section). The
+ <varname>INSTALL_LIB</varname> macro does the same thing to
+ shared libraries.</para>
- <para>If you need to strip a file, but wish to use neither
- <varname>INSTALL_PROGRAM</varname> nor
- <varname>INSTALL_LIB</varname> macros,
- <varname>${STRIP_CMD}</varname> will strip your program or
- shared library. This is typically done within the
- <buildtarget>post-install</buildtarget> target. For
- example:</para>
+ <para>If you need to strip a file, but wish to use neither
+ <varname>INSTALL_PROGRAM</varname> nor
+ <varname>INSTALL_LIB</varname> macros,
+ <varname>${STRIP_CMD}</varname> will strip your program or
+ shared library. This is typically done within the
+ <buildtarget>post-install</buildtarget> target. For
+ example:</para>
- <programlisting>post-install:
+ <programlisting>post-install:
${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting>
- <para>When multiple files need to be stripped:</para>
+ <para>When multiple files need to be stripped:</para>
- <programlisting>post-install:
+ <programlisting>post-install:
.for l in geometry media body track world
${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0
.endfor</programlisting>
- <para>Use &man.file.1; on a file to determine if it has been
- stripped. Binaries are reported by &man.file.1; as
- <literal>stripped</literal>, or
- <literal>not stripped</literal>. Additionally, &man.strip.1;
- will detect programs that have already been stripped and
- exit cleanly.</para>
- </sect2>
+ <para>Use &man.file.1; on a file to determine if it has been
+ stripped. Binaries are reported by &man.file.1; as
+ <literal>stripped</literal>, or
+ <literal>not stripped</literal>. Additionally, &man.strip.1;
+ will detect programs that have already been stripped and exit
+ cleanly.</para>
+ </sect2>
- <sect2 xml:id="install-copytree">
- <title>Installing a Whole Tree of Files</title>
+ <sect2 xml:id="install-copytree">
+ <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
- <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>,
- <varname>DATADIR</varname>, and other path variables must
- always be prepended with <varname>STAGEDIR</varname> to
- respect staging (see <xref linkend="staging"/>).</para>
+ <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
+ <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>,
+ <varname>DATADIR</varname>, and other path variables 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
- they guarantee proper file ownership and permissions on
- target files. The first macro,
- <varname>COPYTREE_BIN</varname>, will set all the installed
- files to be executable, thus being suitable for installing
- into <filename>PREFIX/bin</filename>.
- The second macro, <varname>COPYTREE_SHARE</varname>, does
- not set executable permissions on files, and is therefore
- suitable for installing files under
- <filename>PREFIX/share</filename>
- target.</para>
+ <para>Two macros exist for this situation. The advantage of
+ using these macros instead of <command>cp</command> is that
+ they guarantee proper file ownership and permissions on target
+ files. The first macro, <varname>COPYTREE_BIN</varname>, will
+ set all the installed files to be executable, thus being
+ suitable for installing into <filename>PREFIX/bin</filename>.
+ The second macro, <varname>COPYTREE_SHARE</varname>, does not
+ set executable permissions on files, and is therefore suitable
+ for installing files under <filename>PREFIX/share</filename>
+ target.</para>
- <programlisting>post-install:
+ <programlisting>post-install:
${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
(cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})</programlisting>
- <para>This example will install the contents of
- <filename>examples</filename> directory in the vendor
- distfile to the proper examples location of your
- port.</para>
+ <para>This example will install the contents of
+ <filename>examples</filename> directory in the vendor distfile
+ to the proper examples location of your port.</para>
- <programlisting>post-install:
+ <programlisting>post-install:
${MKDIR} ${STAGEDIR}${DATADIR}/summer
(cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting>
- <para>And this example will install the data of summer months
- to the <filename>summer</filename> subdirectory of a
- <filename>DATADIR</filename>.</para>
+ <para>And this example will install the data of summer months to
+ the <filename>summer</filename> subdirectory of a
+ <filename>DATADIR</filename>.</para>
- <para>Additional <command>find</command> arguments can be
- passed via the third argument to the
- <varname>COPYTREE_*</varname> macros. For example, to
- install all files from the first example except Makefiles,
- one can use the following command.</para>
+ <para>Additional <command>find</command> arguments can be
+ passed via the third argument to the
+ <varname>COPYTREE_*</varname> macros. For example, to install
+ all files from the first example except Makefiles, one can use
+ the following command.</para>
- <programlisting>post-install:
+ <programlisting>post-install:
${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
(cd ${WRKSRC}/examples && \
${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
- (<varname>PORTEXAMPLES</varname>), the
- <literal>%%PORTDOCS%%</literal> or
- <literal>%%PORTEXAMPLES%%</literal> prefixes must be
- prepended in <filename>pkg-plist</filename>.</para>
- </sect2>
+ <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
+ (<varname>PORTEXAMPLES</varname>), the
+ <literal>%%PORTDOCS%%</literal> or
+ <literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended
+ in <filename>pkg-plist</filename>.</para>
+ </sect2>
- <sect2 xml:id="install-documentation">
- <title>Install Additional Documentation</title>
+ <sect2 xml:id="install-documentation">
+ <title>Install Additional Documentation</title>
- <para>If your software has some documentation other than the
- standard man and info pages that you think is useful for the
- user, install it under
- <filename>PREFIX/share/doc</filename>.
- This can be done, like the previous item, in the
- <buildtarget>post-install</buildtarget> target.</para>
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under <filename>PREFIX/share/doc</filename>.
+ This can be done, like the previous item, in the
+ <buildtarget>post-install</buildtarget> target.</para>
- <para>Create a new directory for your port. The directory
- name should reflect what the port is. This usually means
- <varname>PORTNAME</varname>. However, if you think the user
- might want different versions of the port to be installed at
- the same time, you can use the whole
- <varname>PKGNAME</varname>.</para>
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means
+ <varname>PORTNAME</varname>. However, if you think the user
+ might want different versions of the port to be installed at
+ the same time, you can use the whole
+ <varname>PKGNAME</varname>.</para>
- <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>
+ <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>
- <programlisting>post-install:
+ <programlisting>post-install:
${MKDIR} ${STAGEDIR}${DOCSDIR}
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}</programlisting>
- <para>Here are some handy variables and how they are expanded
- by default when used in the
- <filename>Makefile</filename>:</para>
+ <para>Here are some handy variables and how they are expanded by
+ default when used in the <filename>Makefile</filename>:</para>
- <itemizedlist>
- <listitem>
- <para><varname>DATADIR</varname> gets expanded to
- <filename>PREFIX/share/PORTNAME</filename>.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><varname>DATADIR</varname> gets expanded to
+ <filename>PREFIX/share/PORTNAME</filename>.</para>
+ </listitem>
- <listitem>
- <para><varname>DATADIR_REL</varname> gets expanded to
- <filename>share/PORTNAME</filename>.</para>
- </listitem>
+ <listitem>
+ <para><varname>DATADIR_REL</varname> gets expanded to
+ <filename>share/PORTNAME</filename>.</para>
+ </listitem>
- <listitem>
- <para><varname>DOCSDIR</varname> gets expanded to
- <filename>PREFIX/share/doc/PORTNAME</filename>.</para>
- </listitem>
+ <listitem>
+ <para><varname>DOCSDIR</varname> gets expanded to
+ <filename>PREFIX/share/doc/PORTNAME</filename>.</para>
+ </listitem>
- <listitem>
- <para><varname>DOCSDIR_REL</varname> gets expanded to
- <filename>share/doc/PORTNAME</filename>.</para>
- </listitem>
+ <listitem>
+ <para><varname>DOCSDIR_REL</varname> gets expanded to
+ <filename>share/doc/PORTNAME</filename>.</para>
+ </listitem>
- <listitem>
- <para><varname>EXAMPLESDIR</varname> gets expanded to
- <filename>PREFIX/share/examples/PORTNAME</filename>.</para>
- </listitem>
+ <listitem>
+ <para><varname>EXAMPLESDIR</varname> gets expanded to
+ <filename>PREFIX/share/examples/PORTNAME</filename>.</para>
+ </listitem>
- <listitem>
- <para><varname>EXAMPLESDIR_REL</varname> gets expanded to
- <filename>share/examples/PORTNAME</filename>.</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><varname>EXAMPLESDIR_REL</varname> gets expanded to
+ <filename>share/examples/PORTNAME</filename>.</para>
+ </listitem>
+ </itemizedlist>
- <note>
- <para>The <literal>DOCS</literal> option only controls
- additional documentation installed in
- <varname>DOCSDIR</varname>. It does not apply to standard
- man pages and info pages. Things installed in
- <varname>DATADIR</varname> and
- <varname>EXAMPLESDIR</varname> are controlled by
- <literal>DATA</literal> and <literal>EXAMPLES</literal>
- options, respectively.</para>
- </note>
+ <note>
+ <para>The <literal>DOCS</literal> option only controls
+ additional documentation installed in
+ <varname>DOCSDIR</varname>. It does not apply to standard
+ man pages and info pages. Things installed in
+ <varname>DATADIR</varname> and
+ <varname>EXAMPLESDIR</varname> are controlled by
+ <literal>DATA</literal> and <literal>EXAMPLES</literal>
+ options, respectively.</para>
+ </note>
- <para>These variables are exported to
- <varname>PLIST_SUB</varname>. Their values will appear
- there as pathnames relative to
- <filename>PREFIX</filename> if possible.
- That is,
- <filename>share/doc/PORTNAME</filename>
- will be substituted for <literal>%%DOCSDIR%%</literal> in
- the packing list by default, and so on. (See more on
- <filename>pkg-plist</filename> substitution
- <link linkend="plist-sub">here</link>.)</para>
+ <para>These variables are exported to
+ <varname>PLIST_SUB</varname>. Their values will appear there
+ as pathnames relative to <filename>PREFIX</filename> if
+ possible. That is, <filename>share/doc/PORTNAME</filename>
+ will be substituted for <literal>%%DOCSDIR%%</literal> in the
+ packing list by default, and so on. (See more on
+ <filename>pkg-plist</filename> substitution
+ <link linkend="plist-sub">here</link>.)</para>
- <para>All conditionally installed documentation files and
- directories should be included in
- <filename>pkg-plist</filename> with the
- <literal>%%PORTDOCS%%</literal> prefix, for example:</para>
+ <para>All conditionally installed documentation files and
+ directories should be included in
+ <filename>pkg-plist</filename> with the
+ <literal>%%PORTDOCS%%</literal> prefix, for example:</para>
- <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
+ <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
%%PORTDOCS%%%%DOCSDIR%%/CONTACT
%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>
- <para>As an alternative to enumerating the documentation files
- in <filename>pkg-plist</filename>, a port can set the
- variable <varname>PORTDOCS</varname> to a list of file names
- and shell glob patterns to add to the final packing list.
- The names will be relative to <varname>DOCSDIR</varname>.
- Therefore, a port that utilizes <varname>PORTDOCS</varname>
- and uses a non-default location for its documentation should
- set <varname>DOCSDIR</varname> accordingly. If a directory
- is listed in <varname>PORTDOCS</varname> or matched by a
- glob pattern from this variable, the entire subtree of
- contained files and directories will be registered in the
- final packing list. If the <literal>DOCS</literal> option
- has been unset then files and directories listed in
- <varname>PORTDOCS</varname> would not be installed or added
- to port packing list. Installing the documentation at
- <varname>PORTDOCS</varname> as shown above remains up to the
- port itself. A typical example of utilizing
- <varname>PORTDOCS</varname> looks as follows:</para>
+ <para>As an alternative to enumerating the documentation files
+ in <filename>pkg-plist</filename>, a port can set the variable
+ <varname>PORTDOCS</varname> to a list of file names and shell
+ glob patterns to add to the final packing list. The names
+ will be relative to <varname>DOCSDIR</varname>. Therefore, a
+ port that utilizes <varname>PORTDOCS</varname> and uses a
+ non-default location for its documentation should set
+ <varname>DOCSDIR</varname> accordingly. If a directory is
+ listed in <varname>PORTDOCS</varname> or matched by a glob
+ pattern from this variable, the entire subtree of contained
+ files and directories will be registered in the final packing
+ list. If the <literal>DOCS</literal> option has been unset
+ then files and directories listed in
+ <varname>PORTDOCS</varname> would not be installed or added to
+ port packing list. Installing the documentation at
+ <varname>PORTDOCS</varname> as shown above remains up to the
+ port itself. A typical example of utilizing
+ <varname>PORTDOCS</varname> looks as follows:</para>
- <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting>
+ <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting>
- <note>
- <para>The equivalents of <varname>PORTDOCS</varname> for
- files installed under <varname>DATADIR</varname> and
- <varname>EXAMPLESDIR</varname> are
- <varname>PORTDATA</varname> and
- <varname>PORTEXAMPLES</varname>, respectively.</para>
+ <note>
+ <para>The equivalents of <varname>PORTDOCS</varname> for files
+ installed under <varname>DATADIR</varname> and
+ <varname>EXAMPLESDIR</varname> are
+ <varname>PORTDATA</varname> and
+ <varname>PORTEXAMPLES</varname>, respectively.</para>
- <para>The contents of <filename>pkg-message</filename>
- are displayed upon installation. See
- <link linkend="porting-message">the section on using
- <filename>pkg-message</filename></link> for details.
- <filename>pkg-message</filename> does not need to be
- added to <filename>pkg-plist</filename>.</para>
- </note>
- </sect2>
+ <para>The contents of <filename>pkg-message</filename> are
+ displayed upon installation. See
+ <link linkend="porting-message">the section on using
+ <filename>pkg-message</filename></link> for details.
+ <filename>pkg-message</filename> does not need to be added
+ to <filename>pkg-plist</filename>.</para>
+ </note>
+ </sect2>
- <sect2 xml:id="install-subdirs">
- <title>Subdirectories Under <varname>PREFIX</varname></title>
-
- <para>Try to let the port put things in the right
- subdirectories of <varname>PREFIX</varname>. Some ports
- lump everything and put it in the subdirectory with the
- port's name, which is incorrect. Also, many ports put
- everything except binaries, header files and manual pages in
- a subdirectory of <filename>lib</filename>, which does not
- work well with the BSD paradigm. Many of the files should
- be moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers),
- <filename>info</filename> (documentation for info browser)
- or <filename>share</filename> (architecture independent
- files). See &man.hier.7; for details; the rules governing
- <filename>/usr</filename> pretty much apply to
- <filename>/usr/local</filename> too. The exception are
- ports dealing with USENET <quote>news</quote>. They may use
- <filename>PREFIX/news</filename> as a
- destination for their files.</para>
- </sect2>
- </sect1>
- </chapter>
+ <sect2 xml:id="install-subdirs">
+ <title>Subdirectories Under <varname>PREFIX</varname></title>
+ <para>Try to let the port put things in the right subdirectories
+ of <varname>PREFIX</varname>. Some ports lump everything and
+ put it in the subdirectory with the port's name, which is
+ incorrect. Also, many ports put everything except binaries,
+ header files and manual pages in a subdirectory of
+ <filename>lib</filename>, which does not work well with the
+ BSD paradigm. Many of the files should be moved to one of the
+ following: <filename>etc</filename> (setup/configuration
+ files), <filename>libexec</filename> (executables started
+ internally), <filename>sbin</filename> (executables for
+ superusers/managers), <filename>info</filename> (documentation
+ for info browser) or <filename>share</filename> (architecture
+ independent files). See &man.hier.7; for details; the rules
+ governing <filename>/usr</filename> pretty much apply to
+ <filename>/usr/local</filename> too. The exception are ports
+ dealing with USENET <quote>news</quote>. They may use
+ <filename>PREFIX/news</filename> as a destination for their
+ files.</para>
+ </sect2>
+ </sect1>
+</chapter>