Differential D643 Diff 1277 en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>		<?xml version="1.0" encoding="iso-8859-1"?>
<!--		<!--
The FreeBSD Documentation Project		The FreeBSD Documentation Project

$FreeBSD$		$FreeBSD$
-->		-->
<chapter xmlns="http://docbook.org/ns/docbook"		<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"		xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="makefiles">		xml:id="makefiles">

<title>Configuring the Makefile</title>		<title>Configuring the Makefile</title>

<para>Configuring the <filename>Makefile</filename> is pretty		<para>Configuring the <filename>Makefile</filename> is pretty
simple, and again we suggest that you look at existing examples		simple, and again we suggest looking at existing examples
before starting. Also, there is a		before starting. Also, there is a
<link linkend="porting-samplem">sample Makefile</link> in this		<link linkend="porting-samplem">sample Makefile</link> in this
handbook, so take a look and please follow the ordering of		handbook, so take a look and please follow the ordering of
variables and sections in that template to make your port easier		variables and sections in that template to make the port easier
for others to read.</para>		for others to read.</para>

<para>Now, consider the following problems in sequence as you		<para>Now, consider these problems in sequence during the
design your new <filename>Makefile</filename>:</para>		design the new <filename>Makefile</filename>:</para>
		wblockUnsubmitted Not Done Inline Actions "Now" is not needed. wblock: "Now" is not needed.
		wblockUnsubmitted Not Done Inline Actions design of the new wblock: design of the new

<sect1 xml:id="makefile-source">		<sect1 xml:id="makefile-source">
<title>The Original Source</title>		<title>The Original Source</title>

<para>Does it live in <varname>DISTDIR</varname> as a standard		<para>Does it live in <varname>DISTDIR</varname> as a standard
<command>gzip</command>ped tarball named something like		<command>gzip</command>ped tarball named something like
<filename>foozolix-1.2.tar.gz</filename>? If so, you can go on		<filename>foozolix-1.2.tar.gz</filename>? If so, go on
to the next step. If not, you should look at overriding any of		to the next step. If not, look at overriding any of
		wblockUnsubmitted Not Done Inline Actions "If not, the distribution file format might require overriding one or more of" wblock: "If not, the distribution file format might require overriding one or more of"
the <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,		<varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
<varname>EXTRACT_CMD</varname>,		<varname>EXTRACT_CMD</varname>,
<varname>EXTRACT_BEFORE_ARGS</varname>,		<varname>EXTRACT_BEFORE_ARGS</varname>,
<varname>EXTRACT_AFTER_ARGS</varname>,		<varname>EXTRACT_AFTER_ARGS</varname>,
<varname>EXTRACT_SUFX</varname>, or <varname>DISTFILES</varname>		<varname>EXTRACT_SUFX</varname>, or <varname>DISTFILES</varname>,
variables, depending on how alien a format your port's		depending on how alien a format the port's
		wblockUnsubmitted Not Done Inline Actions End the sentence after DISTFILES: ..., or <varname>DISTFILES</varname>.</para> and delete the next two lines. wblock: End the sentence after DISTFILES: ..., or <varname>DISTFILES</varname>.</para> and delete the…
distribution file is.</para>		distribution file is.</para>

<para>In the worst case, you can simply create your own		<para>In the worst case, create a custom
<buildtarget>do-extract</buildtarget> target to override the		<buildtarget>do-extract</buildtarget> target to override the
default, though this should be rarely, if ever,		default, though this is rarely, if ever,
		wblockUnsubmitted Not Done Inline Actions Break this compound sentence into two sentences: "default. This is rarely necessary.</para>" wblock: Break this compound sentence into two sentences: "default. This is rarely necessary.</para>"
necessary.</para>		necessary.</para>
		wblockUnsubmitted Not Done Inline Actions The "if ever" is redundant but can be kept if you feel it is needed. (It's a subset of "rarely".) wblock: The "if ever" is redundant but can be kept if you feel it is needed. (It's a subset of…
		matAuthorUnsubmitted Not Done Inline Actions Yes, I'll keep it, people should almost never need to do that :-) mat: Yes, I'll keep it, people should almost never need to do that :-)
</sect1>		</sect1>

<sect1 xml:id="makefile-naming">		<sect1 xml:id="makefile-naming">
<title>Naming</title>		<title>Naming</title>

<para>The first part of the port's <filename>Makefile</filename>		<para>The first part of the port's <filename>Makefile</filename>
names the port, describes its version number, and lists it in		names the port, describes its version number, and lists it in
the correct category.</para>		the correct category.</para>

<sect2 xml:id="makefile-portname">		<sect2 xml:id="makefile-portname">
<title><varname>PORTNAME</varname> and		<title><varname>PORTNAME</varname> and
<varname>PORTVERSION</varname></title>		<varname>PORTVERSION</varname></title>

<para>You should set <varname>PORTNAME</varname> to the base		<para>Set <varname>PORTNAME</varname> to the base
name of your port, and <varname>PORTVERSION</varname> to the		name of the port, and <varname>PORTVERSION</varname> to the
version number of the port.</para>		version number of the port.</para>

<warning>		<important>
<para>Package name should be unique among all of the ports		<para>Package name must be unique among all of the ports
		wblockUnsubmitted Not Done Inline Actions s/Package/The package/ wblock: s/Package/The package/
tree, check that there is not already a port with the same		tree, check that there is not already a port with the same
		wblockUnsubmitted Not Done Inline Actions s/tree, check/tree. Make sure/ wblock: s/tree, check/tree. Make sure/
<varname>PORTNAME</varname> and if there is add one of <link		<varname>PORTNAME</varname> and if there is add one of <link
linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>		linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
or <varname>PKGNAMESUFFIX</varname></link>.</para>		or <varname>PKGNAMESUFFIX</varname></link>.</para>
</warning>		</important>
</sect2>		</sect2>

<sect2 xml:id="makefile-naming-revepoch">		<sect2 xml:id="makefile-naming-revepoch">
<title><varname>PORTREVISION</varname> and		<title><varname>PORTREVISION</varname> and
<varname>PORTEPOCH</varname></title>		<varname>PORTEPOCH</varname></title>

<sect3 xml:id="makefile-portrevision">		<sect3 xml:id="makefile-portrevision">
<title><varname>PORTREVISION</varname></title>		<title><varname>PORTREVISION</varname></title>

<para>The <varname>PORTREVISION</varname> variable is a		<para><varname>PORTREVISION</varname> is a
monotonically increasing value which is reset to 0 with		monotonically increasing value which is reset to 0 with
every increase of <varname>PORTVERSION</varname> (i.e.,		every increase of <varname>PORTVERSION</varname> (that is,
		wblockUnsubmitted Not Done Inline Actions This whole paragraph is full of asides. <para><varname>PORTREVISION</varname> is a monotonically increasing value which is reset to 0 with every increase of <varname>PORTVERSION</varname>, typically every time there is a new official vendor release. If <varname>PORTREVISION</varname> is non-zero, the value is appended to the package name. Changes to <varname>PORTREVISION</varname> are used by automated tools like &man.pkg-version.8; to determine that a new package is available.</para> wblock: This whole paragraph is full of asides. <para><varname>PORTREVISION</varname> is a…
every time a new official vendor release is made), and		every time a new official vendor release is made), and
appended to the package name if non-zero. Changes to		appended to the package name if non-zero. Changes to
<varname>PORTREVISION</varname> are used by automated tools		<varname>PORTREVISION</varname> are used by automated tools
(e.g., <command>pkg version</command>, see		(for example, <command>pkg version</command>, see
&man.pkg-version.8;) to highlight the fact that a new		&man.pkg-version.8;) to highlight the fact that a new
package is available.</para>		package is available.</para>

<para><varname>PORTREVISION</varname> should be increased each		<para><varname>PORTREVISION</varname> must be increased each
time a change is made to the port that changes the generated		time a change is made to the port that changes the generated
package in any way. That includes changes that only affect		package in any way. That includes changes that only affect
a package built with non-default		a package built with non-default
<link linkend="makefile-options">options</link>.</para>		<link linkend="makefile-options">options</link>.</para>

<para>Examples of when <varname>PORTREVISION</varname>		<para>Examples of when <varname>PORTREVISION</varname>
should be bumped:</para>		must be bumped:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>Addition of patches to correct security		<para>Addition of patches to correct security
vulnerabilities, bugs, or to add new functionality to		vulnerabilities, bugs, or to add new functionality to
the port.</para>		the port.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Changes to the port <filename>Makefile</filename> to		<para>Changes to the port <filename>Makefile</filename> to
enable or disable compile-time options in the		enable or disable compile-time options in the
package.</para>		package.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Changes in the packing list or the install-time		<para>Changes in the packing list or the install-time
		wblockUnsubmitted Not Done Inline Actions <para>Changes in the packing list or the install-time behavior of the package. For example, a change to a script which generates initial data for the package, like &man.ssh.1; host keys.</para> wblock: <para>Changes in the packing list or the install-time behavior of the package. For example, a…
behavior of the package (e.g., change to a script which		behavior of the package (for example, change to a script which
generates initial data for the package, like ssh host		generates initial data for the package, like ssh host
keys).</para>		keys).</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Version bump of a port's shared library dependency		<para>Version bump of a port's shared library dependency
(in this case, someone trying to install the old package		(in this case, someone trying to install the old package
after installing a newer version of the dependency will		after installing a newer version of the dependency will
fail since it will look for the old libfoo.x instead of		fail since it will look for the old libfoo.x instead of
libfoo.(x+1)).</para>		libfoo.(x+1)).</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Silent changes to the port distfile which have		<para>Silent changes to the port distfile which have
significant functional differences, i.e., changes to the		significant functional differences, that is, changes to the
		wblockUnsubmitted Not Done Inline Actions Break compound sentence: s/differences, that is,/differences. For example,/ wblock: Break compound sentence: s/differences, that is,/differences. For example,/
distfile requiring a correction to		distfile requiring a correction to
<filename>distinfo</filename> with no corresponding		<filename>distinfo</filename> with no corresponding
change to <varname>PORTVERSION</varname>, where a		change to <varname>PORTVERSION</varname>, where a
<command>diff -ru</command> of the old and new versions		<command>diff -ru</command> of the old and new versions
shows non-trivial changes to the code.</para>		shows non-trivial changes to the code.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

Show All 11 Lines	<listitem>
<para>Changes to <varname>MASTER_SITES</varname> or other		<para>Changes to <varname>MASTER_SITES</varname> or other
functional changes to the port which do not affect the		functional changes to the port which do not affect the
resulting package.</para>		resulting package.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Trivial patches to the distfile such as correction		<para>Trivial patches to the distfile such as correction
of typos, which are not important enough that users of		of typos, which are not important enough that users of
the package should go to the trouble of		the package have to go to the trouble of
upgrading.</para>		upgrading.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Build fixes which cause a package to become		<para>Build fixes which cause a package to become
compilable where it was previously failing (as long as		compilable where it was previously failing (as long as
the changes do not introduce any functional change on		the changes do not introduce any functional change on
any other platforms on which the port did previously		any other platforms on which the port did previously
build). Since <varname>PORTREVISION</varname> reflects		build). Since <varname>PORTREVISION</varname> reflects
the content of the package, if the package was not		the content of the package, if the package was not
previously buildable then there is no need to increase		previously buildable then there is no need to increase
<varname>PORTREVISION</varname> to mark a change.</para>		<varname>PORTREVISION</varname> to mark a change.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<para>A rule of thumb is to ask yourself whether a change		<para>A rule of thumb is to decide whether a change
committed to a port is something which everyone would		committed to a port is something which some people would
		wblockUnsubmitted Not Done Inline Actions This paragraph would also benefit from breaking out the asides into separate sentences. wblock: This paragraph would also benefit from breaking out the asides into separate sentences.
benefit from having (either because of an enhancement, fix,		benefit from having (either because of an enhancement, fix,
or by virtue that the new package will actually work at		or by virtue that the new package will actually work at
all), and weigh that against that fact that it will cause		all), and weigh that against that fact that it will cause
everyone who regularly updates their ports tree to be		everyone who regularly updates their ports tree to be
compelled to update. If yes, the		compelled to update. If yes,
<varname>PORTREVISION</varname> should be bumped.</para>		<varname>PORTREVISION</varname> must be bumped.</para>

		<note>
		<para>People using binary packages will
		<emphasis>never</emphasis> see the update if
		<varname>PORTREVISION</varname> is not bumped because the
		wblockUnsubmitted Not Done Inline Actions Break sentences up: s/bumped because/bumped. Without increasing <varname>PORTREVISION</varname>, the/ wblock: Break sentences up: s/bumped because/bumped. Without increasing…
		package builders have no way to detect the change and
		thus, will not rebuild the package.</para>
		</note>
</sect3>		</sect3>

<sect3 xml:id="makefile-portepoch">		<sect3 xml:id="makefile-portepoch">
<title><varname>PORTEPOCH</varname></title>		<title><varname>PORTEPOCH</varname></title>

<para>From time to time a software vendor or &os; porter will		<para>From time to time a software vendor or &os; porter will
do something silly and release a version of their software		do something silly and release a version of their software
which is actually numerically less than the previous		which is actually numerically less than the previous
Show All 11 Lines	<tip>
<screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>		<screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
></screen>		></screen>

<para>The <literal>></literal> output indicates that		<para>The <literal>></literal> output indicates that
version 0.031 is considered greater than version 0.29,		version 0.031 is considered greater than version 0.29,
which may not have been obvious to the porter.</para>		which may not have been obvious to the porter.</para>
</tip>		</tip>

<para>In situations such as this, the		<para>In situations such as this,
<varname>PORTEPOCH</varname> version should be increased.		<varname>PORTEPOCH</varname> must be increased.
		wblockUnsubmitted Not Done Inline Actions Another paragraph with asides. Not your fault, but fix if you can. wblock: Another paragraph with asides. Not your fault, but fix if you can.
If <varname>PORTEPOCH</varname> is nonzero it is appended to		If <varname>PORTEPOCH</varname> is nonzero it is appended to
the package name as described in section 0 above.		the package name as described in section 0 above.
<varname>PORTEPOCH</varname> must never be decreased or		<varname>PORTEPOCH</varname> must never be decreased or
reset to zero, because that would cause comparison to a		reset to zero, because that would cause comparison to a
package from an earlier epoch to fail (i.e., the package		package from an earlier epoch to fail (that is, the package
would not be detected as out of date): the new version		would not be detected as out of date): the new version
number (e.g., <literal>1.0,1</literal> in the above example)		number (for example, <literal>1.0,1</literal> in the above
is still numerically less than the previous version		example) is still numerically less than the previous version
(20000801), but the <literal>,1</literal> suffix is treated		(20000801), but the <literal>,1</literal> suffix is treated
specially by automated tools and found to be greater than		specially by automated tools and found to be greater than
the implied suffix <literal>,0</literal> on the earlier		the implied suffix <literal>,0</literal> on the earlier
		wblockUnsubmitted Not Done Inline Actions "for example," is not needed in this line. wblock: "for example," is not needed in this line.
package.</para>		package.</para>

<para>Dropping or resetting <varname>PORTEPOCH</varname>		<para>Dropping or resetting <varname>PORTEPOCH</varname>
incorrectly leads to no end of grief; if you do not		incorrectly leads to no end of grief; if the above
understand the above discussion, please keep after it until		discussion is not clear enough, please keep after it until
you do, or ask questions on the mailing lists.</para>		it becomes clear, or ask questions on the mailing
		lists.</para>
		wblockUnsubmitted Not Done Inline Actions End the first sentence after "grief". After that... If the description above was not clear enough, please consult the &a.ports;.</para> wblock: End the first sentence after "grief". After that... If the description above was not clear…

<para>It is expected that <varname>PORTEPOCH</varname> will		<para>It is expected that <varname>PORTEPOCH</varname> will
not be used for the majority of ports, and that sensible use		not be used for the majority of ports, and that sensible use
of <varname>PORTVERSION</varname> can often preempt it		of <varname>PORTVERSION</varname> can often preempt it
becoming necessary if a future release of the software		becoming necessary if a future release of the software
should change the version structure. However, care is		change the version structure. However, care is
		wblockUnsubmitted Not Done Inline Actions s/change/changes/ wblock: s/change/changes/
needed by &os; porters when a vendor release is made without		needed by &os; porters when a vendor release is made without
an official version number — such as a code		an official version number — such as a code
<quote>snapshot</quote> release. The temptation is to label		<quote>snapshot</quote> release. The temptation is to label
the release with the release date, which will cause problems		the release with the release date, which will cause problems
as in the example above when a new <quote>official</quote>		as in the example above when a new <quote>official</quote>
release is made.</para>		release is made.</para>

<para>For example, if a snapshot release is made on the date		<para>For example, if a snapshot release is made on the date
20000917, and the previous version of the software was		<literal>20000917</literal>, and the previous version of the software was
		wblockUnsubmitted Not Done Inline Actions This sentence is long and confusing. Break into multiple sentences, and if you show the wrong way, show it first: For example, do not do ... . The correct way is ... . wblock: This sentence is long and confusing. Break into multiple sentences, and if you show the wrong…
version 1.2, the snapshot release should be given a		version <literal>1.2</literal>, use a version of <literal>1.2.20000917</literal>, or similar, for
<varname>PORTVERSION</varname> of 1.2.20000917 or similar,		<varname>PORTVERSION</varname>,
not 20000917, so that the succeeding release, say 1.3, is		not <literal>20000917</literal>, so that the succeeding release, say <literal>1.3</literal>, is
still a numerically greater value.</para>		still a numerically greater value.</para>
</sect3>		</sect3>
		wblockUnsubmitted Not Done Inline Actions Double "use". wblock: Double "use".

<sect3 xml:id="makefile-portrevision-example">		<sect3 xml:id="makefile-portrevision-example">
		wblockUnsubmitted Not Done Inline Actions "to use" is not needed. wblock: "to use" is not needed.
<title>Example of <varname>PORTREVISION</varname> and		<title>Example of <varname>PORTREVISION</varname> and
<varname>PORTEPOCH</varname> Usage</title>		<varname>PORTEPOCH</varname> Usage</title>

<para>The <literal>gtkmumble</literal> port, version		<para>The <literal>gtkmumble</literal> port, version
<literal>0.10</literal>, is committed to the ports		<literal>0.10</literal>, is committed to the ports
collection:</para>		collection:</para>

<programlisting>PORTNAME= gtkmumble		<programlisting>PORTNAME= gtkmumble
Show All 14 Lines	<para><varname>PKGNAME</varname> becomes
<literal>gtkmumble-0.10_1</literal></para>		<literal>gtkmumble-0.10_1</literal></para>

<para>A new version is released by the vendor, numbered		<para>A new version is released by the vendor, numbered
<literal>0.2</literal> (it turns out the author actually		<literal>0.2</literal> (it turns out the author actually
intended <literal>0.10</literal> to actually mean		intended <literal>0.10</literal> to actually mean
<literal>0.1.0</literal>, not <quote>what comes after		<literal>0.1.0</literal>, not <quote>what comes after
0.9</quote> - oops, too late now). Since the new minor		0.9</quote> - oops, too late now). Since the new minor
version <literal>2</literal> is numerically less than the		version <literal>2</literal> is numerically less than the
previous version <literal>10</literal>, the		previous version <literal>10</literal>,
<varname>PORTEPOCH</varname> must be bumped to manually		<varname>PORTEPOCH</varname> must be bumped to manually
force the new package to be detected as		force the new package to be detected as
<quote>newer</quote>. Since it is a new vendor release of		<quote>newer</quote>. Since it is a new vendor release of
the code, <varname>PORTREVISION</varname> is reset to 0 (or		the code, <varname>PORTREVISION</varname> is reset to 0 (or
removed from the <filename>Makefile</filename>).</para>		removed from the <filename>Makefile</filename>).</para>

<programlisting>PORTNAME= gtkmumble		<programlisting>PORTNAME= gtkmumble
PORTVERSION= 0.2		PORTVERSION= 0.2
Show All 32 Lines	<varname>PKGNAMESUFFIX</varname></title>

<para>Two optional variables, <varname>PKGNAMEPREFIX</varname>		<para>Two optional variables, <varname>PKGNAMEPREFIX</varname>
and <varname>PKGNAMESUFFIX</varname>, are combined with		and <varname>PKGNAMESUFFIX</varname>, are combined with
<varname>PORTNAME</varname> and <varname>PORTVERSION</varname>		<varname>PORTNAME</varname> and <varname>PORTVERSION</varname>
to form <varname>PKGNAME</varname> as		to form <varname>PKGNAME</varname> as
<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.		<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
Make sure this conforms to our		Make sure this conforms to our
<link linkend="porting-pkgname">guidelines for a good		<link linkend="porting-pkgname">guidelines for a good
package name</link>. In particular, you are		package name</link>. In particular, the use of a
<emphasis>not</emphasis> allowed to use a hyphen		hyphen (<literal>-</literal>) in
(<literal>-</literal>) in <varname>PORTVERSION</varname>.		<varname>PORTVERSION</varname> is <emphasis>not</emphasis>
		allowed.
Also, if the package name has the		Also, if the package name has the
<replaceable>language-</replaceable> or the		<replaceable>language-</replaceable> or the
<replaceable>-compiled.specifics</replaceable> part (see		<replaceable>-compiled.specifics</replaceable> part (see
below), use <varname>PKGNAMEPREFIX</varname> and		below), use <varname>PKGNAMEPREFIX</varname> and
<varname>PKGNAMESUFFIX</varname>, respectively. Do not make		<varname>PKGNAMESUFFIX</varname>, respectively. Do not make
them part of <varname>PORTNAME</varname>.</para>		them part of <varname>PORTNAME</varname>.</para>
</sect2>		</sect2>

Show All 30 Lines	<listitem>

<para>If the port is specific to a certain region within		<para>If the port is specific to a certain region within
the language area, add the two letter country code as		the language area, add the two letter country code as
well. Examples are <literal>en_US</literal> for US		well. Examples are <literal>en_US</literal> for US
English and <literal>fr_CH</literal> for Swiss		English and <literal>fr_CH</literal> for Swiss
French.</para>		French.</para>

<para>The <replaceable>language-</replaceable> part is		<para>The <replaceable>language-</replaceable> part is
set in the <varname>PKGNAMEPREFIX</varname>		set in <varname>PKGNAMEPREFIX</varname>.</para>
variable.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry xml:id="porting-pkgname-name">		<varlistentry xml:id="porting-pkgname-name">
<term><filename><replaceable>name</replaceable></filename></term>		<term><filename><replaceable>name</replaceable></filename></term>

<listitem>		<listitem>
<para>The first letter of the <filename>name</filename>		<para>The first letter of <filename><replaceable>name</replaceable></filename>
part should be lowercase. (The rest of the name may		part should be lowercase. (The rest of the name may
contain capital letters, so use your own discretion when		contain capital letters, so think about it when
		wblockUnsubmitted Not Done Inline Actions "think about it" seems a little weak, but I can't think of a better version. wblock: "think about it" seems a little weak, but I can't think of a better version.
		matAuthorUnsubmitted Not Done Inline Actions I had the same problem, I ended up with this... mat: I had the same problem, I ended up with this...
		wblockUnsubmitted Not Done Inline Actions I guess I don't understand what this part about the name is explaining. Why should the first letter be lower case? The nonspecific "think about it" does not tell me the goal. Am I supposed to think about converting the whole thing to lower case? And then... is just thinking about it enough? wblock: I guess I don't understand what this part about the name is explaining. Why should the first…
		matAuthorUnsubmitted Not Done Inline Actions Well, hum, the idea is that you should really not have a package name that starts with a capital letter. Then, you should refrain from having capital letter later in the name. So, well, I don't really know what you're supposed to be thinking about :-) mat: Well, hum, the idea is that you should really not have a package name that starts with a…
converting a software name that has some capital letters		converting a software name that has some capital letters
		wblockUnsubmitted Not Done Inline Actions I still don't see why the first letter should not be upper case. We have ports that actually break that rule, like ImageMagick. Is it for ASCII sorting? wblock: I still don't see why the first letter should not be upper case. We have ports that actually…
		matAuthorUnsubmitted Not Done Inline Actions Ok, yes, I've discussed it with my fellow portmgr, and it is not needed any more, it seems. Rewording it. (Well, more like axing it.) mat: Ok, yes, I've discussed it with my fellow portmgr, and it is not needed any more, it seems.
in it.) There is a tradition of naming		in it.) There is a tradition of naming
<literal>Perl 5</literal> modules by prepending		<literal>Perl 5</literal> modules by prepending
<literal>p5-</literal> and converting the double-colon		<literal>p5-</literal> and converting the double-colon
separator to a hyphen. For example, the		separator to a hyphen. For example, the
<literal>Data::Dumper</literal> module becomes		<literal>Data::Dumper</literal> module becomes
<literal>p5-Data-Dumper</literal>.</para>		<literal>p5-Data-Dumper</literal>.</para>

<para>Make sure that the port's name and version are		<para>Make sure that the port's name and version are
clearly separated and placed into the		clearly separated and placed into
<varname>PORTNAME</varname> and		<varname>PORTNAME</varname> and
<varname>PORTVERSION</varname> variables. The only		<varname>PORTVERSION</varname>. The only
reason for <varname>PORTNAME</varname> to contain a		reason for <varname>PORTNAME</varname> to contain a
version part is if the upstream distribution is really		version part is if the upstream distribution is really
named that way, as in the		named that way, as in the
<filename>textproc/libxml2</filename> or		<package role="port">textproc/libxml2</package> or
<filename>japanese/kinput2-freewnn</filename> ports.		<package role="port">japanese/kinput2-freewnn</package> ports.
Otherwise, the <varname>PORTNAME</varname> should not		Otherwise, <varname>PORTNAME</varname> cannot
contain any version-specific information. It is quite		contain any version-specific information. It is quite
normal for several ports to have the same		normal for several ports to have the same
<varname>PORTNAME</varname>, as the		<varname>PORTNAME</varname>, as the
<filename>www/apache*</filename> ports do; in that case,		<package role="port">www/apache*</package> ports do; in that case,
different versions (and different index entries) are		different versions (and different index entries) are
distinguished by the <varname>PKGNAMEPREFIX</varname>		distinguished by <varname>PKGNAMEPREFIX</varname>
and <varname>PKGNAMESUFFIX</varname> values.</para>		and <varname>PKGNAMESUFFIX</varname> values.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry xml:id="porting-pkgname-compiled-specifics">		<varlistentry xml:id="porting-pkgname-compiled-specifics">
<term><filename><replaceable>-compiled.specifics</replaceable></filename></term>		<term><filename><replaceable>-compiled.specifics</replaceable></filename></term>

<listitem>		<listitem>
<para>If the port can be built with different <link		<para>If the port can be built with different <link
linkend="makefile-masterdir">hardcoded defaults</link>		linkend="makefile-masterdir">hardcoded defaults</link>
(usually part of the directory name in a family of		(usually part of the directory name in a family of
ports), the		ports), the
<replaceable>-compiled.specifics</replaceable> part		<replaceable>-compiled.specifics</replaceable> part
should state the compiled-in defaults (the hyphen is		states the compiled-in defaults (the hyphen is
		wblockUnsubmitted Not Done Inline Actions Break out aside: "states the compiled-in defaults. The hyphen is optional. wblock: Break out aside: "states the compiled-in defaults. The hyphen is optional.
optional). Examples are paper size and font		optional). Examples are paper size and font
units.</para>		units.</para>

<para>The <replaceable>-compiled.specifics</replaceable>		<para>The <replaceable>-compiled.specifics</replaceable>
part is set in the <varname>PKGNAMESUFFIX</varname>		part is set in <varname>PKGNAMESUFFIX</varname>.</para>
variable.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>

<varlistentry xml:id="porting-pkgname-version-numbers">		<varlistentry xml:id="porting-pkgname-version-numbers">
<term><filename><replaceable>-version.numbers</replaceable></filename></term>		<term><filename><replaceable>-version.numbers</replaceable></filename></term>

<listitem>		<listitem>
<para>The version string follows a dash		<para>The version string follows a dash
(<literal>-</literal>) and is a period-separated list of		(<literal>-</literal>) and is a period-separated list of
integers and single lowercase alphabetics. In		integers and single lowercase alphabetics. In
particular, it is not permissible to have another dash		particular, it is not permissible to have another dash
inside the version string. The only exception is the		inside the version string. The only exception is the
string <literal>pl</literal> (meaning		string <literal>pl</literal> (meaning
<quote>patchlevel</quote>), which can be used		<quote>patchlevel</quote>), which can be used
<emphasis>only</emphasis> when there are no major and		<emphasis>only</emphasis> when there are no major and
minor version numbers in the software. If the software		minor version numbers in the software. If the software
version has strings like <quote>alpha</quote>,		version has strings like <quote>alpha</quote>,
<quote>beta</quote>, <quote>rc</quote>, or		<quote>beta</quote>, <quote>rc</quote>, or
<quote>pre</quote>, take the first letter and put it		<quote>pre</quote>, take the first letter and put it
immediately after a period. If the version string		immediately after a period. If the version string
continues after those names, the numbers should follow		continues after those names, the numbers follows
		wblockUnsubmitted Not Done Inline Actions s/follows/follow/ wblock: s/follows/follow/
the single alphabet without an extra period between		the single alphabet without an extra period between
them.</para>		them (for example, <literal>1.0b2</literal>).</para>

<para>The idea is to make it easier to sort ports by		<para>The idea is to make it easier to sort ports by
looking at the version string. In particular, make sure		looking at the version string. In particular, make sure
version number components are always delimited by a		version number components are always delimited by a
period, and if the date is part of the string, use the		period, and if the date is part of the string, use the
<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>		<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
format, not		format, not
<literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>		<literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>
or the non-Y2K compliant		or the non-Y2K compliant
<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>		<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
format. It is important to prefix the version with		format. It is important to prefix the version with
<literal>0.0.</literal> in case a release with an actual		<literal>0.0.</literal> in case a release with an actual
version number is made, which would of course be		version number is made, which would be
numerically less than		numerically less than
<literal><replaceable>yyyy</replaceable></literal>.</para>		<literal><replaceable>yyyy</replaceable></literal>.</para>
</listitem>		</listitem>
</varlistentry>		</varlistentry>
</variablelist>		</variablelist>

<warning>		<important>
<para>Package name must be unique among all of the ports		<para>Package name must be unique among all of the ports
tree, check that there is not already a port with the same		tree, check that there is not already a port with the same
<varname>PORTNAME</varname> and if there is add one of <link		<varname>PORTNAME</varname> and if there is add one of <link
linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>		linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
or <varname>PKGNAMESUFFIX</varname></link>.</para>		or <varname>PKGNAMESUFFIX</varname></link>.</para>
</warning>		</important>

<para>Here are some (real) examples on how to convert the name		<para>Here are some (real) examples on how to convert the name
as called by the software authors to a suitable package		as called by the software authors to a suitable package
name:</para>		name:</para>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="6">		<tgroup cols="6">
<thead>		<thead>
▲ Show 20 Lines • Show All 146 Lines • ▼ Show 20 Lines	PORTEPOCH= 1</programlisting>
made from one or more subdirectories of		made from one or more subdirectories of
<filename>/usr/ports/packages</filename>. The names of these		<filename>/usr/ports/packages</filename>. The names of these
subdirectories are specified by the variable		subdirectories are specified by the variable
<varname>CATEGORIES</varname>. It is intended to make life		<varname>CATEGORIES</varname>. It is intended to make life
easier for the user when he is wading through the pile of		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		packages on the FTP site or the CDROM. Please take a look at
the <link linkend="porting-categories">current list of		the <link linkend="porting-categories">current list of
categories</link> and pick the ones that are suitable for		categories</link> and pick the ones that are suitable for
your port.</para>		the port.</para>

<para>This list also determines where in the ports tree the port		<para>This list also determines where in the ports tree the port
is imported. If you put more than one category here, it is		is imported. If there are more than one category here,
assumed that the port files will be put in the subdirectory		the port files must be put in the subdirectory
with the name in the first category. See		with the name of the first category. See
		wblockUnsubmitted Not Done Inline Actions s/there are/there is/ wblock: s/there are/there is/
<link linkend="choosing-categories">below</link> for more		<link linkend="choosing-categories">below</link> for more
discussion about how to pick the right categories.</para>		discussion about how to pick the right categories.</para>
</sect2>		</sect2>

<sect2 xml:id="porting-categories">		<sect2 xml:id="porting-categories">
<title>Current List of Categories</title>		<title>Current List of Categories</title>

<para>Here is the current list of port categories. Those marked		<para>Here is the current list of port categories. Those marked
with an asterisk (<literal>*</literal>) are		with an asterisk (<literal>*</literal>) are
<emphasis>virtual</emphasis> categories—those that do		<emphasis>virtual</emphasis> categories—those that do
not have a corresponding subdirectory in the ports tree. They		not have a corresponding subdirectory in the ports tree. They
are only used as secondary categories, and only for search		are only used as secondary categories, and only for search
purposes.</para>		purposes.</para>

<note>		<note>
<para>For non-virtual categories, you will find a one-line		<para>For non-virtual categories, there is a one-line
description in the <varname>COMMENT</varname> in that		description in <varname>COMMENT</varname> in that
subdirectory's <filename>Makefile</filename>.</para>		subdirectory's <filename>Makefile</filename>.</para>
</note>		</note>

<informaltable frame="none" pgwide="1">		<informaltable frame="none" pgwide="1">
<tgroup cols="3">		<tgroup cols="3">
<thead>		<thead>
<row>		<row>
<entry>Category</entry>		<entry>Category</entry>
▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines	window manager.</entry>
<entry><filename>chinese</filename></entry>		<entry><filename>chinese</filename></entry>
<entry>Chinese language support.</entry>		<entry>Chinese language support.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>comms</filename></entry>		<entry><filename>comms</filename></entry>
<entry>Communication software.</entry>		<entry>Communication software.</entry>
<entry>Mostly software to talk to your serial		<entry>Mostly software to talk to serial port.</entry>
		wblockUnsubmitted Not Done Inline Actions s/to serial/to the serial/ wblock: s/to serial/to the serial/
port.</entry>
</row>		</row>

<row>		<row>
<entry><filename>converters</filename></entry>		<entry><filename>converters</filename></entry>
<entry>Character code converters.</entry>		<entry>Character code converters.</entry>
<entry/>		<entry/>
</row>		</row>

Show All 9 Lines	<tgroup cols="3">
computers were invented.</entry>		computers were invented.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>devel</filename></entry>		<entry><filename>devel</filename></entry>
<entry>Development utilities.</entry>		<entry>Development utilities.</entry>
<entry>Do not put libraries here just because they are		<entry>Do not put libraries here just because they are
libraries—unless they truly do not belong		libraries—they <emphasis>must</emphasis> not be
anywhere else, they should not be in this		in this category unless they truly do not belong
category.</entry>		anywhere else.</entry>
		wblockUnsubmitted Not Done Inline Actions Remove the emdash and split the sentence: s/libraries— they/libraries. They/ "should not" would be okay here, as a recommendation. The emphasis should be on "not" either way. wblock: Remove the emdash and split the sentence: s/libraries— they/libraries. They/ "should…
		matAuthorUnsubmitted Not Done Inline Actions Maybe igor should look for those, and the semi-colon and say that they're not great 0:-) mat: Maybe igor should look for those, and the semi-colon and say that they're not great 0:-)
		wblockUnsubmitted Not Done Inline Actions It's been considered. One difficulty is the semicolons that are part of entities. Also, semicolons are only one of the signs of compound sentences. There are colons and parens and commas and lots of others. wblock: It's been considered. One difficulty is the semicolons that are part of entities. Also…
</row>		</row>

<row>		<row>
<entry><filename>dns</filename></entry>		<entry><filename>dns</filename></entry>
<entry>DNS-related software.</entry>		<entry>DNS-related software.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>docs*</filename></entry>		<entry><filename>docs*</filename></entry>
<entry>Meta-ports for &os; documentation.</entry>		<entry>Meta-ports for &os; documentation.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>editors</filename></entry>		<entry><filename>editors</filename></entry>
<entry>General editors.</entry>		<entry>General editors.</entry>
<entry>Specialized editors go in the section for those		<entry>Specialized editors go in the section for those
tools (e.g., a mathematical-formula editor will go		tools (for example, a mathematical-formula editor will
in <filename>math</filename>).</entry>		go in <filename>math</filename>, and have
		<filename>editors</filename> as a second
		category).</entry>
		wblockUnsubmitted Not Done Inline Actions Break compound sentence, with the "for example" in the second sentence. wblock: Break compound sentence, with the "for example" in the second sentence.
</row>		</row>

<row>		<row>
<entry><filename>elisp*</filename></entry>		<entry><filename>elisp*</filename></entry>
<entry>Emacs-lisp ports.</entry>		<entry>Emacs-lisp ports.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>emulators</filename></entry>		<entry><filename>emulators</filename></entry>
<entry>Emulators for other operating systems.</entry>		<entry>Emulators for other operating systems.</entry>
<entry>Terminal emulators do <emphasis>not</emphasis>		<entry>Terminal emulators do <emphasis>not</emphasis>
belong here—X-based ones should go to		belong here—X-based ones go to
		wblockUnsubmitted Not Done Inline Actions Break into two sentences instead of the emdash. wblock: Break into two sentences instead of the emdash.
<filename>x11</filename> and text-based ones to		<filename>x11</filename> and text-based ones to
either <filename>comms</filename> or		either <filename>comms</filename> or
<filename>misc</filename>, depending on the exact		<filename>misc</filename>, depending on the exact
functionality.</entry>		functionality.</entry>
</row>		</row>

<row>		<row>
<entry><filename>finance</filename></entry>		<entry><filename>finance</filename></entry>
<entry>Monetary, financial and related		<entry>Monetary, financial and related
applications.</entry>		applications.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>french</filename></entry>		<entry><filename>french</filename></entry>
<entry>French language support.</entry>		<entry>French language support.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>ftp</filename></entry>		<entry><filename>ftp</filename></entry>
<entry>FTP client and server utilities.</entry>		<entry>FTP client and server utilities.</entry>
<entry>If your port speaks both FTP and HTTP, put it		<entry>If the port speaks both FTP and HTTP, put it
		wblockUnsubmitted Not Done Inline Actions use <acronym> tags on FTP and HTTP. wblock: use <acronym> tags on FTP and HTTP.
in <filename>ftp</filename> with a secondary		in <filename>ftp</filename> with a secondary
category of <filename>www</filename>.</entry>		category of <filename>www</filename>.</entry>
</row>		</row>

<row>		<row>
<entry><filename>games</filename></entry>		<entry><filename>games</filename></entry>
<entry>Games.</entry>		<entry>Games.</entry>
<entry/>		<entry/>
▲ Show 20 Lines • Show All 142 Lines • ▼ Show 20 Lines	utilities for mathematics.</entry>
<entry><filename>mbone*</filename></entry>		<entry><filename>mbone*</filename></entry>
<entry>MBone applications.</entry>		<entry>MBone applications.</entry>
<entry/>		<entry/>
</row>		</row>

<row>		<row>
<entry><filename>misc</filename></entry>		<entry><filename>misc</filename></entry>
<entry>Miscellaneous utilities</entry>		<entry>Miscellaneous utilities</entry>
<entry>Basically things that do not belong anywhere		<entry>Things that do not belong anywhere
else. If at all possible, try to find a better		else. If at all possible, try to find a better
category for your port than <literal>misc</literal>,		category for the port than <literal>misc</literal>,
as ports tend to get overlooked in here.</entry>		as ports tend to get overlooked in here.</entry>
		wblockUnsubmitted Not Done Inline Actions s/get/be/ wblock: s/get/be/
</row>		</row>

<row>		<row>
<entry><filename>multimedia</filename></entry>		<entry><filename>multimedia</filename></entry>
<entry>Multimedia software.</entry>		<entry>Multimedia software.</entry>
<entry/>		<entry/>
</row>		</row>

▲ Show 20 Lines • Show All 208 Lines • ▼ Show 20 Lines	<tgroup cols="3">
support belongs here too.</entry>		support belongs here too.</entry>
</row>		</row>

<row>		<row>
<entry><filename>x11</filename></entry>		<entry><filename>x11</filename></entry>
<entry>The X Window System and friends.</entry>		<entry>The X Window System and friends.</entry>
<entry>This category is only for software that directly		<entry>This category is only for software that directly
supports the window system. Do not put regular X		supports the window system. Do not put regular X
applications here; most of them should go into other		applications here; most of them go into other
		wblockUnsubmitted Not Done Inline Actions Break sentence at the semicolon. wblock: Break sentence at the semicolon.
<filename>x11-*</filename> categories (see		<filename>x11-*</filename> categories (see
below).</entry>		below).</entry>
</row>		</row>

<row>		<row>
<entry><filename>x11-clocks</filename></entry>		<entry><filename>x11-clocks</filename></entry>
<entry>X11 clocks.</entry>		<entry>X11 clocks.</entry>
<entry/>		<entry/>
▲ Show 20 Lines • Show All 59 Lines • ▼ Show 20 Lines	<tgroup cols="3">
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>
</sect2>		</sect2>

<sect2 xml:id="choosing-categories">		<sect2 xml:id="choosing-categories">
<title>Choosing the Right Category</title>		<title>Choosing the Right Category</title>

<para>As many of the categories overlap, you often have to		<para>As many of the categories overlap, choosing which of the
choose which of the categories should be the primary category		categories will be the primary category of the port can be
of your port. There are several rules that govern this issue.		tedious. There are several rules that govern this issue.
Here is the list of priorities, in decreasing order of		Here is the list of priorities, in decreasing order of
precedence:</para>		precedence:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>The first category must be a physical category (see		<para>The first category must be a physical category (see
<link linkend="porting-categories">above</link>). This is		<link linkend="porting-categories">above</link>). This is
necessary to make the packaging work. Virtual categories		necessary to make the packaging work. Virtual categories
and physical categories may be intermixed after		and physical categories may be intermixed after
that.</para>		that.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Language specific categories always come first. For		<para>Language specific categories always come first. For
example, if your port installs Japanese X11 fonts, then		example, if the port installs Japanese X11 fonts, then
your <varname>CATEGORIES</varname> line would read		<varname>CATEGORIES</varname> line would read
		wblockUnsubmitted Not Done Inline Actions Insert "the" before CATEGORIES. wblock: Insert "the" before CATEGORIES.
<filename>japanese x11-fonts</filename>.</para>		<filename>japanese x11-fonts</filename>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Specific categories are listed before less-specific		<para>Specific categories are listed before less-specific
ones. For instance, an HTML editor should be listed as		ones. For instance, an HTML editor will be listed as
		wblockUnsubmitted Not Done Inline Actions Avoid passive voice. s/will be/is/ wblock: Avoid passive voice. s/will be/is/
<filename>www editors</filename>, not the other way		<filename>www editors</filename>, not the other way
around. Also, you should not list		around. Also, do not list
<filename>net</filename> when the port belongs to any of		<filename>net</filename> when the port belongs to any of
<filename>irc</filename>, <filename>mail</filename>,		<filename>irc</filename>, <filename>mail</filename>,
<filename>news</filename>, <filename>security</filename>,		<filename>news</filename>, <filename>security</filename>,
or <filename>www</filename>, as <filename>net</filename>		or <filename>www</filename>, as <filename>net</filename>
is included implicitly.</para>		is included implicitly.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>x11</filename> is used as a secondary		<para><filename>x11</filename> is used as a secondary
category only when the primary category is a natural		category only when the primary category is a natural
language. In particular, you should not put		language. In particular, do not put
<filename>x11</filename> in the category line for X		<filename>x11</filename> in the category line for X
applications.</para>		applications.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><application>Emacs</application> modes should be		<para><application>Emacs</application> modes are
placed in the same ports category as the application		placed in the same ports category as the application
supported by the mode, not in		supported by the mode, not in
<filename>editors</filename>. For example, an		<filename>editors</filename>. For example, an
<application>Emacs</application> mode to edit source files		<application>Emacs</application> mode to edit source files
of some programming language should go into		of some programming language goes into
<filename>lang</filename>.</para>		<filename>lang</filename>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Ports which install loadable kernel modules should		<para>Ports installing loadable kernel modules also
have the virtual category <filename>kld</filename> in		have the virtual category <filename>kld</filename> in
their <varname>CATEGORIES</varname> line. This is one of		their <varname>CATEGORIES</varname> line. This is one of
the things handled automatically by adding		the things handled automatically by adding
<literal>kmod</literal> to the <varname>USES</varname>		<literal>USES=kmod</literal>.</para>
line.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>misc</filename> should not appear with any		<para><filename>misc</filename> does not appear with any
other non-virtual category. If you have		other non-virtual category. If there is
<literal>misc</literal> with something else in your		<literal>misc</literal> with something else in
<varname>CATEGORIES</varname> line, that means you can		<varname>CATEGORIES</varname>, that means
safely delete <literal>misc</literal> and just put the		<literal>misc</literal> can safely be deleted and only put
		wblockUnsubmitted Not Done Inline Actions "... be deleted and the port placed only in the other subdirectory.</para> wblock: "... be deleted and the port placed only in the other subdirectory.</para>
port in that other subdirectory!</para>		the port in that other subdirectory!</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>If your port truly does not belong anywhere else,		<para>If the port truly does not belong anywhere else,
put it in <filename>misc</filename>.</para>		put it in <filename>misc</filename>.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<para>If you are not sure about the category, please put a		<para>If the category is not clearly cut, please put a
comment to that effect in your &man.send-pr.1; submission so		comment to that effect in the &man.send-pr.1; submission so
		wblockUnsubmitted Not Done Inline Actions send-pr is gone. "port submission in the bug database" (and a link)? wblock: send-pr is gone. "port submission in the bug database" (and a link)?
we can discuss it before we import it. If you are a		we can discuss it before we import it. As a committer,
committer, send a note to the &a.ports; so we can discuss it		send a note to the &a.ports; so we can discuss it
		wblockUnsubmitted Not Done Inline Actions s/clearly cut/clearly defined/ wblock: s/clearly cut/clearly defined/
first. Too often, new ports are imported to the wrong		first. Too often, new ports are imported to the wrong
category only to be moved right away. This causes unnecessary		category only to be moved right away. This causes unnecessary
and undesirable bloat in the master source repository.</para>		and undesirable bloat in the master source repository.</para>
</sect2>		</sect2>

<sect2 xml:id="proposing-categories">		<sect2 xml:id="proposing-categories">
<title>Proposing a New Category</title>		<title>Proposing a New Category</title>

<para>As the Ports Collection has grown over time, various new		<para>As the Ports Collection has grown over time, various new
categories have been introduced. New categories can either be		categories have been introduced. New categories can either be
<emphasis>virtual</emphasis> categories—those that do		<emphasis>virtual</emphasis> categories—those that do
not have a corresponding subdirectory in the ports tree—		not have a corresponding subdirectory in the ports tree—
or <emphasis>physical</emphasis> categories—those that		or <emphasis>physical</emphasis> categories—those that
do. The following text discusses the issues involved in		do. This section discusses the issues involved in creating a
creating a new physical category so that you can understand		new physical category. Read it thouroughly before proposing a
them before you propose one.</para>		new one.</para>

<para>Our existing practice has been to avoid creating a new		<para>Our existing practice has been to avoid creating a new
physical category unless either a large number of ports would		physical category unless either a large number of ports would
logically belong to it, or the ports that would belong to it		logically belong to it, or the ports that would belong to it
are a logically distinct group that is of limited general		are a logically distinct group that is of limited general
interest (for instance, categories related to spoken human		interest (for instance, categories related to spoken human
languages), or preferably both.</para>		languages), or preferably both.</para>

<para>The rationale for this is that such a change creates a		<para>The rationale for this is that such a change creates a
<link xlink:href="&url.articles.committers-guide;/#ports">fair		<link xlink:href="&url.articles.committers-guide;/#ports">fair
amount of work</link> for both the committers and also for		amount of work</link> for both the committers and also for
all users who track changes to the Ports Collection. In		all users who track changes to the Ports Collection. In
addition, proposed category changes just naturally seem to		addition, proposed category changes just naturally seem to
attract controversy. (Perhaps this is because there is no		attract controversy. (Perhaps this is because there is no
clear consensus on when a category is <quote>too big</quote>,		clear consensus on when a category is <quote>too big</quote>,
nor whether categories should lend themselves to browsing (and		nor whether categories should lend themselves to browsing (and
thus what number of categories would be an ideal number), and		thus what number of categories would be an ideal number), and
so forth.)</para>		so forth.)</para>

<para>Here is the procedure:</para>		<para>Here is the procedure:</para>

<procedure>		<procedure>
<step>		<step>
<para>Propose the new category on &a.ports;. You should		<para>Propose the new category on &a.ports;. Include
include a detailed rationale for the new category,		a detailed rationale for the new category,
including why you feel the existing categories are not		including why the existing categories are not
sufficient, and the list of existing ports proposed to		sufficient, and the list of existing ports proposed to
move. (If there are new ports pending in		move. (If there are new ports pending in
<application>GNATS</application> that would fit this		<application>Bugzilla</application> that would fit this
category, list them too.) If you are the maintainer		category, list them too.) If you are the maintainer
and/or submitter, respectively, mention that as it may		and/or submitter, respectively, mention that as it may
help you to make your case.</para>		help the case.</para>
</step>		</step>

<step>		<step>
<para>Participate in the discussion.</para>		<para>Participate in the discussion.</para>
</step>		</step>

<step>		<step>
<para>If it seems that there is support for your idea, file		<para>If it seems that there is support for the idea, file
a PR which includes both the rationale and the list of		a PR which includes both the rationale and the list of
existing ports that need to be moved. Ideally, this PR		existing ports that need to be moved. Ideally, this PR
should also include patches for the following:</para>		would also include these patches:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><filename>Makefile</filename>s for the new ports		<para><filename>Makefile</filename>s for the new ports
once they are repocopied</para>		once they are repocopied</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>Makefile</filename> for the new		<para><filename>Makefile</filename> for the new
category</para>		category</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>Makefile</filename> for the old ports'		<para><filename>Makefile</filename> for the old ports'
categories</para>		categories</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><filename>Makefile</filename>s for ports that		<para><filename>Makefile</filename>s for ports that
depend on the old ports</para>		depend on the old ports</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>(for extra credit, you can include the other files		<para>(for extra credit, include the other files
that have to change, as per the procedure in the		that have to change, as per the procedure in the
Committer's Guide.)</para>		Committer's Guide.)</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</step>		</step>

<step>		<step>
<para>Since it affects the ports infrastructure and involves		<para>Since it affects the ports infrastructure and involves
not only performing repo-copies but also possibly running		moving and patching many ports but also possibly running
regression tests on the build cluster, the PR should be		regression tests on the build cluster, assign the PR to
assigned to the &a.portmgr;.</para>		the &a.portmgr;.</para>
</step>		</step>

<step>		<step>
<para>If that PR is approved, a committer will need to		<para>If that PR is approved, a committer will need to
follow the rest of the procedure that is <link		follow the rest of the procedure that is <link
xlink:href="&url.articles.committers-guide;/article.html#PORTS">outlined		xlink:href="&url.articles.committers-guide;/article.html#PORTS">outlined
in the Committer's Guide</link>.</para>		in the Committer's Guide</link>.</para>
</step>		</step>
</procedure>		</procedure>

<para>Proposing a new virtual category should be similar to the		<para>Proposing a new virtual category is similar to the
above but much less involved, since no ports will actually		above but much less involved, since no ports will actually
have to move. In this case, the only patches to include in		have to move. In this case, the only patches to include in
the PR would be those to add the new category to the		the PR would be those to add the new category to
<varname>CATEGORIES</varname> of the affected ports.</para>		<varname>CATEGORIES</varname> of the affected ports.</para>
</sect2>		</sect2>

<sect2 xml:id="proposing-reorg">		<sect2 xml:id="proposing-reorg">
<title>Proposing Reorganizing All the Categories</title>		<title>Proposing Reorganizing All the Categories</title>

<para>Occasionally someone proposes reorganizing the		<para>Occasionally someone proposes reorganizing the
categories with either a 2-level structure, or some other kind		categories with either a 2-level structure, or some other kind
of keyword structure. To date, nothing has come of any of		of keyword structure. To date, nothing has come of any of
these proposals because, while they are very easy to make, the		these proposals because, while they are very easy to make, the
effort involved to retrofit the entire existing ports		effort involved to retrofit the entire existing ports
collection with any kind of reorganization is daunting to say		collection with any kind of reorganization is daunting to say
the very least. Please read the history of these proposals in		the very least. Please read the history of these proposals in
the mailing list archives before you post this idea;		the mailing list archives before posting this idea;
furthermore, you should be prepared to be challenged to offer		furthermore, be prepared to be challenged to offer
		wblockUnsubmitted Not Done Inline Actions Break sentence at semicolon. wblock: Break sentence at semicolon.
a working prototype.</para>		a working prototype.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="makefile-distfiles">		<sect1 xml:id="makefile-distfiles">
<title>The Distribution Files</title>		<title>The Distribution Files</title>

<para>The second part of the <filename>Makefile</filename>		<para>The second part of the <filename>Makefile</filename>
describes the files that must be downloaded in order to build		describes the files that must be downloaded to build
the port, and where they can be downloaded from.</para>		the port, and where they can be downloaded from.</para>
		wblockUnsubmitted Not Done Inline Actions Remove "from". wblock: Remove "from".

<sect2 xml:id="makefile-distversion">		<sect2 xml:id="makefile-distversion">
<title><varname>DISTVERSION/DISTNAME</varname></title>		<title><varname>DISTVERSION/DISTNAME</varname></title>

<para><varname>DISTNAME</varname> is the name of the port as		<para><varname>DISTNAME</varname> is the name of the port as
called by the authors of the software.		called by the authors of the software.
<varname>DISTNAME</varname> defaults to		<varname>DISTNAME</varname> defaults to
<literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>,		<literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>,
Show All 11 Lines
<literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be		<literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be
handled automatically by setting		handled automatically by setting
<varname>DISTVERSION</varname>.		<varname>DISTVERSION</varname>.
<varname>PORTVERSION</varname> will be derived from it		<varname>PORTVERSION</varname> will be derived from it
automatically.</para>		automatically.</para>

<note>		<note>
<para>Only one of <varname>PORTVERSION</varname> and		<para>Only one of <varname>PORTVERSION</varname> and
<varname>DISTVERSION</varname> can be set at a time. If you		<varname>DISTVERSION</varname> can be set at a time. If
set <varname>DISTVERSION</varname> and the derived		<varname>DISTVERSION</varname> does not derive a correct
<varname>PORTVERSION</varname> is not right, do not use		<varname>PORTVERSION</varname>, do not use
<varname>DISTVERSION</varname>, set		<varname>DISTVERSION</varname>, set
<varname>PORTVERSION</varname> to the right value and set		<varname>PORTVERSION</varname> to the right value and set
<varname>DISTNAME</varname> with <varname>PORTNAME</varname>		<varname>DISTNAME</varname> with <varname>PORTNAME</varname>
with either some computation of		with either some computation of
<varname>PORTVERSION</varname> or the verbatim upstream		<varname>PORTVERSION</varname> or the verbatim upstream
version.</para>		version.</para>
</note>		</note>

<para>The following table lists some examples of
<varname>DISTVERSION</varname> and the derived
<varname>PORTVERSION</varname>:</para>

<informaltable frame="none" pgwide="0">		<table frame="none" pgwide="0">
		<title>Examples of <varname>DISTVERSION</varname> and the
		Derived <varname>PORTVERSION</varname></title>

<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry><varname>DISTVERSION</varname></entry>		<entry><varname>DISTVERSION</varname></entry>
<entry><varname>PORTVERSION</varname></entry>		<entry><varname>PORTVERSION</varname></entry>
</row>		</row>
</thead>		</thead>

Show All 14 Lines	<tbody>
</row>		</row>

<row>		<row>
<entry>8:f_17</entry>		<entry>8:f_17</entry>
<entry>8f.17</entry>		<entry>8f.17</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</table>

<note>		<note>
<para><varname>PKGNAMEPREFIX</varname> and		<para><varname>PKGNAMEPREFIX</varname> and
<varname>PKGNAMESUFFIX</varname> do not affect		<varname>PKGNAMESUFFIX</varname> do not affect
<varname>DISTNAME</varname>. Also note that if		<varname>DISTNAME</varname>. Also note that if
<varname>WRKSRC</varname> is equal to		<varname>WRKSRC</varname> is equal to
<filename>work/${DISTNAME}</filename> while		<filename>${WRKDIR}/${DISTNAME}</filename> while
the original source archive is named something other than		the original source archive is named something other than
<literal>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</literal>,		<literal>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</literal>,
you should probably leave <varname>DISTNAME</varname>		leave <varname>DISTNAME</varname>
alone— you are better off defining		alone— defining only
<varname>DISTFILES</varname> than having to set both		<varname>DISTFILES</varname> is easier than both
<varname>DISTNAME</varname> and <varname>WRKSRC</varname>		<varname>DISTNAME</varname> and <varname>WRKSRC</varname>
(and possibly <varname>EXTRACT_SUFX</varname>).</para>		(and possibly <varname>EXTRACT_SUFX</varname>).</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="makefile-master_sites">		<sect2 xml:id="makefile-master_sites">
<title><varname>MASTER_SITES</varname></title>		<title><varname>MASTER_SITES</varname></title>

<para>Record the directory part of the FTP/HTTP-URL pointing at		<para>Record the directory part of the FTP/HTTP-URL pointing at
the original tarball in <varname>MASTER_SITES</varname>. Do		the original tarball in <varname>MASTER_SITES</varname>. Do
not forget the trailing slash (<filename>/</filename>)!</para>		not forget the trailing slash (<filename>/</filename>)!</para>

<para>The <command>make</command> macros will try to use this		<para>The <command>make</command> macros will try to use this
specification for grabbing the distribution file with		specification for grabbing the distribution file with
<varname>FETCH</varname> if they cannot find it already on the		<varname>FETCH</varname> if they cannot find it already on the
system.</para>		system.</para>

<para>It is recommended that you put multiple sites on this		<para>It is recommended that multiple sites be added on this
		wblockUnsubmitted Not Done Inline Actions s/be added/are included/ wblock: s/be added/are included/
list, preferably from different continents. This will		list, preferably from different continents. This will
safeguard against wide-area network problems. We are even		safeguard against wide-area network problems. We are even
planning to add support for automatically determining the		planning to add support for automatically determining the
closest master site and fetching from there; having multiple		closest master site and fetching from there; having multiple
sites will go a long way towards helping this effort.</para>		sites will go a long way towards helping this effort.</para>

<para>If the original tarball is part of one of the popular		<para>If the original tarball is part of one of the popular
archives such as SourceForge, GNU, or Perl CPAN, you may be		archives such as SourceForge, GNU, or Perl CPAN, it may be
able refer to those sites in an easy compact form using		possible refer to those sites in an easy compact form using
predefined macros (e.g., <literal>SF</literal>,		predefined macros (for example, <literal>SF</literal>,
<literal>GNU</literal> or <literal>CPAN</literal>). Simply		<literal>GNU</literal> or <literal>CPAN</literal>).
set <varname>MASTER_SITES</varname> to one of these values.		Set <varname>MASTER_SITES</varname> to one of these values.
Here is an example:</para>		Here is an example:</para>

<programlisting>MASTER_SITES= GNU/make</programlisting>		<programlisting>MASTER_SITES= GNU/make</programlisting>

<para>Or you can use the older expanded format, though there		<para>Or the older expanded format can be used, though there
		wblockUnsubmitted Not Done Inline Actions "The older expanded format can still be used, although there" wblock: "The older expanded format can still be used, although there"
really are no reason to do so:</para>		really are no reason to do so:</para>
		wblockUnsubmitted Not Done Inline Actions "really is no reason to do so:</para> wblock: "really is no reason to do so:</para>

<programlisting>MASTER_SITES= ${MASTER_SITE_GNU}		<programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
MASTER_SITE_SUBDIR= make</programlisting>		MASTER_SITE_SUBDIR= make</programlisting>

<para>These values and variables are defined in		<para>These values and variables are defined in
<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are		<filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
new entries added all the time, so make sure to check the		new entries added all the time, so make sure to check the
latest version of this file before submitting a port.</para>		latest version of this file before submitting a port.</para>

<para>Several <emphasis>magic</emphasis> macros exist for		<para>Several <emphasis>magic</emphasis> macros exist for
popular sites with a predictable directory structure. For		popular sites with a predictable directory structure. For
these, just use the abbreviation and the system will try to		these, just use the abbreviation and the system will try to
guess the correct subdirectory for you.</para>		guess the correct subdirectory automatically.</para>

<programlisting>MASTER_SITES= SF</programlisting>		<programlisting>MASTER_SITES= SF</programlisting>

<para>If the guess is incorrect, it can be overridden as		<para>If the guess is incorrect, it can be overridden as
follows.</para>		follows.</para>

<programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>		<programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>

▲ Show 20 Lines • Show All 220 Lines • ▼ Show 20 Lines	GH_COMMIT= 6dbb17b</programlisting>
</example>		</example>

</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="makefile-extract_sufx">		<sect2 xml:id="makefile-extract_sufx">
<title><varname>EXTRACT_SUFX</varname></title>		<title><varname>EXTRACT_SUFX</varname></title>

<para>If you have one distribution file, and it uses an odd		<para>If there is one distribution file, and it uses an odd
suffix to indicate the compression mechanism, set		suffix to indicate the compression mechanism, set
<varname>EXTRACT_SUFX</varname>.</para>		<varname>EXTRACT_SUFX</varname>.</para>

<para>For example, if the distribution file was named		<para>For example, if the distribution file was named
<filename>foo.tar.gzip</filename> instead of the more normal		<filename>foo.tar.gzip</filename> instead of the more normal
<filename>foo.tar.gz</filename>, you would write:</para>		<filename>foo.tar.gz</filename>, write:</para>

<programlisting>DISTNAME= foo		<programlisting>DISTNAME= foo
EXTRACT_SUFX= .tar.gzip</programlisting>		EXTRACT_SUFX= .tar.gzip</programlisting>

<para>The		<para>The
<literal>USES=tar[:<replaceable>xxx</replaceable>]</literal>,		<literal>USES=tar[:<replaceable>xxx</replaceable>]</literal>,
<literal>USES=lha</literal> or <literal>USES=zip</literal>		<literal>USES=lha</literal> or <literal>USES=zip</literal>
automatically set <varname>EXTRACT_SUFX</varname> to the most		automatically set <varname>EXTRACT_SUFX</varname> to the most
common archives extensions as necessary, see <xref		common archives extensions as necessary, see <xref
linkend="uses-values"/> for more details. If neither of		linkend="uses-values"/> for more details. If neither of
these are set then <varname>EXTRACT_SUFX</varname> defaults to		these are set then <varname>EXTRACT_SUFX</varname> defaults to
<literal>.tar.gz</literal>.</para>		<literal>.tar.gz</literal>.</para>

<note>		<note>
<para>You never need to set both		<para>As <varname>EXTRACT_SUFX</varname> is only used in
<varname>EXTRACT_SUFX</varname> and		<varname>DISTFILES</varname>, only set one of them..</para>
		wblockUnsubmitted Not Done Inline Actions I don't understand what this sentence is saying. wblock: I don't understand what this sentence is saying.
		matAuthorUnsubmitted Not Done Inline Actions EXTRACT_SUFX is normally set to .tar.gz and the only way it is used is line 2511 of bsd.port.mk: DISTFILES?= ${DISTNAME}${EXTRACT_SUFX} So if you set DISTFILES for some other reason, EXTRACT_SUFX is never used and you don't need to set it. mat: EXTRACT_SUFX is normally set to .tar.gz and the only way it is used is line 2511 of bsd.port.mk…
<varname>DISTFILES</varname>.</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="makefile-distfiles-definition">		<sect2 xml:id="makefile-distfiles-definition">
<title><varname>DISTFILES</varname></title>		<title><varname>DISTFILES</varname></title>

<para>Sometimes the names of the files to be downloaded have no		<para>Sometimes the names of the files to be downloaded have no
resemblance to the name of the port. For example, it might be		resemblance to the name of the port. For example, it might be
Show All 10 Lines	downloaded.</para>
<para>If not explicitly set, <varname>DISTFILES</varname>		<para>If not explicitly set, <varname>DISTFILES</varname>
defaults to		defaults to
<literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>		<literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-extract_only">		<sect2 xml:id="makefile-extract_only">
<title><varname>EXTRACT_ONLY</varname></title>		<title><varname>EXTRACT_ONLY</varname></title>

<para>If only some of the <varname>DISTFILES</varname> must be		<para>If only some of <varname>DISTFILES</varname> must be
		wblockUnsubmitted Not Done Inline Actions It does need the "the" before DISTFILES. wblock: It does need the "the" before DISTFILES.
extracted—for example, one of them is the source code,		extracted—for example, one of them is the source code,
while another is an uncompressed document—list the		while another is an uncompressed document—list the
filenames that must be extracted in		filenames that must be extracted in
<varname>EXTRACT_ONLY</varname>.</para>		<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>		EXTRACT_ONLY= source.tar.gz</programlisting>

<para>If <emphasis>none</emphasis> of the		<para>If <emphasis>none</emphasis> of
<varname>DISTFILES</varname> should be uncompressed then set		<varname>DISTFILES</varname> have to be uncompressed then set
		wblockUnsubmitted Not Done Inline Actions <para>When none of the <varname>DISTFILES</varname> need to be uncompressed, set <varname>EXTRACT_ONLY</varname> to the empty string.</para> wblock: <para>When none of the <varname>DISTFILES</varname> need to be uncompressed, set…
<varname>EXTRACT_ONLY</varname> to the empty string.</para>		<varname>EXTRACT_ONLY</varname> to the empty string.</para>

<programlisting>EXTRACT_ONLY=</programlisting>		<programlisting>EXTRACT_ONLY=</programlisting>
</sect2>		</sect2>

<sect2 xml:id="porting-patchfiles">		<sect2 xml:id="porting-patchfiles">
<title><varname>PATCHFILES</varname></title>		<title><varname>PATCHFILES</varname></title>

<para>If your port requires some additional patches that are		<para>If the port requires some additional patches that are
available by FTP or HTTP, set <varname>PATCHFILES</varname> to		available by FTP or HTTP, set <varname>PATCHFILES</varname> to
		wblockUnsubmitted Not Done Inline Actions <acronym> tags for FTP and HTTP. wblock: <acronym> tags for FTP and HTTP.
the names of the files and <varname>PATCH_SITES</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		the URL of the directory that contains them (the format is the
same as <varname>MASTER_SITES</varname>).</para>		same as <varname>MASTER_SITES</varname>).</para>

<para>If the patch is not relative to the top of the source tree		<para>If the patch is not relative to the top of the source tree
(i.e., <varname>WRKSRC</varname>) because it contains some		(that is, <varname>WRKSRC</varname>) because it contains some
extra pathnames, set <varname>PATCH_DIST_STRIP</varname>		extra pathnames, set <varname>PATCH_DIST_STRIP</varname>
accordingly. For instance, if all the pathnames in the patch		accordingly. For instance, if all the pathnames in the patch
have an extra <literal>foozolix-1.0/</literal> in front of the		have an extra <literal>foozolix-1.0/</literal> in front of the
filenames, then set		filenames, then set
<literal>PATCH_DIST_STRIP=-p1</literal>.</para>		<literal>PATCH_DIST_STRIP=-p1</literal>.</para>

<para>Do not worry if the patches are compressed; they will be		<para>Do not worry if the patches are compressed; they will be
decompressed automatically if the filenames end with		decompressed automatically if the filenames end with
<filename>.Z</filename>, <filename>.gz</filename>,		<filename>.Z</filename>, <filename>.gz</filename>,
<filename>.bz2</filename> or <filename>.xz</filename>.</para>		<filename>.bz2</filename> or <filename>.xz</filename>.</para>

<para>If the patch is distributed with some other files, such as		<para>If the patch is distributed with some other files, such as
documentation, in a <command>gzip</command>ped tarball, you		documentation, in a <command>gzip</command>ped tarball, using
cannot just use <varname>PATCHFILES</varname>. If that is the		<varname>PATCHFILES</varname> is not possible. If that is the
case, add the name and the location of the patch tarball to		case, add the name and the location of the patch tarball to
<varname>DISTFILES</varname> and		<varname>DISTFILES</varname> and
<varname>MASTER_SITES</varname>. Then, use the		<varname>MASTER_SITES</varname>. Then, use
<varname>EXTRA_PATCHES</varname> variable to point to those		<varname>EXTRA_PATCHES</varname> to point to those
files and <filename>bsd.port.mk</filename> will automatically		files and <filename>bsd.port.mk</filename> will automatically
apply them for you. In particular, do		apply them. In particular, do
<emphasis>not</emphasis> copy patch files into the		<emphasis>not</emphasis> copy patch files into
<varname>PATCHDIR</varname> directory—that directory may		<filename>${PATCHDIR}</filename>—that directory may
		wblockUnsubmitted Not Done Inline Actions Break sentence at the emdash. wblock: Break sentence at the emdash.
not be writable.</para>		not be writable.</para>

<tip>		<tip>
<para>If there are multiple patches and they need mixed values		<para>If there are multiple patches and they need mixed values
for the strip parameter, it can be added alongside the patch		for the strip parameter, it can be added alongside the patch
name in <varname>PATCHFILES</varname>, e.g:</para>		name in <varname>PATCHFILES</varname>, e.g:</para>

<programlisting>PATCHFILES= patch1 patch2:-p1</programlisting>		<programlisting>PATCHFILES= patch1 patch2:-p1</programlisting>

<para>This does not conflict with <link		<para>This does not conflict with <link
linkend="porting-master-sites-n">the master site grouping		linkend="porting-master-sites-n">the master site grouping
feature</link>, the following also works:</para>		feature</link>, adding a group also works:</para>

<programlisting>PATCHFILES= patch2:-p1:source2</programlisting>		<programlisting>PATCHFILES= patch2:-p1:source2</programlisting>
</tip>		</tip>

<note>		<note>
<para>The tarball will have been extracted alongside the		<para>The tarball will have been extracted alongside the
regular source by then, so there is no need to explicitly		regular source by then, so there is no need to explicitly
extract it if it is a regular <command>gzip</command>ped or		extract it if it is a regular <command>gzip</command>ped or
<command>compress</command>ed tarball. If you do the		<command>compress</command>ed tarball. Take extra care not
latter, take extra care not to overwrite something that		to overwrite something that already exists in that
already exists in that directory. Also, do not forget to		directory if extracting it manually. Also, do not forget to
add a command to remove the copied patch in the		add a command to remove the copied patch in the
<buildtarget>pre-clean</buildtarget> target.</para>		<buildtarget>pre-clean</buildtarget> target.</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="porting-master-sites-n">		<sect2 xml:id="porting-master-sites-n">
<title>Multiple Distribution Files or Patches from Different		<title>Multiple Distribution Files or Patches from Different
Sites and Subdirectories		Sites and Subdirectories
(<literal>MASTER_SITES:n</literal>)</title>		(<literal>MASTER_SITES:n</literal>)</title>

<para>(Consider this to be a somewhat		<para>(Consider this to be a somewhat
<quote>advanced topic</quote>; those new to this document		<quote>advanced topic</quote>; those new to this document
may wish to skip this section at first).</para>		may wish to skip this section at first).</para>

<para>This section has information on the fetching mechanism		<para>This section has information on the fetching mechanism
known as both <literal>MASTER_SITES:n</literal> and		known as both <literal>MASTER_SITES:n</literal> and
<literal>MASTER_SITES_NN</literal>. We will refer to this		<literal>MASTER_SITES_NN</literal>. We will refer to this
mechanism as <literal>MASTER_SITES:n</literal>.</para>		mechanism as <literal>MASTER_SITES:n</literal>.</para>

<para>A little background first. OpenBSD has a neat feature		<para>A little background first. OpenBSD has a neat feature
inside the <varname>DISTFILES</varname> and		inside <varname>DISTFILES</varname> and
<varname>PATCHFILES</varname> variables which allows files and		<varname>PATCHFILES</varname> which allows files and
patches to be postfixed with <literal>:n</literal>		patches to be postfixed with <literal>:n</literal>
identifiers. Here, <literal>n</literal> can be both		identifiers. Here, <literal>n</literal> can be both
<literal>[0-9]</literal> and denote a group designation. For		<literal>[0-9]</literal> and denote a group designation. For
example:</para>		example:</para>

<programlisting>DISTFILES= alpha:0 beta:1</programlisting>		<programlisting>DISTFILES= alpha:0 beta:1</programlisting>

<para>In OpenBSD, distribution file <filename>alpha</filename>		<para>In OpenBSD, distribution file <filename>alpha</filename>
Show All 23 Lines	relief to network strain that this would bring.</para>

<para>In the next sections, information will follow on the		<para>In the next sections, information will follow on the
&os; implementation of this idea. We improved a bit on		&os; implementation of this idea. We improved a bit on
OpenBSD's concept.</para>		OpenBSD's concept.</para>

<sect3 xml:id="porting-master-sites-n-simplified">		<sect3 xml:id="porting-master-sites-n-simplified">
<title>Simplified Information</title>		<title>Simplified Information</title>

<para>This section tells you how to quickly prepare fine		<para>This section explains how to quickly prepare fine
		wblockUnsubmitted Not Done Inline Actions Nice! wblock: Nice!
grained fetching of multiple distribution files and patches		grained fetching of multiple distribution files and patches
from different sites and subdirectories. We describe here a		from different sites and subdirectories. We describe here a
case of simplified <literal>MASTER_SITES:n</literal> usage.		case of simplified <literal>MASTER_SITES:n</literal> usage.
This will be sufficient for most scenarios. However, if you		This will be sufficient for most scenarios. More detailed
need further information, you will have to refer to the next		information are available in <xref
section.</para>		linkend="ports-master-sites-n-detailed"/>.</para>

<para>Some applications consist of multiple distribution files		<para>Some applications consist of multiple distribution files
that must be downloaded from a number of different sites.		that must be downloaded from a number of different sites.
For example, <application>Ghostscript</application> consists		For example, <application>Ghostscript</application> consists
of the core of the program, and then a large number of		of the core of the program, and then a large number of
driver files that are used depending on the user's printer.		driver files that are used depending on the user's printer.
Some of these driver files are supplied with the core, but		Some of these driver files are supplied with the core, but
many others must be downloaded from a variety of different		many others must be downloaded from a variety of different
sites.</para>		sites.</para>

<para>To support this, each entry in		<para>To support this, each entry in
<varname>DISTFILES</varname> may be followed by a colon and		<varname>DISTFILES</varname> may be followed by a colon and
a <quote>tag name</quote>. Each site listed in		a <quote>tag name</quote>. Each site listed in
<varname>MASTER_SITES</varname> is then followed by a colon,		<varname>MASTER_SITES</varname> is then followed by a colon,
and the tag that indicates which distribution files should		and the tag that indicates which distribution files are
be downloaded from this site.</para>		downloaded from this site.</para>

<para>For example, consider an application with the source		<para>For example, consider an application with the source
split in two parts, <filename>source1.tar.gz</filename> and		split in two parts, <filename>source1.tar.gz</filename> and
<filename>source2.tar.gz</filename>, which must be		<filename>source2.tar.gz</filename>, which must be
downloaded from two different sites. The port's		downloaded from two different sites. The port's
<filename>Makefile</filename> would include lines like <xref		<filename>Makefile</filename> would include lines like <xref
linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para>		linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para>

<example		<example
xml:id="ports-master-sites-n-example-simple-use-one-file-per-site">		xml:id="ports-master-sites-n-example-simple-use-one-file-per-site">

<title>Simplified Use of <literal>MASTER_SITES:n</literal>		<title>Simplified Use of <literal>MASTER_SITES:n</literal>
with One File Per Site</title>		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		ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \		DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2</programlisting>		source2.tar.gz:source2</programlisting>
</example>		</example>

<para>Multiple distribution files can have the same tag.		<para>Multiple distribution files can have the same tag.
Continuing the previous example, suppose that there was a		Continuing the previous example, suppose that there was a
third distfile, <filename>source3.tar.gz</filename>, that		third distfile, <filename>source3.tar.gz</filename>, that
should be downloaded from		is downloaded from
<systemitem>ftp.example2.com</systemitem>. The		<systemitem>ftp.example2.com</systemitem>. The
<filename>Makefile</filename> would then be written like		<filename>Makefile</filename> would then be written like
<xref		<xref
linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para>		linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para>

<example		<example
xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">		xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">

<title>Simplified Use of <literal>MASTER_SITES:n</literal>		<title>Simplified Use of <literal>MASTER_SITES:n</literal>
with More Than One File Per Site</title>		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		ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \		DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2 \		source2.tar.gz:source2 \
source3.tar.gz:source2</programlisting>		source3.tar.gz:source2</programlisting>
</example>		</example>
</sect3>		</sect3>

<sect3 xml:id="ports-master-sites-n-detailed">		<sect3 xml:id="ports-master-sites-n-detailed">
<title>Detailed Information</title>		<title>Detailed Information</title>

<para>Okay, so the previous section example did not reflect		<para>Okay, so the previous section example did not reflect
		wblockUnsubmitted Not Done Inline Actions Remove "section". wblock: Remove "section".
your needs? In this section we will explain in detail how		the port needs? In this section we will explain in detail how
		wblockUnsubmitted Not Done Inline Actions s/the port/the new port's/ wblock: s/the port/the new port's/
the fine grained fetching mechanism		the fine grained fetching mechanism
		wblockUnsubmitted Not Done Inline Actions s/port/port's/ wblock: s/port/port's/
<literal>MASTER_SITES:n</literal> works and how you can		<literal>MASTER_SITES:n</literal> works and how it can
modify your ports to use it.</para>		be used.</para>

<orderedlist>		<orderedlist>
<listitem>		<listitem>
<para>Elements can be postfixed with		<para>Elements can be postfixed with
<literal>:<replaceable>n</replaceable></literal> where		<literal>:<replaceable>n</replaceable></literal> where
<replaceable>n</replaceable> is		<replaceable>n</replaceable> is
<literal>[^:,]+</literal>, i.e.,		<literal>[^:,]+</literal>, that is,
<replaceable>n</replaceable> could conceptually be any		<replaceable>n</replaceable> could conceptually be any
alphanumeric string but we will limit it to		alphanumeric string but we will limit it to
<literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for		<literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
now.</para>		now.</para>

<para>Moreover, string matching is case sensitive; i.e.,		<para>Moreover, string matching is case sensitive; that is,
<literal>n</literal> is different from		<literal>n</literal> is different from
<literal>N</literal>.</para>		<literal>N</literal>.</para>

<para>However, the following words cannot be used for		<para>However, these words cannot be used for
postfixing purposes since they yield special meaning:		postfixing purposes since they yield special meaning:
<literal>default</literal>, <literal>all</literal> and		<literal>default</literal>, <literal>all</literal> and
<literal>ALL</literal> (they are used internally in		<literal>ALL</literal> (they are used internally in
item <xref		item <xref
linkend="porting-master-sites-n-what-changes-in-port-targets"/>).		linkend="porting-master-sites-n-what-changes-in-port-targets"/>).
Furthermore, <literal>DEFAULT</literal> is a special		Furthermore, <literal>DEFAULT</literal> is a special
purpose word (check item <xref		purpose word (check item <xref
linkend="porting-master-sites-n-DEFAULT-group"/>).</para>		linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Elements postfixed with <literal>:n</literal>		<para>Elements postfixed with <literal>:n</literal>
belong to the group <literal>n</literal>,		belong to the group <literal>n</literal>,
<literal>:m</literal> belong to group		<literal>:m</literal> belong to group
<literal>m</literal> and so forth.</para>		<literal>m</literal> and so forth.</para>
</listitem>		</listitem>

<listitem xml:id="porting-master-sites-n-DEFAULT-group">		<listitem xml:id="porting-master-sites-n-DEFAULT-group">
<para>Elements without a postfix are groupless, i.e., they		<para>Elements without a postfix are groupless, they
all belong to the special group		all belong to the special group
<literal>DEFAULT</literal>. If you postfix any elements		<literal>DEFAULT</literal>. Any elements postfixed with
with <literal>DEFAULT</literal>, you are just being		with <literal>DEFAULT</literal>, is just being
redundant unless you want to have an element belonging		redundant unless an element belongs
		wblockUnsubmitted Not Done Inline Actions Extra "with". wblock: Extra "with".
to both <literal>DEFAULT</literal> and other groups at		to both <literal>DEFAULT</literal> and other groups at
the same time (check item <xref		the same time (check item <xref
linkend="porting-master-sites-n-comma-operator"/>).</para>		linkend="porting-master-sites-n-comma-operator"/>).</para>

<para>The following examples are equivalent but the first		<para>These examples are equivalent but the first
one is preferred:</para>		one is preferred:</para>

<programlisting>MASTER_SITES= alpha</programlisting>		<programlisting>MASTER_SITES= alpha</programlisting>

<programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>		<programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Groups are not exclusive, an element may belong to		<para>Groups are not exclusive, an element may belong to
several different groups at the same time and a group		several different groups at the same time and a group
can either have either several different elements or		can either have either several different elements or
none at all. Repeated elements within the same group		none at all.</para>
will be simply that, repeated elements.</para>
</listitem>		</listitem>

<listitem xml:id="porting-master-sites-n-comma-operator">		<listitem xml:id="porting-master-sites-n-comma-operator">
<para>When you want an element to belong to several groups		<para>When an element belongs to several groups
at the same time, you can use the comma operator		at the same time, use the comma operator
(<literal>,</literal>).</para>		(<literal>,</literal>).</para>

<para>Instead of repeating it several times, each time		<para>Instead of repeating it several times, each time
with a different postfix, we can list several groups at		with a different postfix, we can list several groups at
once in a single postfix. For instance,		once in a single postfix. For instance,
<literal>:m,n,o</literal> marks an element that belongs		<literal>:m,n,o</literal> marks an element that belongs
to group <literal>m</literal>, <literal>n</literal> and		to group <literal>m</literal>, <literal>n</literal> and
<literal>o</literal>.</para>		<literal>o</literal>.</para>

<para>All the following examples are equivalent but the		<para>All these examples are equivalent but the
last one is preferred:</para>		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>		<programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>All sites within a given group are sorted according		<para>All sites within a given group are sorted according
to <varname>MASTER_SORT_AWK</varname>. All groups		to <varname>MASTER_SORT_AWK</varname>. All groups
within <varname>MASTER_SITES</varname> and		within <varname>MASTER_SITES</varname> and
<varname>PATCH_SITES</varname> are sorted as		<varname>PATCH_SITES</varname> are sorted as
well.</para>		well.</para>
</listitem>		</listitem>

<listitem xml:id="porting-master-sites-n-group-semantics">		<listitem xml:id="porting-master-sites-n-group-semantics">
<para>Group semantics can be used in any of the following		<para>Group semantics can be used in any of these
		wblockUnsubmitted Not Done Inline Actions s/these/the/ wblock: s/these/the/
variables <varname>MASTER_SITES</varname>,		variables <varname>MASTER_SITES</varname>,
<varname>PATCH_SITES</varname>,		<varname>PATCH_SITES</varname>,
<varname>MASTER_SITE_SUBDIR</varname>,		<varname>MASTER_SITE_SUBDIR</varname>,
<varname>PATCH_SITE_SUBDIR</varname>,		<varname>PATCH_SITE_SUBDIR</varname>,
<varname>DISTFILES</varname>, and		<varname>DISTFILES</varname>, and
<varname>PATCHFILES</varname> according to the following		<varname>PATCHFILES</varname> according to this
syntax:</para>		syntax:</para>

<orderedlist>		<orderedlist>
<listitem>		<listitem>
<para>All <varname>MASTER_SITES</varname>,		<para>All <varname>MASTER_SITES</varname>,
<varname>PATCH_SITES</varname>,		<varname>PATCH_SITES</varname>,
<varname>MASTER_SITE_SUBDIR</varname> and		<varname>MASTER_SITE_SUBDIR</varname> and
<varname>PATCH_SITE_SUBDIR</varname> elements must		<varname>PATCH_SITE_SUBDIR</varname> elements must
▲ Show 20 Lines • Show All 62 Lines • ▼ Show 20 Lines	<orderedlist>
http://site9/:group8		http://site9/:group8
DISTFILES= file1 file2:DEFAULT file3:group3 \		DISTFILES= file1 file2:DEFAULT file3:group3 \
file4:group4,group5,group6 file5:grouping \		file4:group4,group5,group6 file5:grouping \
file6:group7		file6:group7
MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \		MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
directory-one/:group6,DEFAULT \		directory-one/:group6,DEFAULT \
directory</programlisting>		directory</programlisting>

<para>The previous example results in the following		<para>The previous example results in this
fine grained fetching. Sites are listed in the		fine grained fetching. Sites are listed in the
exact order they will be used.</para>		exact order they will be used.</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><filename>file1</filename> will be		<para><filename>file1</filename> will be
fetched from</para>		fetched from</para>

▲ Show 20 Lines • Show All 154 Lines • ▼ Show 20 Lines	MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
</itemizedlist>		</itemizedlist>
</example>		</example>
</listitem>		</listitem>
</orderedlist>		</orderedlist>
</listitem>		</listitem>

<listitem>		<listitem>
<para>How do I group one of the special variables from		<para>How do I group one of the special variables from
<filename>bsd.sites.mk</filename>, e.g.,		<filename>bsd.sites.mk</filename>, for example,
<varname>MASTER_SITE_SOURCEFORGE</varname>?</para>		<varname>MASTER_SITE_SOURCEFORGE</varname>?</para>

<para>See <xref		<para>See <xref
linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para>		linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para>

<example		<example
xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">		xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">

<title>Detailed Use of <literal>MASTER_SITES:n</literal>		<title>Detailed Use of <literal>MASTER_SITES:n</literal>
with		with
<varname>MASTER_SITE_SOURCEFORGE</varname></title>		<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>		DISTFILES= something.tar.gz:sourceforge</programlisting>
</example>		</example>

<para><filename>something.tar.gz</filename> will be		<para><filename>something.tar.gz</filename> will be
fetched from all sites within		fetched from all sites within
<varname>MASTER_SITE_SOURCEFORGE</varname>.</para>		<varname>MASTER_SITE_SOURCEFORGE</varname>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>How do I use this with		<para>How do I use this with
<varname>PATCH<replaceable>*</replaceable></varname>		<varname>PATCH<replaceable>*</replaceable></varname>?</para>
variables?</para>

<para>All examples were done with		<para>All examples were done with
<varname>MASTER<replaceable>*</replaceable></varname>		<varname>MASTER<replaceable>*</replaceable></varname>
variables but they work exactly the same for		but they work exactly the same for
<varname>PATCH<replaceable>*</replaceable></varname>		<varname>PATCH<replaceable>*</replaceable></varname>
ones as can be seen in <xref		ones as can be seen in <xref
linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para>		linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para>

<example		<example
xml:id="ports-master-sites-n-example-detailed-use-patch-sites">		xml:id="ports-master-sites-n-example-detailed-use-patch-sites">

<title>Simplified Use of		<title>Simplified Use of
▲ Show 20 Lines • Show All 126 Lines • ▼ Show 20 Lines	<orderedlist numeration="lowerroman">
</listitem>		</listitem>
</orderedlist>		</orderedlist>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="makefile-dist_subdir">		<sect2 xml:id="makefile-dist_subdir">
<title><varname>DIST_SUBDIR</varname></title>		<title><varname>DIST_SUBDIR</varname></title>

<para>Do not let your port clutter		<para>Do not let the port clutter
<filename>/usr/ports/distfiles</filename>. If your port		<filename>/usr/ports/distfiles</filename>. If the port
requires a lot of files to be fetched, or contains a file that		requires a lot of files to be fetched, or contains a file that
has a name that might conflict with other ports (e.g.,		has a name that might conflict with other ports (for example,
<filename>Makefile</filename>), set		<filename>Makefile</filename>), set
<varname>DIST_SUBDIR</varname> to the name of the port		<varname>DIST_SUBDIR</varname> to the name of the port
(<literal>${PORTNAME}</literal> or		(<literal>${PORTNAME}</literal> or
<literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work		<literal>${PKGNAMEPREFIX}${PORTNAME}</literal> are
fine). This will change <varname>DISTDIR</varname> from the		fine). This will change <varname>DISTDIR</varname> from the
default <filename>/usr/ports/distfiles</filename> to		default <filename>/usr/ports/distfiles</filename> to
<filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, and in		<filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, and in
effect puts everything that is required for your port into		effect puts everything that is required for the port into
that subdirectory.</para>		that subdirectory.</para>

<para>It will also look at the subdirectory with the same name		<para>It will also look at the subdirectory with the same name
on the backup master site at		on the backup master site at
<filename>ftp.FreeBSD.org</filename>. (Setting		<filename>ftp.FreeBSD.org</filename>. (Setting
<varname>DISTDIR</varname> explicitly in your		<varname>DISTDIR</varname> explicitly in
<varname>Makefile</varname> will not accomplish this, so		<filename>Makefile</filename> will not accomplish this, so
please use <varname>DIST_SUBDIR</varname>.)</para>		please use <varname>DIST_SUBDIR</varname>.)</para>

<note>		<note>
<para>This does not affect the		<para>This does not affect
<varname>MASTER_SITES</varname> you define in your		<varname>MASTER_SITES</varname> defined in the
<filename>Makefile</filename>.</para>		<filename>Makefile</filename>.</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="makefile-always_keep_distfiles">		<sect2 xml:id="makefile-always_keep_distfiles">
<title><varname>ALWAYS_KEEP_DISTFILES</varname></title>		<title><varname>ALWAYS_KEEP_DISTFILES</varname></title>

<para>If your port uses binary distfiles and has a license that		<para>If the port uses binary distfiles and has a license that
requires that the source code is provided with packages		requires that the source code is provided with packages
distributed in binary form, e.g., GPL,		distributed in binary form, for example, GPL,
		wblockUnsubmitted Not Done Inline Actions s/for example,/like/ Should probably have <acronym> tags around GPL. wblock: s/for example,/like/ Should probably have <acronym> tags around GPL.
<varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the		<varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the
&os; build cluster to keep a copy of the files specified in		&os; build cluster to keep a copy of the files specified in
<varname>DISTFILES</varname>. Users of these ports will		<varname>DISTFILES</varname>. Users of these ports will
generally not need these files, so it is a good idea to only		generally not need these files, so it is a good idea to only
add the source distfiles to <varname>DISTFILES</varname> when		add the source distfiles to <varname>DISTFILES</varname> when
<varname>PACKAGE_BUILDING</varname> is defined.</para>		<varname>PACKAGE_BUILDING</varname> is defined.</para>

<example		<example
xml:id="ports-master-sites-n-example-always-keep-distfiles">		xml:id="ports-master-sites-n-example-always-keep-distfiles">

<title>Use of		<title>Use of
<varname>ALWAYS_KEEP_DISTFILES</varname></title>		<varname>ALWAYS_KEEP_DISTFILES</varname></title>

<programlisting>.if defined(PACKAGE_BUILDING)		<programlisting>.if defined(PACKAGE_BUILDING)
DISTFILES+= <replaceable>foo.tar.gz</replaceable>		DISTFILES+= <replaceable>foo.tar.gz</replaceable>
ALWAYS_KEEP_DISTFILES= yes		ALWAYS_KEEP_DISTFILES= yes
.endif</programlisting>		.endif</programlisting>
</example>		</example>

<para>When adding extra files to <varname>DISTFILES</varname>,		<para>When adding extra files to <varname>DISTFILES</varname>,
make sure you also add them to <filename>distinfo</filename>.		make sure to also add them to <filename>distinfo</filename>.
Also, the additional files will normally be extracted into		Also, the additional files will normally be extracted into
<varname>WRKDIR</varname> as well, which for some ports may		<varname>WRKDIR</varname> as well, which for some ports may
lead to undesirable side effects and require special		lead to undesirable side effects and require special
handling.</para>		handling.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="makefile-maintainer">		<sect1 xml:id="makefile-maintainer">
▲ Show 20 Lines • Show All 88 Lines • ▼ Show 20 Lines	<para>The &a.portmgr; reserves the right to revoke or override
&a.security-officer; reserves the right to revoke or override		&a.security-officer; reserves the right to revoke or override
maintainership for security reasons.</para>		maintainership for security reasons.</para>
</sect1>		</sect1>

<sect1 xml:id="makefile-comment">		<sect1 xml:id="makefile-comment">
<title><varname>COMMENT</varname></title>		<title><varname>COMMENT</varname></title>

<para>This is a one-line description of the port. Please respect		<para>This is a one-line description of the port. Please respect
the following rules:</para>		these rules:</para>

<orderedlist>		<orderedlist>
<listitem>		<listitem>
<para>Try to keep the COMMENT value at no longer than 70		<para>Try to keep the COMMENT value at no longer than 70
characters, as this line will be used by		characters, as this line will be used by
<command>pkg info</command> (see &man.pkg-info.8;) to		<command>pkg info</command> (see &man.pkg-info.8;) to
display a one-line summary of the port;</para>		display a one-line summary of the port;</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Do <emphasis>not</emphasis> include the package name (or		<para>Do <emphasis>not</emphasis> include the package name (or
version number of the software);</para>		version number of the software);</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>The comment should begin with a capital and end without		<para>The comment must begin with a capital and end without
a period;</para>		a period;</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Do not start with an indefinite article (i.e., A or		<para>Do not start with an indefinite article (that is, A or
An);</para>		An);</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Names are capitalized (for example, Apache, JavaScript,		<para>Names are capitalized (for example, Apache, JavaScript,
Perl);</para>		Perl);</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>For lists of words, use the Oxford comma (e.g., green,		<para>For lists of words, use the Oxford comma (for example,
red<emphasis>,</emphasis> and blue);</para>		green, red<emphasis>,</emphasis> and blue);</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>Spell check the text.</para>		<para>Spell check the text.</para>
</listitem>		</listitem>
</orderedlist>		</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		<para>The COMMENT variable immediately follows the
		wblockUnsubmitted Not Done Inline Actions Good catch! wblock: Good catch!
MAINTAINER variable in the <filename>Makefile</filename>.</para>		MAINTAINER variable in the <filename>Makefile</filename>.</para>
</sect1>		</sect1>

<sect1 xml:id="makefile-portscout">		<sect1 xml:id="makefile-portscout">
<title><varname>PORTSCOUT</varname></title>		<title><varname>PORTSCOUT</varname></title>

<para><application>Portscout</application> is an automated		<para><application>Portscout</application> is an automated
distfile check utility for the &os; Ports Collection,		distfile check utility for the &os; Ports Collection,
described in detail in <xref linkend="distfile-survey"/>.</para>		described in detail in <xref linkend="distfile-survey"/>.</para>

<para>The <varname>PORTSCOUT</varname> variable defines special		<para><varname>PORTSCOUT</varname> defines special
conditions within which the <application>Portscout</application>		conditions within which the <application>Portscout</application>
distfile scanner should be restricted.</para>		distfile scanner is restricted.</para>

<para>Situations where the <varname>PORTSCOUT</varname> variable		<para>Situations where <varname>PORTSCOUT</varname>
should be set include:</para>		is set include:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>When distfiles should be ignored, whether for specific		<para>When distfiles has to be ignored, whether for specific
		wblockUnsubmitted Not Done Inline Actions s/has to/have to/ wblock: s/has to/have to/
versions, or specific minor revisions. For example, to		versions, or specific minor revisions. For example, to
exclude version <replaceable>8.2</replaceable> from distfile		exclude version <replaceable>8.2</replaceable> from distfile
version checks because it is known to be broken, add:</para>		version checks because it is known to be broken, add:</para>

<programlisting>PORTSCOUT= ignore:8.2</programlisting>		<programlisting>PORTSCOUT= ignore:8.2</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>When specific versions or specific major and minor		<para>When specific versions or specific major and minor
revisions of a distfile should be checked. For example, if		revisions of a distfile must be checked. For example, if
only version <replaceable>0.6.4</replaceable> should be		only version <replaceable>0.6.4</replaceable> must be
monitored because newer versions have compatibility issues		monitored because newer versions have compatibility issues
with &os;, add:</para>		with &os;, add:</para>

<programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>		<programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>
</listitem>		</listitem>

<listitem>		<listitem>
<para>When URLs listing the available versions differ from the		<para>When URLs listing the available versions differ from the
Show All 29 Lines	.endif</programlisting>
the shared library, <replaceable>dir</replaceable> is the		the shared library, <replaceable>dir</replaceable> is the
directory in which to find it in case it is not available.		directory in which to find it in case it is not available.
For example,</para>		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		<para>will check for a shared jpeg library with any version, and
descend into the <filename>graphics/jpeg</filename>		descend into the <filename>graphics/jpeg</filename>
subdirectory of your ports tree to build and install it if it		subdirectory of the ports tree to build and install it if it
is not found.</para>		is not found.</para>

<para>The dependency is checked twice, once from within the		<para>The dependency is checked twice, once from within the
<buildtarget>build</buildtarget> target and then from within		<buildtarget>build</buildtarget> target and then from within
the <buildtarget>install</buildtarget> target. Also, the name		the <buildtarget>install</buildtarget> target. Also, the name
of the dependency is put into the package so that		of the dependency is put into the package so that
<command>pkg install</command> (see &man.pkg-install.8;) will		<command>pkg install</command> (see &man.pkg-install.8;) will
automatically install it if it is not on the user's		automatically install it if it is not on the user's
Show All 22 Lines	program exists in the search path.</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>		xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting>

<para>will check if the file or directory		<para>will check if the file or directory
<filename>/usr/local/news/bin/innd</filename> exists, and		<filename>/usr/local/news/bin/innd</filename> exists, and
build and install it from the <filename>news/inn</filename>		build and install it from the <filename>news/inn</filename>
subdirectory of the ports tree if it is not found. It will		subdirectory of the ports tree if it is not found. It will
also see if an executable called <command>xmlcatmgr</command>		also see if an executable called <command>xmlcatmgr</command>
is in the search path, and descend into the		is in the search path, and descend into
<filename>textproc/xmlcatmgr</filename> subdirectory of your		<filename>textproc/xmlcatmgr</filename>
ports tree to build and install it if it is not found.</para>		to build and install it if it is not found.</para>

<note>		<note>
<para>In this case, <command>innd</command> is actually an		<para>In this case, <command>innd</command> is actually an
executable; if an executable is in a place that is not		executable; if an executable is in a place that is not
expected to be in the search path, you should use the full		expected to be in the search path, use the full
pathname.</para>		pathname.</para>
</note>		</note>

<note>		<note>
<para>The official search <envar>PATH</envar> used on the		<para>The official search <envar>PATH</envar> used on the
ports build cluster is</para>		ports build cluster is</para>

<programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>		<programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>
Show All 17 Lines	other:</para>

<programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>		<programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>

<para>However, such assignment can pollute run-time		<para>However, such assignment can pollute run-time
dependencies with entries not defined in the port's original		dependencies with entries not defined in the port's original
<varname>BUILD_DEPENDS</varname>. This happens because of		<varname>BUILD_DEPENDS</varname>. This happens because of
&man.make.1;'s lazy evaluation of variable assignment.		&man.make.1;'s lazy evaluation of variable assignment.
Consider a <filename>Makefile</filename> with		Consider a <filename>Makefile</filename> with
<varname>USE_<replaceable>*</replaceable></varname> variables,		<varname>USE_<replaceable>*</replaceable></varname>,
which are processed by <filename>ports/Mk/bsd.*.mk</filename>		which are processed by <filename>ports/Mk/bsd.*.mk</filename>
to augment initial build dependencies. For example,		to augment initial build dependencies. For example,
<literal>USES= gmake</literal> adds		<literal>USES= gmake</literal> adds
<package role="port">devel/gmake</package> to		<package role="port">devel/gmake</package> to
<varname>BUILD_DEPENDS</varname>. To prevent such additional		<varname>BUILD_DEPENDS</varname>. To prevent such additional
dependencies from polluting <varname>RUN_DEPENDS</varname>,		dependencies from polluting <varname>RUN_DEPENDS</varname>,
take care to assign with expansion, i.e., expand the value		take care to assign with expansion, that is, expand the value
before assigning it to the variable:</para>		before assigning it to the variable:</para>

<programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting>		<programlisting>RUN_DEPENDS:= ${BUILD_DEPENDS}</programlisting>
</sect2>		</sect2>

<sect2 xml:id="makefile-build_depends">		<sect2 xml:id="makefile-build_depends">
<title><varname>BUILD_DEPENDS</varname></title>		<title><varname>BUILD_DEPENDS</varname></title>

<para>This variable specifies executables or files this port		<para>This variable specifies executables or files this port
requires to build. Like <varname>RUN_DEPENDS</varname>, it		requires to build. Like <varname>RUN_DEPENDS</varname>, it
is a list of		is a list of
<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>		<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
tuples. For example,</para>		tuples. For example,</para>

<programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>		<programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>

<para>will check for an executable called		<para>will check for an executable called
<command>unzip</command>, and descend into the		<command>unzip</command>, and descend into the
<filename>archivers/unzip</filename> subdirectory of your		<filename>archivers/unzip</filename> subdirectory of the
ports tree to build and install it if it is not found.</para>		ports tree to build and install it if it is not found.</para>

<note>		<note>
<para><quote>build</quote> here means everything from		<para><quote>build</quote> here means everything from
extraction to compilation. The dependency is checked from		extraction to compilation. The dependency is checked from
within the <buildtarget>extract</buildtarget> target. The		within the <buildtarget>extract</buildtarget> target. The
<replaceable>target</replaceable> part can be omitted if it		<replaceable>target</replaceable> part can be omitted if it
is the same as <varname>DEPENDS_TARGET</varname></para>		is the same as <varname>DEPENDS_TARGET</varname></para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="makefile-fetch_depends">		<sect2 xml:id="makefile-fetch_depends">
<title><varname>FETCH_DEPENDS</varname></title>		<title><varname>FETCH_DEPENDS</varname></title>

<para>This variable specifies executables or files this port		<para>This variable specifies executables or files this port
requires to fetch. Like the previous two, it is a list of		requires to fetch. Like the previous two, it is a list of
<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>		<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
tuples. For example,</para>		tuples. For example,</para>

<programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>		<programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>

<para>will check for an executable called		<para>will check for an executable called
<command>ncftp2</command>, and descend into the		<command>ncftp2</command>, and descend into the
<filename>net/ncftp2</filename> subdirectory of your ports		<filename>net/ncftp2</filename> subdirectory of the ports
tree to build and install it if it is not found.</para>		tree to build and install it if it is not found.</para>

<para>The dependency is checked from within the		<para>The dependency is checked from within the
<buildtarget>fetch</buildtarget> target. The		<buildtarget>fetch</buildtarget> target. The
<replaceable>target</replaceable> part can be omitted if it is		<replaceable>target</replaceable> part can be omitted if it is
the same as <varname>DEPENDS_TARGET</varname>.</para>		the same as <varname>DEPENDS_TARGET</varname>.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-extract_depends">		<sect2 xml:id="makefile-extract_depends">
<title><varname>EXTRACT_DEPENDS</varname></title>		<title><varname>EXTRACT_DEPENDS</varname></title>

<para>This variable specifies executables or files this port		<para>This variable specifies executables or files this port
requires for extraction. Like the previous, it is a list of		requires for extraction. Like the previous, it is a list of
<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>		<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
tuples. For example,</para>		tuples. For example,</para>

<programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>		<programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>

<para>will check for an executable called		<para>will check for an executable called
<command>unzip</command>, and descend into the		<command>unzip</command>, and descend into the
<filename>archivers/unzip</filename> subdirectory of your		<filename>archivers/unzip</filename> subdirectory of the
ports tree to build and install it if it is not found.</para>		ports tree to build and install it if it is not found.</para>

<para>The dependency is checked from within the		<para>The dependency is checked from within the
<buildtarget>extract</buildtarget> target. The		<buildtarget>extract</buildtarget> target. The
<replaceable>target</replaceable> part can be omitted if it		<replaceable>target</replaceable> part can be omitted if it
is the same as <varname>DEPENDS_TARGET</varname>.</para>		is the same as <varname>DEPENDS_TARGET</varname>.</para>

<note>		<note>
Show All 12 Lines	<sect2 xml:id="makefile-patch_depends">
<para>This variable specifies executables or files this port		<para>This variable specifies executables or files this port
requires to patch. Like the previous, it is a list of		requires to patch. Like the previous, it is a list of
<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>		<replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
tuples. For example,</para>		tuples. For example,</para>

<programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>		<programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>

<para>will descend into the <filename>java/jfc</filename>		<para>will descend into the <filename>java/jfc</filename>
subdirectory of your ports tree to extract it.</para>		subdirectory of the ports tree to extract it.</para>

<para>The dependency is checked from within the		<para>The dependency is checked from within the
<buildtarget>patch</buildtarget> target. The		<buildtarget>patch</buildtarget> target. The
<replaceable>target</replaceable> part can be omitted if it		<replaceable>target</replaceable> part can be omitted if it
is the same as <varname>DEPENDS_TARGET</varname>.</para>		is the same as <varname>DEPENDS_TARGET</varname>.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-uses">		<sect2 xml:id="makefile-uses">
Show All 37 Lines	.endif</programlisting>
<programlisting>USE_GCC=X.Y</programlisting>		<programlisting>USE_GCC=X.Y</programlisting>

<para>(where X.Y is version number) would add a dependency		<para>(where X.Y is version number) would add a dependency
on gccXY for every port, including		on gccXY for every port, including
<literal>lang/gccXY</literal> itself!</para>		<literal>lang/gccXY</literal> itself!</para>
</note>		</note>

<table frame="none" xml:id="makefile-use-vars-table">		<table frame="none" xml:id="makefile-use-vars-table">
<title>The		<title><varname>USE_<replaceable>*</replaceable></varname></title>
<varname>USE_<replaceable>*</replaceable></varname>
Variables</title>

<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry>Variable</entry>		<entry>Variable</entry>
<entry>Means</entry>		<entry>Means</entry>
</row>		</row>
</thead>		</thead>
Show All 10 Lines	<tgroup cols="2">
port would be installed when default C/C++ compiler is		port would be installed when default C/C++ compiler is
Clang); or <literal>yes</literal> (means always use		Clang); or <literal>yes</literal> (means always use
stable, modern GCC from <literal>lang/gcc</literal>		stable, modern GCC from <literal>lang/gcc</literal>
port). The exact version can also be specified, with		port). The exact version can also be specified, with
a value such as <literal>4.7</literal>. The minimal		a value such as <literal>4.7</literal>. The minimal
required version can be specified as		required version can be specified as
<literal>4.6+</literal>. The GCC from the base system		<literal>4.6+</literal>. The GCC from the base system
is used when it satisfies the requested version,		is used when it satisfies the requested version,
otherwise an appropriate compiler in built from the		otherwise an appropriate compiler in built from the
port, and the <varname>CC</varname> and		port, and <varname>CC</varname> and
		wblockUnsubmitted Not Done Inline Actions s/in/is/ (Not yours, I know.) wblock: s/in/is/ (Not yours, I know.)
		matAuthorUnsubmitted Not Done Inline Actions No problem, I also correct the few I find :-) mat: No problem, I also correct the few I find :-)
<varname>CXX</varname> variables are adjusted		<varname>CXX</varname> are adjusted
accordingly.</entry>		accordingly.</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</table>		</table>

<para>Variables related to <application>gmake</application> and		<para>Variables related to <application>gmake</application> and
the <filename>configure</filename> script are described in		<filename>configure</filename> are described in
<xref linkend="building"/>, while		<xref linkend="building"/>, while
<application>autoconf</application>,		<application>autoconf</application>,
<application>automake</application> and		<application>automake</application> and
<application>libtool</application> are described in		<application>libtool</application> are described in
<xref linkend="using-autotools"/>.		<xref linkend="using-autotools"/>.
<application>Perl</application> related variables are		<application>Perl</application> related variables are
described in <xref linkend="using-perl"/>. X11 variables are		described in <xref linkend="using-perl"/>. X11 variables are
listed in <xref linkend="using-x11"/>.		listed in <xref linkend="using-x11"/>.
Show All 13 Lines	.endif</programlisting>
<application>Xfce</application>.</para>		<application>Xfce</application>.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-version-dependency">		<sect2 xml:id="makefile-version-dependency">
<title>Minimal Version of a Dependency</title>		<title>Minimal Version of a Dependency</title>

<para>A minimal version of a dependency can be specified in any		<para>A minimal version of a dependency can be specified in any
<varname><replaceable>*</replaceable>_DEPENDS</varname>		<varname><replaceable>*</replaceable>_DEPENDS</varname>
variable except <varname>LIB_DEPENDS</varname> using the		except <varname>LIB_DEPENDS</varname> using this
following syntax:</para>		syntax:</para>

<programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>		<programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>

<para>The first field contains a dependent package name, which		<para>The first field contains a dependent package name, which
must match the entry in the package database, a comparison		must match the entry in the package database, a comparison
sign, and a package version. The dependency is satisfied if		sign, and a package version. The dependency is satisfied if
p5-Spiffy-0.26 or newer is installed on the machine.</para>		p5-Spiffy-0.26 or newer is installed on the machine.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-note-on-dependencies">		<sect2 xml:id="makefile-note-on-dependencies">
<title>Notes on Dependencies</title>		<title>Notes on Dependencies</title>

<para>As mentioned above, the default target to call when a		<para>As mentioned above, the default target to call when a
dependency is required is		dependency is required is
<buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to		<buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to
<literal>install</literal>. This is a user variable; it is		<literal>install</literal>. This is a user variable; it is
never defined in a port's <filename>Makefile</filename>. If		never defined in a port's <filename>Makefile</filename>. If
your port needs a special way to handle a dependency, use the		the port needs a special way to handle a dependency, use the
<literal>:target</literal> part of the		<literal>:target</literal> part of
<varname><replaceable>*</replaceable>_DEPENDS</varname>		<varname><replaceable>*</replaceable>_DEPENDS</varname>
variables instead of redefining		instead of redefining
<varname>DEPENDS_TARGET</varname>.</para>		<varname>DEPENDS_TARGET</varname>.</para>

<para>When you type <command>make clean</command>, its		<para>When running <command>make clean</command>, the port
dependencies are automatically cleaned too. If you do not		dependencies are automatically cleaned too. If this is not
wish this to happen, define the variable		desirable, define
<varname>NOCLEANDEPENDS</varname> in your environment. This		<varname>NOCLEANDEPENDS</varname> in the environment. This
may be particularly desirable if the port has something that		may be particularly desirable if the port has something that
takes a long time to rebuild in its dependency list, such as		takes a long time to rebuild in its dependency list, such as
KDE, GNOME or Mozilla.</para>		KDE, GNOME or Mozilla.</para>

<para>To depend on another port unconditionally, use the		<para>To depend on another port unconditionally, use the
variable <literal>${NONEXISTENT}</literal> as the first field		variable <literal>${NONEXISTENT}</literal> as the first field
of <varname>BUILD_DEPENDS</varname> or		of <varname>BUILD_DEPENDS</varname> or
<varname>RUN_DEPENDS</varname>. Use this only when you need		<varname>RUN_DEPENDS</varname>. Use this only when
to get the source of the other port. You can often save		the source of the other port is needed. Compilation time can
compilation time by specifying the target too. For		be saved by specifying the target too. For
		wblockUnsubmitted Not Done Inline Actions Nice! wblock: Nice!
instance</para>		instance</para>

<programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>		<programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>

<para>will always descend to the <literal>jpeg</literal> port		<para>will always descend to the <literal>jpeg</literal> port
and extract it.</para>		and extract it.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-circular-dependencies">		<sect2 xml:id="makefile-circular-dependencies">
<title>Circular Dependencies Are Fatal</title>		<title>Circular Dependencies Are Fatal</title>

<important>		<important>
<para>Do not introduce any circular dependencies into the		<para>Do not introduce any circular dependencies into the
ports tree!</para>		ports tree!</para>
</important>		</important>

<para>The ports building technology does not tolerate circular		<para>The ports building technology does not tolerate circular
dependencies. If you introduce one, you will have someone,		dependencies. If one is introduced, someone, somewhere in the
somewhere in the world, whose &os; installation will break		world, will have is &os; installation broken
		wblockUnsubmitted Not Done Inline Actions s/is/their/ wblock: s/is/their/
almost immediately, with many others quickly to follow. These		almost immediately, with many others quickly to follow. These
can really be hard to detect; if in doubt, before you make		can really be hard to detect; if in doubt, before making
that change, make sure you have done the following:		that change, make sure to run this:
		wblockUnsubmitted Not Done Inline Actions Break at semicolon. wblock: Break at semicolon.
		wblockUnsubmitted Not Done Inline Actions Remove "this" wblock: Remove "this"
<command>cd /usr/ports; make index</command>. That process		<command>cd /usr/ports; make index</command>. That process
can be quite slow on older machines, but you may be able to		can be quite slow on older machines, but it may be able to
save a large number of people—including yourself—		save a large number of people—including yourself—
		wblockUnsubmitted Not Done Inline Actions Replace — with comma. wblock: Replace — with comma.
a lot of grief in the process.</para>		a lot of grief in the process.</para>
</sect2>		</sect2>

<sect2 xml:id="makefile-automatic-dependencies">		<sect2 xml:id="makefile-automatic-dependencies">
<title>Problems Caused by Automatic Dependencies</title>		<title>Problems Caused by Automatic Dependencies</title>

<para>Dependencies must be declared either explicitly or by		<para>Dependencies must be declared either explicitly or by
using the		using the
Show All 35 Lines	BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar</programlisting>
not cause inconsistencies in the index of a batch of ports,		not cause inconsistencies in the index of a batch of ports,
provided the options were defined prior to the index build.		provided the options were defined prior to the index build.
Simple scripts can then be used to automate the building,		Simple scripts can then be used to automate the building,
installation, and updating of these ports and their		installation, and updating of these ports and their
packages.</para>		packages.</para>
</sect2>		</sect2>

<sect2 xml:id="use-want">		<sect2 xml:id="use-want">
<title><varname>USE_</varname> and		<title><varname>USE_<replaceable>*</replaceable></varname> and
<varname>WANT_</varname></title>		<varname>WANT_<replaceable>*</replaceable></varname></title>

<para><varname>USE_</varname> variables are set by the port		<para><varname>USE_<replaceable>*</replaceable></varname> are set by the port
maintainer to define software on which this port depends. A		maintainer to define software on which this port depends. A
port that needs Firefox would set</para>		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		<para>Some <varname>USE_<replaceable>*</replaceable></varname> can accept version
numbers or other parameters. For example, a port that		numbers or other parameters. For example, a port that
requires Apache 2.2 would set</para>		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,		<para>For more control over dependencies in some cases,
<varname>WANT_</varname> variables are available to more		<varname>WANT_<replaceable>*</replaceable></varname> are available to more
precisely specify what is needed. For example, consider the		precisely specify what is needed. For example, consider the
<package role="port">mail/squirrelmail</package> port. This		<package role="port">mail/squirrelmail</package> port. This
port needs some PHP modules, which are listed in the		port needs some PHP modules, which are listed in
<varname>USE_PHP</varname> variable:</para>		<varname>USE_PHP</varname>:</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		<para>Those modules may be available in CLI or web versions, so
the web version is selected with a		the web version is selected with
<varname>WANT_</varname> variable:</para>		<varname>WANT_<replaceable>*</replaceable></varname>:</para>

<programlisting>WANT_PHP_WEB= yes</programlisting>		<programlisting>WANT_PHP_WEB= yes</programlisting>

<para>Available <varname>USE_</varname> and		<para>Available <varname>USE_<replaceable>*</replaceable></varname> and
<varname>WANT_</varname> variables are defined in the files in		<varname>WANT_<replaceable>*</replaceable></varname> are defined in the files in
<filename class="directory">/usr/ports/Mk</filename>.</para>		<filename class="directory">/usr/ports/Mk</filename>.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="makefile-masterdir">		<sect1 xml:id="makefile-masterdir">
<title><varname>MASTERDIR</varname></title>		<title><varname>MASTERDIR</varname></title>

<para>If your port needs to build slightly different versions of		<para>If the port needs to build slightly different versions of
packages by having a variable (for instance, resolution, or		packages by having a variable (for instance, resolution, or
paper size) take different values, create one subdirectory per		paper size) take different values, create one subdirectory per
package to make it easier for users to see what to do, but try		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		to share as many files as possible between ports. Typically, by
only need a very short <filename>Makefile</filename> in all but		variables cleverly only a very short
		wblockUnsubmitted Not Done Inline Actions "using variables cleverly, only a very short" wblock: "using variables cleverly, only a very short"
one of the directories if you use variables cleverly. In the		<filename>Makefile</filename> is needed in all but one of the
sole <filename>Makefile</filename>, you can use		directories. In the sole <filename>Makefile</filename>, use
<varname>MASTERDIR</varname> to specify the directory where the		<varname>MASTERDIR</varname> to specify the directory where the
rest of the files are. Also, use a variable as part of <link		rest of the files are. Also, use a variable as part of <link
linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link>		linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link>
so the packages will have different names.</para>		so the packages will have different names.</para>

<para>This will be best demonstrated by an example. This is part		<para>This will be best demonstrated by an example. This is part
of <filename>japanese/xdvi300/Makefile</filename>;</para>		of <filename>japanese/xdvi300/Makefile</filename>;</para>

<programlisting>PORTNAME= xdvi		<programlisting>PORTNAME= xdvi
PORTVERSION= 17		PORTVERSION= 17
PKGNAMEPREFIX= ja-		PKGNAMEPREFIX= ja-
PKGNAMESUFFIX= ${RESOLUTION}		PKGNAMESUFFIX= ${RESOLUTION}
:		:
# default		# default
RESOLUTION?= 300		RESOLUTION?= 300
.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \		.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
${RESOLUTION} != 300 && ${RESOLUTION} != 400		${RESOLUTION} != 300 && ${RESOLUTION} != 400
@${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""		@${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
@${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."		@${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."
@${FALSE}		@${FALSE}
.endif</programlisting>		.endif</programlisting>

<para><package role="port">japanese/xdvi300</package> also has all		<para><package role="port">japanese/xdvi300</package> also has all
the regular patches, package files, etc. If you type		the regular patches, package files, etc. Runnig
		wblockUnsubmitted Not Done Inline Actions s/Runnig/Running/ wblock: s/Runnig/Running/
<command>make</command> there, it will take the default value		<command>make</command> there, it will take the default value
for the resolution (300) and build the port normally.</para>		for the resolution (300) and build the port normally.</para>

<para>As for other resolutions, this is the		<para>As for other resolutions, this is the
<emphasis>entire</emphasis>		<emphasis>entire</emphasis>
<filename>xdvi118/Makefile</filename>:</para>		<filename>xdvi118/Makefile</filename>:</para>

<programlisting>RESOLUTION= 118		<programlisting>RESOLUTION= 118
MASTERDIR= ${.CURDIR}/../xdvi300		MASTERDIR= ${.CURDIR}/../xdvi300

.include "${MASTERDIR}/Makefile"</programlisting>		.include "${MASTERDIR}/Makefile"</programlisting>

<para>(<filename>xdvi240/Makefile</filename> and		<para>(<filename>xdvi240/Makefile</filename> and
<filename>xdvi400/Makefile</filename> are similar). The		<filename>xdvi400/Makefile</filename> are similar).
<varname>MASTERDIR</varname> definition tells		<varname>MASTERDIR</varname> definition tells
<filename>bsd.port.mk</filename> that the regular set of		<filename>bsd.port.mk</filename> that the regular set of
subdirectories like <varname>FILESDIR</varname> and		subdirectories like <varname>FILESDIR</varname> and
<varname>SCRIPTDIR</varname> are to be found under		<varname>SCRIPTDIR</varname> are to be found under
<filename>xdvi300</filename>. The		<filename>xdvi300</filename>. The
<literal>RESOLUTION=118</literal> line will override the		<literal>RESOLUTION=118</literal> line will override the
<literal>RESOLUTION=300</literal> line in		<literal>RESOLUTION=300</literal> line in
<filename>xdvi300/Makefile</filename> and the port will be built		<filename>xdvi300/Makefile</filename> and the port will be built
with resolution set to 118.</para>		with resolution set to 118.</para>
</sect1>		</sect1>

<sect1 xml:id="makefile-manpages">		<sect1 xml:id="makefile-manpages">
<title>Man Pages</title>		<title>Man Pages</title>

<para>If your port anchors its man tree somewhere other than		<para>If the port anchors its man tree somewhere other than
<varname>PREFIX</varname>, you can use		<varname>PREFIX</varname>, use
<varname>MANDIRS</varname> to specify those directories. Note		<varname>MANDIRS</varname> to specify those directories. Note
that the files corresponding to manual pages should be placed in		that the files corresponding to manual pages must be be placed in
<filename>pkg-plist</filename> along with the rest of the files.		<filename>pkg-plist</filename> along with the rest of the files.
The purpose of <varname>MANDIRS</varname> is to enable automatic		The purpose of <varname>MANDIRS</varname> is to enable automatic
compression of manual pages, therefore the file names should be		compression of manual pages, therefore the file names are
suffixed with <filename>.gz</filename>.</para>		suffixed with <filename>.gz</filename>.</para>
</sect1>		</sect1>

<sect1 xml:id="makefile-info">		<sect1 xml:id="makefile-info">
<title>Info Files</title>		<title>Info Files</title>

<para>If your package needs to install GNU info files, they should		<para>If the package needs to install GNU info files, list them
be listed in the <varname>INFO</varname> variable (without the		in <varname>INFO</varname> (without the
		wblockUnsubmitted Not Done Inline Actions <acronym> tags on GNU. wblock: <acronym> tags on GNU.
trailing <literal>.info</literal>), one entry per document.		trailing <literal>.info</literal>), one entry per document.
These files are assumed to be installed to		These files are assumed to be installed to
<filename>PREFIX/INFO_PATH</filename>. You can change		<filename>PREFIX/INFO_PATH</filename>. Change
<varname>INFO_PATH</varname> if your package uses a different		<varname>INFO_PATH</varname> if the package uses a different
location. However, this is not recommended. These entries		location. However, this is not recommended. These entries
contain just the path relative to		contain just the path relative to
<filename>PREFIX/INFO_PATH</filename>. For example,		<filename>PREFIX/INFO_PATH</filename>. For example,
<package role="port">lang/gcc34</package> installs info files to		<package role="port">lang/gcc34</package> installs info files to
<filename>PREFIX/INFO_PATH/gcc34</filename>, and		<filename>PREFIX/INFO_PATH/gcc34</filename>, and
<varname>INFO</varname> will be something like this:</para>		<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>
Show All 17 Lines	<para>Many applications can be built with optional or differing
two or more ports for the price of one.</para>		two or more ports for the price of one.</para>

<sect2 xml:id="makefile-options-options">		<sect2 xml:id="makefile-options-options">
<title><varname>OPTIONS</varname></title>		<title><varname>OPTIONS</varname></title>

<sect3 xml:id="makefile-options-background">		<sect3 xml:id="makefile-options-background">
<title>Background</title>		<title>Background</title>

<para>The <varname>OPTIONS_*</varname> variables give the		<para><varname>OPTIONS_<replaceable>*</replaceable></varname> give the
user installing the port a dialog showing the available		user installing the port a dialog showing the available
options, and then saves those options to		options, and then saves those options to
<filename>/var/db/ports/${UNIQUENAME}/options</filename>.		<filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>.
The next time the port is built, the options are		The next time the port is built, the options are
reused.</para>		reused. <varname>PORT_DBDIR</varname> defaults to
		<filename>/var/db/ports</filename>.
		<varname>OPTIONS_NAME</varname> is to the port origin with
		an underscore as the space separator, for example, for
		<package role="port">dns/bind99</package> it will be
		<literal>dns_bind99</literal>.</para>

<para>When the user runs <command>make config</command> (or		<para>When the user runs <command>make config</command> (or
runs <command>make build</command> for the first time), the		runs <command>make build</command> for the first time), the
framework checks for		framework checks for
<filename>/var/db/ports/${UNIQUENAME}/options</filename>.		<filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>.
If that file does not exist, the values of		If that file does not exist, the values of
<varname>OPTIONS_*</varname> are used, and a dialog box is		<varname>OPTIONS_<replaceable>*</replaceable></varname> are used, and a dialog box is
displayed where the options can be enabled or disabled.		displayed where the options can be enabled or disabled.
Then the <filename>options</filename> file is saved and the		Then <filename>options</filename> is saved and the
configured variables are used when building the port.</para>		configured variables are used when building the port.</para>

<para>If a new version of the port adds new		<para>If a new version of the port adds new
<varname>OPTIONS</varname>, the dialog will be presented to		<varname>OPTIONS</varname>, the dialog will be presented to
the user with the saved values of old		the user with the saved values of old
<varname>OPTIONS</varname> prefilled.</para>		<varname>OPTIONS</varname> prefilled.</para>

<para><command>make showconfig</command> shows the saved		<para><command>make showconfig</command> shows the saved
Show All 17 Lines
OPT2_DESC= Describe OPT2		OPT2_DESC= Describe OPT2
OPT3_DESC= Describe OPT3		OPT3_DESC= Describe OPT3
OPT4_DESC= Describe OPT4		OPT4_DESC= Describe OPT4
OPT5_DESC= Describe OPT5		OPT5_DESC= Describe OPT5
OPT6_DESC= Describe OPT6</programlisting>		OPT6_DESC= Describe OPT6</programlisting>

<para><filename>ports/Mk/bsd.options.desc.mk</filename>		<para><filename>ports/Mk/bsd.options.desc.mk</filename>
has descriptions for many common <varname>OPTIONS</varname>.		has descriptions for many common <varname>OPTIONS</varname>.
While often useful, they should be overridden if the		While often useful, override them if the
description is insufficient for the port.</para>		description is insufficient for the port.</para>

<tip>		<tip>
<para>When describing options, view it from the		<para>When describing options, view it from the
perspective of the user: <quote>What functionality does it		perspective of the user: <quote>What functionality does it
change?</quote>		change?</quote>
and <quote>Why would I want to enable this?</quote>		and <quote>Why would I want to enable this?</quote>
Do not just repeat the name. For example, describing the		Do not just repeat the name. For example, describing the
<literal>NLS</literal> option as		<literal>NLS</literal> option as
<quote>include NLS support</quote> does not help the user,		<quote>include NLS support</quote> does not help the user,
who can already see the option name but may not know what		who can already see the option name but may not know what
it means. Describing it as <quote>Native Language Support		it means. Describing it as <quote>Native Language Support
via gettext utilities</quote> is much more		via gettext utilities</quote> is much more
helpful.</para>		helpful.</para>
</tip>		</tip>

<note>		<important>
<para>Option names should always be in all uppercase. They		<para>Option names are always in all uppercase. They
should not use mixed case or lowercase.</para>		cannot use mixed case or lowercase.</para>
</note>		</important>

<para><varname>OPTIONS</varname> can be grouped as radio		<para><varname>OPTIONS</varname> can be grouped as radio
choices, where only one choice from each group is		choices, where only one choice from each group is
allowed:</para>		allowed:</para>

<programlisting>OPTIONS_SINGLE= SG1		<programlisting>OPTIONS_SINGLE= SG1
OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting>		OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting>

		wblockUnsubmitted Not Done Inline Actions s/time/times/ wblock: s/time/times/
<para><varname>OPTIONS</varname> can be grouped as radio		<para><varname>OPTIONS</varname> can be grouped as radio
choices, where none or only one choice from each group		choices, where none or only one choice from each group
is allowed:</para>		is allowed:</para>

<programlisting>OPTIONS_RADIO= RG1		<programlisting>OPTIONS_RADIO= RG1
OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting>		OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting>

<para><varname>OPTIONS</varname> can also be grouped as		<para><varname>OPTIONS</varname> can also be grouped as
Show All 14 Lines	OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting>
<para><varname>OPTIONS</varname> are unset by default,		<para><varname>OPTIONS</varname> are unset by default,
unless they are listed in		unless they are listed in
<varname>OPTIONS_DEFAULT</varname>:</para>		<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		<para><varname>OPTIONS</varname> definitions must appear
before the inclusion of		before the inclusion of
<filename>bsd.port.options.mk</filename>. The		<filename>bsd.port.options.mk</filename>.
<varname>PORT_OPTIONS</varname> variable can only be tested		<varname>PORT_OPTIONS</varname> can only be tested
		wblockUnsubmitted Not Done Inline Actions s/can/values can/ wblock: s/can/values can/
after the inclusion of		after the inclusion of
<filename>bsd.port.options.mk</filename>. Inclusion of		<filename>bsd.port.options.mk</filename>. Inclusion of
<filename>bsd.port.pre.mk</filename> can be used instead,		<filename>bsd.port.pre.mk</filename> can be used instead,
too, and is still widely used in ports written before the		too, and is still widely used in ports written before the
introduction of <filename>bsd.port.options.mk</filename>.		introduction of <filename>bsd.port.options.mk</filename>.
But be aware that some variables will not work as expected		But be aware that some variables will not work as expected
after the inclusion of <filename>bsd.port.pre.mk</filename>,		after the inclusion of <filename>bsd.port.pre.mk</filename>,
typically some <varname>USE_*</varname> flags.</para>		typically some <varname>USE_<replaceable>*</replaceable></varname> flags.</para>

<example xml:id="ports-options-simple-use">		<example xml:id="ports-options-simple-use">
<title>Simple Use of <varname>OPTIONS</varname></title>		<title>Simple Use of <varname>OPTIONS</varname></title>

<programlisting>OPTIONS_DEFINE= FOO BAR		<programlisting>OPTIONS_DEFINE= FOO BAR
FOO_DESC= Option foo support		FOO_DESC= Option foo support
BAR_DESC= Feature bar support		BAR_DESC= Feature bar support

Show All 9 Lines	.include <bsd.port.mk></programlisting>
<example xml:id="ports-options-check-unset">		<example xml:id="ports-options-check-unset">
<title>Check for Unset Port		<title>Check for Unset Port
<varname>OPTIONS</varname></title>		<varname>OPTIONS</varname></title>

<programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}		<programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES}
CONFIGURE_ARGS+=--without-examples		CONFIGURE_ARGS+=--without-examples
.endif</programlisting>		.endif</programlisting>

<para>Though, you should use the following so that the		<para>Though, this form is discourraged, using a configure
configure knob is really enabled and disabled when the		knob to really enable and disable the feature when the
option is.</para>		option is, is preferred:</para>

		wblockUnsubmitted Not Done Inline Actions "The form shown above is discouraged. The preferred method is using a configure knob to really enable and disable the feature to match the option:" (I suggest only showing the preferred way and not mentioning the other way.) wblock: "The form shown above is discouraged. The preferred method is using a configure knob to really…
		matAuthorUnsubmitted Not Done Inline Actions Well, with that example, yes, it would be better not to show the bad example, but, there sure are places where porters need to use this kind of tests, for some reason or another, and I'd rather have an example, of how to do it. mat: Well, with that example, yes, it would be better not to show the bad example, but, there sure…
<programlisting># Will add --with-examples / --without-examples		<programlisting># Will add --with-examples / --without-examples
EXAMPLES_CONFIGURE_WITH= examples</programlisting>		EXAMPLES_CONFIGURE_WITH= examples</programlisting>
</example>		</example>

<example xml:id="ports-options-practical-use">		<example xml:id="ports-options-practical-use">
<title>Practical Use of <varname>OPTIONS</varname></title>		<title>Practical Use of <varname>OPTIONS</varname></title>

<programlisting>OPTIONS_DEFINE= EXAMPLES		<programlisting>OPTIONS_DEFINE= EXAMPLES
Show All 27 Lines

.include <bsd.port.mk></programlisting>		.include <bsd.port.mk></programlisting>
</example>		</example>
</sect3>		</sect3>

<sect3 xml:id="makefile-options-default">		<sect3 xml:id="makefile-options-default">
<title>Default Options</title>		<title>Default Options</title>

<para>The following options are always on by default.</para>		<para>These options are always on by default.</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><literal>DOCS</literal> — build and install		<para><literal>DOCS</literal> — build and install
documentation.</para>		documentation.</para>
</listitem>		</listitem>

<listitem>		<listitem>
Show All 21 Lines	</note>
</sect3>		</sect3>
</sect2>		</sect2>

<sect2 xml:id="makefile-options-auto-activation">		<sect2 xml:id="makefile-options-auto-activation">
<title>Feature Auto-Activation</title>		<title>Feature Auto-Activation</title>

<para>When using a GNU configure script, keep an eye on which		<para>When using a GNU configure script, keep an eye on which
optional features are activated by auto-detection. Explicitly		optional features are activated by auto-detection. Explicitly
disable optional features you do not wish to be used by		disable optional features that are not needed by
passing respective <literal>--without-xxx</literal> or		adding <literal>--without-xxx</literal> or
<literal>--disable-xxx</literal> in		<literal>--disable-xxx</literal> in
<varname>CONFIGURE_ARGS</varname>.</para>		<varname>CONFIGURE_ARGS</varname>.</para>

<example xml:id="makefile-options-auto-activation-bad">		<example xml:id="makefile-options-auto-activation-bad">
<title>Wrong Handling of an Option</title>		<title>Wrong Handling of an Option</title>

<programlisting>.if ${PORT_OPTIONS:MFOO}		<programlisting>.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo		LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo
Show All 16 Lines	.endif</programlisting>

<programlisting>FOO_LIB_DEPENDS= libfoo.so:${PORTSDIR}/devel/foo		<programlisting>FOO_LIB_DEPENDS= libfoo.so:${PORTSDIR}/devel/foo
# Will add --enable-foo / --disable-foo		# Will add --enable-foo / --disable-foo
FOO_CONFIGURE_ENABLE= foo</programlisting>		FOO_CONFIGURE_ENABLE= foo</programlisting>
</example>		</example>

<note>		<note>
<para>Under some circumstances, the shorthand conditional		<para>Under some circumstances, the shorthand conditional
syntax can cause problems with complex constructs. If you		syntax can cause problems with complex constructs. The
receive errors such as		errors are usually
<literal>Malformed conditional</literal>, an alternative		<literal>Malformed conditional</literal>, an alternative
syntax can be used.</para>		syntax can be used.</para>

<programlisting>.if !empty(VARIABLE:MVALUE)		<programlisting>.if !empty(VARIABLE:MVALUE)
# as an alternative to		# as an alternative to
.if ${VARIABLE:MVALUE}</programlisting>		.if ${VARIABLE:MVALUE}</programlisting>
</note>		</note>
</sect2>		</sect2>
▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines	.endif</programlisting>
<title><varname><replaceable>OPT</replaceable>_USE</varname></title>		<title><varname><replaceable>OPT</replaceable>_USE</varname></title>

<para>For each		<para>For each
<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>		<literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
pair in		pair in
<varname><replaceable>OPT</replaceable>_USE</varname> the		<varname><replaceable>OPT</replaceable>_USE</varname> the
corresponding		corresponding
<varname>USE_<replaceable>KEY</replaceable></varname>		<varname>USE_<replaceable>KEY</replaceable></varname>
variable will be set to <replaceable>value</replaceable>.		will be set to <replaceable>value</replaceable>.
If <replaceable>value</replaceable> has spaces in it,		If <replaceable>value</replaceable> has spaces in it,
replace them with commas, they will be changed back to		replace them with commas, they will be changed back to
spaces during processing. For example:</para>		spaces during processing. For example:</para>

<programlisting>OPTIONS_DEFINE= OPT1		<programlisting>OPTIONS_DEFINE= OPT1
OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr</programlisting>		OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr</programlisting>

<para>is equivalent to:</para>		<para>is equivalent to:</para>
▲ Show 20 Lines • Show All 175 Lines • ▼ Show 20 Lines
.if ! ${PORT_OPTIONS:MOPT1}		.if ! ${PORT_OPTIONS:MOPT1}
CMAKE_ARGS+= -DTEST:BOOL=false		CMAKE_ARGS+= -DTEST:BOOL=false
.endif</programlisting>		.endif</programlisting>
</sect3>		</sect3>

<sect3 xml:id="options-dependencies">		<sect3 xml:id="options-dependencies">
<title>Dependencies</title>		<title>Dependencies</title>

<para>For any of the following dependency type:</para>		<para>For any of these dependency types:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><varname>PKG_DEPENDS</varname></para>		<para><varname>PKG_DEPENDS</varname></para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><varname>EXTRACT_DEPENDS</varname></para>		<para><varname>EXTRACT_DEPENDS</varname></para>
▲ Show 20 Lines • Show All 70 Lines • ▼ Show 20 Lines
LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a		LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a
.endif</programlisting>		.endif</programlisting>
</sect4>		</sect4>
</sect3>		</sect3>

<sect3 xml:id="options-variables">		<sect3 xml:id="options-variables">
<title>Generic Variables Replacement</title>		<title>Generic Variables Replacement</title>

<para>For any of the following variables:</para>		<para>For any of these variables:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><varname>ALL_TARGET</varname></para>		<para><varname>ALL_TARGET</varname></para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><varname>CATEGORIES</varname></para>		<para><varname>CATEGORIES</varname></para>
▲ Show 20 Lines • Show All 86 Lines • ▼ Show 20 Lines	.endif</programlisting>

<warning>		<warning>
<para>Some of these variables, at least		<para>Some of these variables, at least
<varname>ALL_TARGET</varname> and		<varname>ALL_TARGET</varname> and
<varname>INSTALL_TARGET</varname>, have their default		<varname>INSTALL_TARGET</varname>, have their default
values set <emphasis>after</emphasis> the options are		values set <emphasis>after</emphasis> the options are
processed.</para>		processed.</para>

<para>With the following lines in the		<para>With these lines in the
<filename>Makefile</filename>:</para>		<filename>Makefile</filename>:</para>

<programlisting>ALL_TARGET= all		<programlisting>ALL_TARGET= all

DOCS_ALL_TARGET= doc</programlisting>		DOCS_ALL_TARGET= doc</programlisting>

<para>If the <literal>DOCS</literal> option is enabled,		<para>If the <literal>DOCS</literal> option is enabled,
<varname>ALL_TARGET</varname> will have a final value of		<varname>ALL_TARGET</varname> will have a final value of
▲ Show 20 Lines • Show All 65 Lines • ▼ Show 20 Lines	.endif</programlisting>
</sect4>		</sect4>
</sect3>		</sect3>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="makefile-wrkdir">		<sect1 xml:id="makefile-wrkdir">
<title>Specifying the Working Directory</title>		<title>Specifying the Working Directory</title>

<para>Each port is extracted in to a working directory, which must		<para>Each port is extracted in to a working directory, which must
		wblockUnsubmitted Not Done Inline Actions s/in to/into/ wblock: s/in to/into/
be writable. The ports system defaults to having the		be writable. The ports system defaults to having
<varname>DISTFILES</varname> unpack in to a directory called		<varname>DISTFILES</varname> unpack in to a directory called
<literal>${DISTNAME}</literal>. In other words, if you have		<literal>${DISTNAME}</literal>. In other words, if the
set:</para>		<filename>Makefile</filename> has:</para>

<programlisting>PORTNAME= foo		<programlisting>PORTNAME= foo
PORTVERSION= 1.0</programlisting>		PORTVERSION= 1.0</programlisting>

<para>then the port's distribution files contain a top-level		<para>then the port's distribution files contain a top-level
directory, <filename>foo-1.0</filename>, and the rest of the		directory, <filename>foo-1.0</filename>, and the rest of the
files are located under that directory.</para>		files are located under that directory.</para>

<para>There are a number of variables you can override if that is		<para>A number of variables can overriden if that is
not the case.</para>		not the case.</para>

<sect2 xml:id="makefile-wrksrc">		<sect2 xml:id="makefile-wrksrc">
<title><varname>WRKSRC</varname></title>		<title><varname>WRKSRC</varname></title>

<para>The variable lists the name of the directory that is		<para>The variable lists the name of the directory that is
created when the application's distfiles are extracted. If		created when the application's distfiles are extracted. If
our previous example extracted into a directory called		our previous example extracted into a directory called
<filename>foo</filename> (and not		<filename>foo</filename> (and not
<filename>foo-1.0</filename>) you would write:</para>		<filename>foo-1.0</filename>) 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>		<programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
</sect2>		</sect2>

<sect2 xml:id="makefile-no_wrksubdir">		<sect2 xml:id="makefile-no_wrksubdir">
<title><varname>NO_WRKSUBDIR</varname></title>		<title><varname>NO_WRKSUBDIR</varname></title>

<para>If the port does not extract in to a subdirectory at all		<para>If the port does not extract in to a subdirectory at all
		wblockUnsubmitted Not Done Inline Actions s/all/all,/ wblock: s/all/all,/
then you should set <varname>NO_WRKSUBDIR</varname> to		then set <varname>NO_WRKSUBDIR</varname> to
indicate that.</para>		indicate that.</para>

<programlisting>NO_WRKSUBDIR= yes</programlisting>		<programlisting>NO_WRKSUBDIR= yes</programlisting>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="conflicts">		<sect1 xml:id="conflicts">
<title>Conflict Handling</title>		<title>Conflict Handling</title>

<para>There are three different variables to register a conflict		<para>There are three different variables to register a conflict
between packages and ports: <varname>CONFLICTS</varname>,		between packages and ports: <varname>CONFLICTS</varname>,
<varname>CONFLICTS_INSTALL</varname> and		<varname>CONFLICTS_INSTALL</varname> and
<varname>CONFLICTS_BUILD</varname>.</para>		<varname>CONFLICTS_BUILD</varname>.</para>

<note>		<note>
<para>The conflict variables automatically set the variable		<para>The conflict variables automatically set the variable
<varname>IGNORE</varname>, which is more fully documented in		<varname>IGNORE</varname>, which is more fully documented in
<xref linkend="dads-noinstall"/>.</para>		<xref linkend="dads-noinstall"/>.</para>
</note>		</note>

<para>When removing one of several conflicting ports, it is		<para>When removing one of several conflicting ports, it is
advisable to retain the <varname>CONFLICTS</varname> entries in		advisable to retain <varname>CONFLICTS</varname> in
those other ports for a few months to cater for users who only		those other ports for a few months to cater for users who only
update once in a while.</para>		update once in a while.</para>

<sect2 xml:id="conflicts-conflicts_install">		<sect2 xml:id="conflicts-conflicts_install">
<title><varname>CONFLICTS_INSTALL</varname></title>		<title><varname>CONFLICTS_INSTALL</varname></title>

<para>If your package cannot coexist with other packages		<para>If the package cannot coexist with other packages
(because of file conflicts, runtime incompatibilities, etc.),		(because of file conflicts, runtime incompatibilities, etc.),
list the other package names in the		list the other package names in
<varname>CONFLICTS_INSTALL</varname> variable. You can use		<varname>CONFLICTS_INSTALL</varname>. Use
shell globs like <literal>*</literal> and <literal>?</literal>		shell globs like <literal>*</literal> and <literal>?</literal>
here. Package names should be enumerated the same way they		here. Enumerate package names in there, not port names or
appear in <filename>/var/db/pkg</filename>. Please make sure		origins. Please make sure
that <varname>CONFLICTS_INSTALL</varname> does not match this		that <varname>CONFLICTS_INSTALL</varname> does not match this
port's package itself. Otherwise enforcing its installation		port's package itself. Otherwise enforcing its installation
with <varname>FORCE_PKG_REGISTER</varname> will no longer		with <varname>FORCE_PKG_REGISTER</varname> will no longer
work. The CONFLICTS_INSTALL check is done after the build		work. <varname>CONFLICTS_INSTALL</varname> check is done after the build
stage and prior to the install stage.</para>		stage and prior to the install stage.</para>
</sect2>		</sect2>

<sect2 xml:id="conflicts-conflicts_build">		<sect2 xml:id="conflicts-conflicts_build">
<title><varname>CONFLICTS_BUILD</varname></title>		<title><varname>CONFLICTS_BUILD</varname></title>

<para>If your port cannot be built if a certain port is already		<para>If the port cannot be built if a certain port is already
installed, list the other port names in the		installed, list the other port names in
<varname>CONFLICTS_BUILD</varname> variable. You can use		<varname>CONFLICTS_BUILD</varname>. use
		wblockUnsubmitted Not Done Inline Actions If the port cannot be built when other specific ports are already wblock: If the port cannot be built when other specific ports are already
		wblockUnsubmitted Not Done Inline Actions s/use/Use/ wblock: s/use/Use/
shell globs like <literal>*</literal> and <literal>?</literal>		shell globs like <literal>*</literal> and <literal>?</literal>
here. Package names should be enumerated the same way they		here. Enumerate package names in there, not port names or
appear in <filename>/var/db/pkg</filename>. The		origins.
CONFLICTS_BUILD check is done prior to the build stage. Build		<varname>CONFLICTS_BUILD</varname> check is done prior to the build stage. Build
		wblockUnsubmitted Not Done Inline Actions "Enumerate" is nice, but probably more difficult for translators than "Use package names, not port names or origins." Actually, that is not clear to me. Package names being a full filename? And above, it says "list the other port names". An example would help, along with consistent statements. wblock: "Enumerate" is nice, but probably more difficult for translators than "Use package names, not…
		matAuthorUnsubmitted Not Done Inline Actions No, not the full file name, the glob is for the package name, for instance, dns/bind99 has: CONFLICTS= bind9-9.[45678]. bind9-sdb-9.[45678]. bind-tools-9.* the package names are, say, for dns/bind98 : bind98-9.8.7P1_5. As for an example, it would be nice, yes, but I'll have to either find one that's easy to understand, or make a useful one up. mat: No, not the full file name, the glob is for the package name, for instance, dns/bind99 has…
conflicts are not recorded in the resulting package.</para>		conflicts are not recorded in the resulting package.</para>
</sect2>		</sect2>

<sect2 xml:id="conflicts-conflicts">		<sect2 xml:id="conflicts-conflicts">
<title><varname>CONFLICTS</varname></title>		<title><varname>CONFLICTS</varname></title>

<para>If your port cannot be built if a certain port is already		<para>If the port cannot be built if a certain port is already
installed and the resulting package cannot coexist with the		installed and the resulting package cannot coexist with the
other package, list the other package name in the		other package, list the other package name in
<varname>CONFLICTS</varname> variable. You can use shell		<varname>CONFLICTS</varname>. use shell
globs like <literal>*</literal> and <literal>?</literal> here.		globs like <literal>*</literal> and <literal>?</literal> here.
Packages names should be enumerated the same way they appear		Enumerate package names in there, not port names or
in <filename>/var/db/pkg</filename>. Please make sure that		origins. Please make sure that
<varname>CONFLICTS_INSTALL</varname> does not match this		<varname>CONFLICTS</varname> does not match this
port's package itself. Otherwise enforcing its installation		port's package itself. Otherwise enforcing its installation
with <varname>FORCE_PKG_REGISTER</varname> will no longer		with <varname>FORCE_PKG_REGISTER</varname> will no longer
work. The CONFLICTS check is done prior to the build stage		work. <varname>CONFLICTS</varname> check is done prior to the build stage
and prior to the install stage.</para>		and prior to the install stage.</para>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="install">		<sect1 xml:id="install">
<title>Installing Files</title>		<title>Installing Files</title>

<sect2 xml:id="install-macros">		<sect2 xml:id="install-macros">
<title><varname>INSTALL_*</varname> Macros</title>		<title><varname>INSTALL_<replaceable>*</replaceable></varname> Macros</title>

<para>Use the macros provided in		<para>Use the macros provided in
<filename>bsd.port.mk</filename> to ensure correct modes of		<filename>bsd.port.mk</filename> to ensure correct modes of
files in the port's <buildtarget>*-install</buildtarget>		files in the port's <buildtarget>*-install</buildtarget>
targets. Set ownership directly in		targets. Set ownership directly in
<filename>pkg-plist</filename> with the corresponding entries,		<filename>pkg-plist</filename> with the corresponding entries,
such as		such as
<literal>@owner <replaceable>owner</replaceable></literal> and		<literal>@owner <replaceable>owner</replaceable></literal> and
Show All 34 Lines	PORTVERSION= 1.0</programlisting>

<listitem>		<listitem>
<para><varname>INSTALL_MAN</varname> is a command to		<para><varname>INSTALL_MAN</varname> is a command to
install manpages and other documentation (it does not		install manpages and other documentation (it does not
compress anything).</para>		compress anything).</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>

<para>These are basically the <command>install</command>		<para>These are the <command>install</command>
command with all the appropriate flags.</para>		command with all the appropriate flags.</para>

<note>		<note>
<para>Do not use <varname>INSTALL_LIB</varname> to install		<para>Do not use <varname>INSTALL_LIB</varname> to install
static libraries, because stripping them render them		static libraries, because stripping them render them
useless. Use <varname>INSTALL_DATA</varname>		useless. Use <varname>INSTALL_DATA</varname>
instead.</para>		instead.</para>
</note>		</note>
</sect2>		</sect2>

<sect2 xml:id="install-strip">		<sect2 xml:id="install-strip">
<title>Stripping Binaries and Shared Libraries</title>		<title>Stripping Binaries and Shared Libraries</title>

<para>Do not strip binaries manually unless you have to. All		<para>Installed binaries have to be stripped. do not strip
binaries should be stripped, but the		binaries manually unless forced to.
		wblockUnsubmitted Not Done Inline Actions "Must" does not seem right. What if DEBUG is set? s/do/Do/, but that sentence is vague. How do I know when I need to strip binaries manually? wblock: "Must" does not seem right. What if DEBUG is set? s/do/Do/, but that sentence is vague. How…
		matAuthorUnsubmitted Not Done Inline Actions DEBUG replaces STRIP_CMD with true, I think, or something, that will just be ignored. Actually, I think I'm going to change that to should, it's more of a recommendation. mat: DEBUG replaces STRIP_CMD with true, I think, or something, that will just be ignored. Actually…
<varname>INSTALL_PROGRAM</varname> macro will install and		<varname>INSTALL_PROGRAM</varname> macro will install and
		wblockUnsubmitted Not Done Inline Actions s/^/^The/ wblock: s/^/^The/
strip a binary at the same time (see the next section). The		strip a binary at the same time (see the next section).
<varname>INSTALL_LIB</varname> macro does the same thing to		<varname>INSTALL_LIB</varname> macro does the same thing to
		wblockUnsubmitted Not Done Inline Actions s/^/^The/ wblock: s/^/^The/
shared libraries.</para>		shared libraries.</para>

<para>If you need to strip a file, but wish to use neither		<para>If a file has to be stripped, but wish to use neither
		wblockUnsubmitted Not Done Inline Actions "When a file must be stripped, but neither <varname>INSTALL_PROGRAM</varname> nor <varname>INSTALL_LIB</varname> macros are desirable, ..." (Why would that be?) wblock: "When a file must be stripped, but neither <varname>INSTALL_PROGRAM</varname> nor…
		matAuthorUnsubmitted Not Done Inline Actions Hum, I have no idea, I'm sure people have insane reason to do stuff. Also, it serves as an example for when upstream thought it was clever and used cp, or some other convoluted way to install files. A porter can just run STRIP_CMD some/file in post-install. mat: Hum, I have no idea, I'm sure people have insane reason to do stuff. Also, it serves as an…
<varname>INSTALL_PROGRAM</varname> nor		<varname>INSTALL_PROGRAM</varname> nor
<varname>INSTALL_LIB</varname> macros,		<varname>INSTALL_LIB</varname> macros,
<literal>${STRIP_CMD}</literal> will strip your program or		<literal>${STRIP_CMD}</literal> will strip the program or
shared library. This is typically done within the		shared library. This is typically done within the
<buildtarget>post-install</buildtarget> target. For		<buildtarget>post-install</buildtarget> target. For
example:</para>		example:</para>

<programlisting>post-install:		<programlisting>post-install:
${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting>		${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>
Show All 35 Lines	PORTVERSION= 1.0</programlisting>
for installing files under <filename>PREFIX/share</filename>		for installing files under <filename>PREFIX/share</filename>
target.</para>		target.</para>

<programlisting>post-install:		<programlisting>post-install:
${MKDIR} ${STAGEDIR}${EXAMPLESDIR}		${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
(cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})</programlisting>		(cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})</programlisting>

<para>This example will install the contents of		<para>This example will install the contents of
<filename>examples</filename> directory in the vendor distfile		<filename>examples</filename> directory in the vendor distfile
		wblockUnsubmitted Not Done Inline Actions s/^/^the / wblock: s/^/^the /
to the proper examples location of your port.</para>		to the proper examples location of the port.</para>

<programlisting>post-install:		<programlisting>post-install:
${MKDIR} ${STAGEDIR}${DATADIR}/summer		${MKDIR} ${STAGEDIR}${DATADIR}/summer
(cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting>		(cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting>

<para>And this example will install the data of summer months to		<para>And this example will install the data of summer months to
the <filename>summer</filename> subdirectory of a		the <filename>summer</filename> subdirectory of a
<filename>DATADIR</filename>.</para>		<filename>DATADIR</filename>.</para>

<para>Additional <command>find</command> arguments can be		<para>Additional <command>find</command> arguments can be
passed via the third argument to the		passed via the third argument to
<varname>COPYTREE_*</varname> macros. For example, to install		<varname>COPYTREE_<replaceable>*</replaceable></varname> macros. For example, to install
all files from the first example except Makefiles, one can use		all files from the first example except Makefiles, one can use
the following command.</para>		these commands.</para>

<programlisting>post-install:		<programlisting>post-install:
${MKDIR} ${STAGEDIR}${EXAMPLESDIR}		${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
(cd ${WRKSRC}/examples && \		(cd ${WRKSRC}/examples && \
${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting>		${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting>

<para>These macros do not add the installed files to		<para>These macros do not add the installed files to
<filename>pkg-plist</filename>. They must be added manually.		<filename>pkg-plist</filename>. They must be added manually.
For optional documentation (<varname>PORTDOCS</varname>, see		For optional documentation (<varname>PORTDOCS</varname>, see
<xref linkend="install-documentation"/>) and examples		<xref linkend="install-documentation"/>) and examples
(<varname>PORTEXAMPLES</varname>), the		(<varname>PORTEXAMPLES</varname>), the
<literal>%%PORTDOCS%%</literal> or		<literal>%%PORTDOCS%%</literal> or
<literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended		<literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended
in <filename>pkg-plist</filename>.</para>		in <filename>pkg-plist</filename>.</para>
</sect2>		</sect2>

<sect2 xml:id="install-documentation">		<sect2 xml:id="install-documentation">
<title>Install Additional Documentation</title>		<title>Install Additional Documentation</title>

<para>If your software has some documentation other than the		<para>If the software has some documentation other than the
standard man and info pages that you think is useful for the		standard man and info pages that is useful for the
user, install it under <filename>PREFIX/share/doc</filename>.		user, install it under <varname>DOCSDIR</varname>
This can be done, like the previous item, in the		This can be done, like the previous item, in the
<buildtarget>post-install</buildtarget> target.</para>		<buildtarget>post-install</buildtarget> target.</para>

<para>Create a new directory for your port. The directory name		<para>Create a new directory for the port. The directory name
should reflect what the port is. This usually means		is <varname>DOCSDIR</varname>. This usually equals
<varname>PORTNAME</varname>. However, if you think the user		<varname>PORTNAME</varname>. However, if the user
might want different versions of the port to be installed at		might want different versions of the port to be installed at
the same time, you can use the whole		the same time, the whole
<varname>PKGNAME</varname>.</para>		<varname>PKGNAME</varname> can be used.</para>

<para>Since only the files listed in		<para>Since only the files listed in
<filename>pkg-plist</filename> are installed, it is safe to		<filename>pkg-plist</filename> are installed, it is safe to
always install documentation to <varname>STAGEDIR</varname>		always install documentation to <varname>STAGEDIR</varname>
(see <xref linkend="staging"/>). Hence <literal>.if</literal>		(see <xref linkend="staging"/>). Hence <literal>.if</literal>
blocks are only needed when the installed files are large		blocks are only needed when the installed files are large
enough to cause significant I/O overhead.</para>		enough to cause significant I/O overhead.</para>

▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Lines	PORTVERSION= 1.0</programlisting>
as pathnames relative to <filename>PREFIX</filename> if		as pathnames relative to <filename>PREFIX</filename> if
possible. That is, <filename>share/doc/PORTNAME</filename>		possible. That is, <filename>share/doc/PORTNAME</filename>
will be substituted for <literal>%%DOCSDIR%%</literal> in the		will be substituted for <literal>%%DOCSDIR%%</literal> in the
packing list by default, and so on. (See more on		packing list by default, and so on. (See more on
<filename>pkg-plist</filename> substitution		<filename>pkg-plist</filename> substitution
<link linkend="plist-sub">here</link>.)</para>		<link linkend="plist-sub">here</link>.)</para>

<para>All conditionally installed documentation files and		<para>All conditionally installed documentation files and
directories should be included in		directories are included in
<filename>pkg-plist</filename> with the		<filename>pkg-plist</filename> with the
<literal>%%PORTDOCS%%</literal> prefix, for example:</para>		<literal>%%PORTDOCS%%</literal> prefix, for example:</para>

<programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS		<programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
%%PORTDOCS%%%%DOCSDIR%%/CONTACT		%%PORTDOCS%%%%DOCSDIR%%/CONTACT
%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>		%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>

<para>As an alternative to enumerating the documentation files		<para>As an alternative to enumerating the documentation files
in <filename>pkg-plist</filename>, a port can set the variable		in <filename>pkg-plist</filename>, a port can set the variable
<varname>PORTDOCS</varname> to a list of file names and shell		<varname>PORTDOCS</varname> to a list of file names and shell
glob patterns to add to the final packing list. The names		glob patterns to add to the final packing list. The names
will be relative to <varname>DOCSDIR</varname>. Therefore, a		will be relative to <varname>DOCSDIR</varname>. Therefore, a
port that utilizes <varname>PORTDOCS</varname> and uses a		port that utilizes <varname>PORTDOCS</varname> and uses a
		wblockUnsubmitted Not Done Inline Actions port that utilizes <varname>PORTDOCS</varname>, and uses a wblock: port that utilizes <varname>PORTDOCS</varname>, and uses a
non-default location for its documentation should set		non-default location for its documentation must set
		wblockUnsubmitted Not Done Inline Actions non-default location for its documentation, must set wblock: non-default location for its documentation, must set
<varname>DOCSDIR</varname> accordingly. If a directory is		<varname>DOCSDIR</varname> accordingly. If a directory is
listed in <varname>PORTDOCS</varname> or matched by a glob		listed in <varname>PORTDOCS</varname> or matched by a glob
pattern from this variable, the entire subtree of contained		pattern from this variable, the entire subtree of contained
files and directories will be registered in the final packing		files and directories will be registered in the final packing
list. If the <literal>DOCS</literal> option has been unset		list. If the <literal>DOCS</literal> option has been unset
then files and directories listed in		then files and directories listed in
<varname>PORTDOCS</varname> would not be installed or added to		<varname>PORTDOCS</varname> would not be installed or added to
port packing list. Installing the documentation at		port packing list. Installing the documentation at
Show All 23 Lines	<sect2 xml:id="install-subdirs">
<title>Subdirectories Under <varname>PREFIX</varname></title>		<title>Subdirectories Under <varname>PREFIX</varname></title>

<para>Try to let the port put things in the right subdirectories		<para>Try to let the port put things in the right subdirectories
of <varname>PREFIX</varname>. Some ports lump everything and		of <varname>PREFIX</varname>. Some ports lump everything and
put it in the subdirectory with the port's name, which is		put it in the subdirectory with the port's name, which is
incorrect. Also, many ports put everything except binaries,		incorrect. Also, many ports put everything except binaries,
header files and manual pages in a subdirectory of		header files and manual pages in a subdirectory of
<filename>lib</filename>, which does not work well with the		<filename>lib</filename>, which does not work well with the
BSD paradigm. Many of the files should be moved to one of the		BSD paradigm. Many of the files must be moved to one of these
following: <filename>etc</filename> (setup/configuration		directories: <filename>etc</filename> (setup/configuration
files), <filename>libexec</filename> (executables started		files), <filename>libexec</filename> (executables started
internally), <filename>sbin</filename> (executables for		internally), <filename>sbin</filename> (executables for
superusers/managers), <filename>info</filename> (documentation		superusers/managers), <filename>info</filename> (documentation
for info browser) or <filename>share</filename> (architecture		for info browser) or <filename>share</filename> (architecture
independent files). See &man.hier.7; for details; the rules		independent files). See &man.hier.7; for details; the rules
governing <filename>/usr</filename> pretty much apply to		governing <filename>/usr</filename> pretty much apply to
<filename>/usr/local</filename> too. The exception are ports		<filename>/usr/local</filename> too. The exception are ports
dealing with USENET <quote>news</quote>. They may use		dealing with USENET <quote>news</quote>. They may use
<filename>PREFIX/news</filename> as a destination for their		<filename>PREFIX/news</filename> as a destination for their
files.</para>		files.</para>
</sect2>		</sect2>
</sect1>		</sect1>
</chapter>		</chapter>