svn commit: r43958 - head/en_US.ISO8859-1/books/porters-handbook/makefiles
Warren Block
wblock at FreeBSD.org
Sun Feb 16 04:57:46 UTC 2014
Author: wblock
Date: Sun Feb 16 04:57:45 2014
New Revision: 43958
URL: http://svnweb.freebsd.org/changeset/doc/43958
Log:
Whitespace-only fixes, translators please ignore.
Modified:
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Sun Feb 16 03:32:26 2014 (r43957)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Sun Feb 16 04:57:45 2014 (r43958)
@@ -4,2114 +4,2087 @@
$FreeBSD$
-->
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="makefiles">
+
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the <filename>Makefile</filename> is pretty
+ simple, and again we suggest that you look at existing examples
+ before starting. Also, there is a
+ <link linkend="porting-samplem">sample Makefile</link> in this
+ handbook, so take a look and please follow the ordering of
+ variables and sections in that template to make your port easier
+ for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new <filename>Makefile</filename>:</para>
+
+ <sect1 xml:id="makefile-source">
+ <title>The Original Source</title>
+
+ <para>Does it live in <varname>DISTDIR</varname> as a standard
+ <command>gzip</command>ped tarball named something like
+ <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
+ to the next step. If not, you should look at overriding any of
+ the <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
+ <varname>EXTRACT_CMD</varname>,
+ <varname>EXTRACT_BEFORE_ARGS</varname>,
+ <varname>EXTRACT_AFTER_ARGS</varname>,
+ <varname>EXTRACT_SUFX</varname>, or <varname>DISTFILES</varname>
+ variables, depending on how alien a format your port's
+ distribution file is.</para>
+
+ <para>In the worst case, you can simply create your own
+ <buildtarget>do-extract</buildtarget> target to override the
+ default, though this should be rarely, if ever,
+ necessary.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-naming">
+ <title>Naming</title>
+
+ <para>The first part of the port's <filename>Makefile</filename>
+ names the port, describes its version number, and lists it in
+ the correct category.</para>
+
+ <sect2>
+ <title><varname>PORTNAME</varname> and
+ <varname>PORTVERSION</varname></title>
+
+ <para>You should set <varname>PORTNAME</varname> to the base
+ name of your port, and <varname>PORTVERSION</varname> to the
+ version number of the port.</para>
+ </sect2>
+
+ <sect2 xml:id="makefile-naming-revepoch">
+ <title><varname>PORTREVISION</varname> and
+ <varname>PORTEPOCH</varname></title>
+
+ <sect3>
+ <title><varname>PORTREVISION</varname></title>
+
+ <para>The <varname>PORTREVISION</varname> variable is a
+ monotonically increasing value which is reset to 0 with
+ every increase of <varname>PORTVERSION</varname> (i.e.,
+ every time a new official vendor release is made), and
+ appended to the package name if non-zero. Changes to
+ <varname>PORTREVISION</varname> are used by automated tools
+ (e.g., <command>pkg version</command>, see
+ &man.pkg-version.8;) to highlight the fact that a new
+ package is available.</para>
+
+ <para><varname>PORTREVISION</varname> should be increased each
+ time a change is made to the port that changes the generated
+ package in any way. That includes changes that only affect
+ a package built with non-default
+ <link linkend="makefile-options">options</link>.</para>
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="makefiles">
- <title>Configuring the Makefile</title>
+ <para>Examples of when <varname>PORTREVISION</varname>
+ should be bumped:</para>
- <para>Configuring the <filename>Makefile</filename> is pretty
- simple, and again we suggest that you look at existing examples
- before starting. Also, there is a
- <link linkend="porting-samplem">sample Makefile</link> in this
- handbook, so take a look and please follow the ordering of
- variables and sections in that template to make your port easier
- for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your new <filename>Makefile</filename>:</para>
-
- <sect1 xml:id="makefile-source">
- <title>The Original Source</title>
-
- <para>Does it live in <varname>DISTDIR</varname> as a standard
- <command>gzip</command>ped tarball named something like
- <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
- to the next step. If not, you should look at overriding any
- of the <varname>DISTVERSION</varname>,
- <varname>DISTNAME</varname>, <varname>EXTRACT_CMD</varname>,
- <varname>EXTRACT_BEFORE_ARGS</varname>,
- <varname>EXTRACT_AFTER_ARGS</varname>,
- <varname>EXTRACT_SUFX</varname>, or
- <varname>DISTFILES</varname> variables, depending on how alien
- a format your port's distribution file is.</para>
-
- <para>In the worst case, you can simply create your own
- <buildtarget>do-extract</buildtarget> target to override the
- default, though this should be rarely, if ever,
- necessary.</para>
- </sect1>
-
- <sect1 xml:id="makefile-naming">
- <title>Naming</title>
-
- <para>The first part of the port's <filename>Makefile</filename>
- names the port, describes its version number, and lists it
- in the correct category.</para>
-
- <sect2>
- <title><varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname></title>
-
- <para>You should set <varname>PORTNAME</varname> to the
- base name of your port, and <varname>PORTVERSION</varname>
- to the version number of the port.</para>
- </sect2>
-
- <sect2 xml:id="makefile-naming-revepoch">
- <title><varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname></title>
-
- <sect3>
- <title><varname>PORTREVISION</varname></title>
-
- <para>The <varname>PORTREVISION</varname> variable is a
- monotonically increasing value which is reset to 0 with
- every increase of <varname>PORTVERSION</varname> (i.e.,
- every time a new official vendor release is made), and
- appended to the package name if non-zero. Changes to
- <varname>PORTREVISION</varname> are used by automated
- tools (e.g., <command>pkg version</command>, see
- &man.pkg-version.8;) to highlight the fact that a new
- package is available.</para>
-
- <para><varname>PORTREVISION</varname> should be increased
- each time a change is made to the port that changes the
- generated package in any way. That includes changes that
- only affect a package built with non-default <link
- linkend="makefile-options">options</link>.</para>
-
- <para>Examples of when <varname>PORTREVISION</varname>
- should be bumped:</para>
-
- <itemizedlist>
- <listitem>
- <para>Addition of patches to correct security
- vulnerabilities, bugs, or to add new functionality to
- the port.</para>
- </listitem>
-
- <listitem>
- <para>Changes to the port <filename>Makefile</filename>
- to enable or disable compile-time options in the
- package.</para>
- </listitem>
-
- <listitem>
- <para>Changes in the packing list or the install-time
- behavior of the package (e.g., change to a script
- which generates initial data for the package, like ssh
- host keys).</para>
- </listitem>
-
- <listitem>
- <para>Version bump of a port's shared library dependency
- (in this case, someone trying to install the old
- package after installing a newer version of the
- dependency will fail since it will look for the old
- libfoo.x instead of libfoo.(x+1)).</para>
- </listitem>
-
- <listitem>
- <para>Silent changes to the port distfile which have
- significant functional differences, i.e., changes to
- the distfile requiring a correction to
- <filename>distinfo</filename> with no corresponding
- change to <varname>PORTVERSION</varname>, where a
- <command>diff -ru</command> of the old and new
- versions shows non-trivial changes to the code.</para>
- </listitem>
- </itemizedlist>
-
- <para>Examples of changes which do not require a
- <varname>PORTREVISION</varname> bump:</para>
-
- <itemizedlist>
- <listitem>
- <para>Style changes to the port skeleton with no
- functional change to what appears in the resulting
- package.</para>
- </listitem>
-
- <listitem>
- <para>Changes to <varname>MASTER_SITES</varname> or
- other functional changes to the port which do not
- affect the resulting package.</para>
- </listitem>
-
- <listitem>
- <para>Trivial patches to the distfile such as correction
- of typos, which are not important enough that users of
- the package should go to the trouble of
- upgrading.</para>
- </listitem>
-
- <listitem>
- <para>Build fixes which cause a package to become
- compilable where it was previously failing (as long as
- the changes do not introduce any functional change on
- any other platforms on which the port did previously
- build). Since <varname>PORTREVISION</varname>
- reflects the content of the package, if the package
- was not previously buildable then there is no need to
- increase <varname>PORTREVISION</varname> to mark a
- change.</para>
- </listitem>
- </itemizedlist>
-
- <para>A rule of thumb is to ask yourself whether a change
- committed to a port is something which everyone would
- benefit from having (either because of an enhancement,
- fix, or by virtue that the new package will actually work
- at all), and weigh that against that fact that it will
- cause everyone who regularly updates their ports tree to
- be compelled to update. If yes, the
- <varname>PORTREVISION</varname> should be bumped.</para>
- </sect3>
-
- <sect3>
- <title><varname>PORTEPOCH</varname></title>
-
- <para>From time to time a software vendor or &os; porter
- will do something silly and release a version of their
- software which is actually numerically less than the
- previous version. An example of this is a port which goes
- from foo-20000801 to foo-1.0 (the former will be
- incorrectly treated as a newer version since 20000801 is a
- numerically greater value than 1).</para>
-
- <tip>
- <para>The results of version number comparisons are not
- always obvious. <command>pkg version</command> (see
- &man.pkg-version.8;) can be used to test the comparison
- of two version number strings. For example:</para>
-
- <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput>
-></screen>
-
- <para>The <literal>></literal> output indicates that
- version 0.031 is considered greater than version 0.29,
- which may not have been obvious to the porter.</para>
- </tip>
-
- <para>In situations such as this, the
- <varname>PORTEPOCH</varname> version should be increased.
- If <varname>PORTEPOCH</varname> is nonzero it is appended
- to the package name as described in section 0 above.
- <varname>PORTEPOCH</varname> must never be decreased or
- reset to zero, because that would cause comparison to a
- package from an earlier epoch to fail (i.e., the package
- would not be detected as out of date): the new version
- number (e.g., <literal>1.0,1</literal> in the above
- example) is still numerically less than the previous
- version (20000801), but the <literal>,1</literal> suffix
- is treated specially by automated tools and found to be
- greater than the implied suffix <literal>,0</literal> on
- the earlier package.</para>
-
- <para>Dropping or resetting <varname>PORTEPOCH</varname>
- incorrectly leads to no end of grief; if you do not
- understand the above discussion, please keep after it
- until you do, or ask questions on the mailing
- lists.</para>
-
- <para>It is expected that <varname>PORTEPOCH</varname> will
- not be used for the majority of ports, and that sensible
- use of <varname>PORTVERSION</varname> can often preempt it
- becoming necessary if a future release of the software
- should change the version structure. However, care is
- needed by &os; porters when a vendor release is made
- without an official version number — such as a code
- <quote>snapshot</quote> release. The temptation is to
- label the release with the release date, which will cause
- problems as in the example above when a new
- <quote>official</quote> release is made.</para>
-
- <para>For example, if a snapshot release is made on the date
- 20000917, and the previous version of the software was
- version 1.2, the snapshot release should be given a
- <varname>PORTVERSION</varname> of 1.2.20000917 or similar,
- not 20000917, so that the succeeding release, say 1.3, is
- still a numerically greater value.</para>
- </sect3>
-
- <sect3>
- <title>Example of <varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname> Usage</title>
-
- <para>The <literal>gtkmumble</literal> port, version
- <literal>0.10</literal>, is committed to the ports
- collection:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10</literal>.</para>
-
- <para>A security hole is discovered which requires a local
- &os; patch. <varname>PORTREVISION</varname> is bumped
- accordingly.</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10
-PORTREVISION= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10_1</literal></para>
-
- <para>A new version is released by the vendor, numbered
- <literal>0.2</literal> (it turns out the author actually
- intended <literal>0.10</literal> to actually mean
- <literal>0.1.0</literal>, not
- <quote>what comes after 0.9</quote> - oops, too late now).
- Since the new minor version <literal>2</literal> is
- numerically less than the previous version
- <literal>10</literal>, the <varname>PORTEPOCH</varname>
- must be bumped to manually force the new package to be
- detected as <quote>newer</quote>. Since it is a new
- vendor release of the code,
- <varname>PORTREVISION</varname> is reset to 0 (or removed
- from the <filename>Makefile</filename>).</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.2
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.2,1</literal></para>
-
- <para>The next release is 0.3. Since
- <varname>PORTEPOCH</varname> never decreases, the version
- variables are now:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.3
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.3,1</literal></para>
-
- <note>
- <para>If <varname>PORTEPOCH</varname> were reset to
- <literal>0</literal> with this upgrade, someone who had
- installed the <literal>gtkmumble-0.10_1</literal>
- package would not detect the
- <literal>gtkmumble-0.3</literal> package as newer, since
- <literal>3</literal> is still numerically less than
- <literal>10</literal>. Remember, this is the whole
- point of <varname>PORTEPOCH</varname> in the first
- place.</para>
- </note>
- </sect3>
- </sect2>
-
- <sect2>
- <title><varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname></title>
-
- <para>Two optional variables, <varname>PKGNAMEPREFIX</varname>
- and <varname>PKGNAMESUFFIX</varname>, are combined with
- <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> to form
- <varname>PKGNAME</varname> as
- <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
- Make sure this conforms to our
- <link linkend="porting-pkgname">guidelines for a good
- package name</link>. In particular, you are
- <emphasis>not</emphasis> allowed to use a hyphen
- (<literal>-</literal>) in <varname>PORTVERSION</varname>.
- Also, if the package name has the
- <replaceable>language-</replaceable> or the
- <replaceable>-compiled.specifics</replaceable> part (see
- below), use <varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname>, respectively. Do not make
- them part of <varname>PORTNAME</varname>.</para>
- </sect2>
-
- <sect2 xml:id="porting-pkgname">
- <title>Package Naming Conventions</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already thousands of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like
- <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para>
-
- <para>The package name is defined as
- <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
- Make sure to set the variables to conform to that
- format.</para>
-
- <orderedlist>
+ <itemizedlist>
<listitem>
- <para>&os; strives to support the native language of
- its users. The <replaceable>language-</replaceable>
- part should be a two letter abbreviation of the natural
- language defined by ISO-639 if the port is specific to a
- certain language. Examples are <literal>ja</literal>
- for Japanese, <literal>ru</literal> for Russian,
- <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal>
- for Korean and <literal>de</literal> for German.</para>
-
- <para>If the port is specific to a certain region within
- the language area, add the two letter country code as
- well. Examples are <literal>en_US</literal> for US
- English and <literal>fr_CH</literal> for Swiss
- French.</para>
-
- <para>The <replaceable>language-</replaceable> part should
- be set in the <varname>PKGNAMEPREFIX</varname>
- variable.</para>
+ <para>Addition of patches to correct security
+ vulnerabilities, bugs, or to add new functionality to
+ the port.</para>
</listitem>
<listitem>
- <para>The first letter of the <filename>name</filename>
- part should be lowercase. (The rest of the name may
- contain capital letters, so use your own discretion when
- you are converting a software name that has some capital
- letters in it.) There is a tradition of naming
- <literal>Perl 5</literal> modules by prepending
- <literal>p5-</literal> and converting the double-colon
- separator to a hyphen; for example, the
- <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>.</para>
+ <para>Changes to the port <filename>Makefile</filename> to
+ enable or disable compile-time options in the
+ package.</para>
</listitem>
<listitem>
- <para>Make sure that the port's name and version are
- clearly separated and placed into the
- <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> variables. The only
- reason for <varname>PORTNAME</varname> to contain a
- version part is if the upstream distribution is really
- named that way, as in the
- <filename>textproc/libxml2</filename> or
- <filename>japanese/kinput2-freewnn</filename> ports.
- Otherwise, the <varname>PORTNAME</varname> should not
- contain any version-specific information. It is quite
- normal for several ports to have the same
- <varname>PORTNAME</varname>, as the
- <filename>www/apache*</filename> ports do; in that case,
- different versions (and different index entries) are
- distinguished by the <varname>PKGNAMEPREFIX</varname>
- and <varname>PKGNAMESUFFIX</varname> values.</para>
+ <para>Changes in the packing list or the install-time
+ behavior of the package (e.g., change to a script which
+ generates initial data for the package, like ssh host
+ keys).</para>
</listitem>
<listitem>
- <para>If the port can be built with different
- <link linkend="makefile-masterdir">hardcoded
- defaults</link> (usually part of the directory name in
- a family of ports), the
- <replaceable>-compiled.specifics</replaceable> part
- should state the compiled-in defaults (the hyphen is
- optional). Examples are paper size and font
- units.</para>
-
- <para>The <replaceable>-compiled.specifics</replaceable>
- part should be set in the
- <varname>PKGNAMESUFFIX</varname> variable.</para>
+ <para>Version bump of a port's shared library dependency
+ (in this case, someone trying to install the old package
+ after installing a newer version of the dependency will
+ fail since it will look for the old libfoo.x instead of
+ libfoo.(x+1)).</para>
</listitem>
<listitem>
- <para>The version string should follow a dash
- (<literal>-</literal>) and be a period-separated list of
- integers and single lowercase alphabetics. In
- particular, it is not permissible to have another dash
- inside the version string. The only exception is the
- string <literal>pl</literal> (meaning
- <quote>patchlevel</quote>), which can be used
- <emphasis>only</emphasis> when there are no major and
- minor version numbers in the software. If the software
- version has strings like <quote>alpha</quote>,
- <quote>beta</quote>, <quote>rc</quote>, or
- <quote>pre</quote>, take the first letter and put it
- immediately after a period. If the version string
- continues after those names, the numbers should follow
- the single alphabet without an extra period between
- them.</para>
-
- <para>The idea is to make it easier to sort ports by
- looking at the version string. In particular, make sure
- version number components are always delimited by a
- period, and if the date is part of the string, use the
- <literal>0.0.yyyy.mm.dd</literal>
- format, not
- <literal>dd.mm.yyyy</literal>
- or the non-Y2K compliant
- <literal>yy.mm.dd</literal>
- format. It is important to prefix the version with
- <literal>0.0.</literal> in case a release with an actual
- version number is made, which would of course be
- numerically less than
- <literal>yyyy</literal>.</para>
+ <para>Silent changes to the port distfile which have
+ significant functional differences, i.e., changes to the
+ distfile requiring a correction to
+ <filename>distinfo</filename> with no corresponding
+ change to <varname>PORTVERSION</varname>, where a
+ <command>diff -ru</command> of the old and new versions
+ shows non-trivial changes to the code.</para>
</listitem>
- </orderedlist>
-
- <para>Here are some (real) examples on how to convert the name
- as called by the software authors to a suitable package
- name:</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="6">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry><varname>PKGNAMEPREFIX</varname></entry>
- <entry><varname>PORTNAME</varname></entry>
- <entry><varname>PKGNAMESUFFIX</varname></entry>
- <entry><varname>PORTVERSION</varname></entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2</entry>
- <entry>(empty)</entry>
- <entry>mule</entry>
- <entry>(empty)</entry>
- <entry>2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>(empty)</entry>
- <entry>emiclock</entry>
- <entry>(empty)</entry>
- <entry>1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>(empty)</entry>
- <entry>rdist</entry>
- <entry>(empty)</entry>
- <entry>1.3.a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>(empty)</entry>
- <entry>es</entry>
- <entry>(empty)</entry>
- <entry>0.9.b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>mailman-2.0rc3</entry>
- <entry>(empty)</entry>
- <entry>mailman</entry>
- <entry>(empty)</entry>
- <entry>2.0.r3</entry>
- <entry>No strings like <literal>rc</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>(empty)</entry>
- <entry>tiff</entry>
- <entry>(empty)</entry>
- <entry>3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>(empty)</entry>
- <entry>tvtwm</entry>
- <entry>(empty)</entry>
- <entry>pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>(empty)</entry>
- <entry>piewm</entry>
- <entry>(empty)</entry>
- <entry>1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>(empty)</entry>
- <entry>xvgr</entry>
- <entry>(empty)</entry>
- <entry>2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-</entry>
- <entry>gawk</entry>
- <entry>(empty)</entry>
- <entry>2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>(empty)</entry>
- <entry>psutils</entry>
- <entry>-letter</entry>
- <entry>1.13</entry>
- <entry>Paper size hardcoded at package build
- time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>(empty)</entry>
- <entry>pkfonts</entry>
- <entry>300</entry>
- <entry>1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>If there is absolutely no trace of version information
- in the original source and it is unlikely that the original
- author will ever release another version, just set the
- version string to <literal>1.0</literal> (like the
- <literal>piewm</literal> example above). Otherwise, ask the
- original author or use the date string
- (<literal>0.0.yyyy.mm.dd</literal>)
- as the version.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="makefile-categories">
- <title>Categorization</title>
-
- <sect2>
- <title><varname>CATEGORIES</varname></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of
- these subdirectories are specified by the variable
- <varname>CATEGORIES</varname>. It is intended to make life
- easier for the user when he is wading through the pile of
- packages on the FTP site or the CDROM. Please take a look
- at the <link linkend="porting-categories">current list of
- categories</link> and pick the ones that are suitable for
- your port.</para>
-
- <para>This list also determines where in the ports tree the
- port is imported. If you put more than one category here,
- it is assumed that the port files will be put in the
- subdirectory with the name in the first category. See
- <link linkend="choosing-categories">below</link> for more
- discussion about how to pick the right categories.</para>
- </sect2>
-
- <sect2 xml:id="porting-categories">
- <title>Current List of Categories</title>
-
- <para>Here is the current list of port categories. Those
- marked with an asterisk (<literal>*</literal>) are
- <emphasis>virtual</emphasis> categories—those that do
- not have a corresponding subdirectory in the ports tree.
- They are only used as secondary categories, and only for
- search purposes.</para>
-
- <note>
- <para>For non-virtual categories, you will find a one-line
- description in the <varname>COMMENT</varname> in that
- subdirectory's <filename>Makefile</filename>.</para>
- </note>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Category</entry>
- <entry>Description</entry>
- <entry>Notes</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><filename>accessibility</filename></entry>
- <entry>Ports to help disabled users.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>afterstep*</filename></entry>
-
- <entry>Ports to support the <link
- xlink:href="http://www.afterstep.org">AfterStep</link>
- window manager.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>arabic</filename></entry>
- <entry>Arabic language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>archivers</filename></entry>
- <entry>Archiving tools.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>astro</filename></entry>
- <entry>Astronomical ports.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>audio</filename></entry>
- <entry>Sound support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>benchmarks</filename></entry>
- <entry>Benchmarking utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>biology</filename></entry>
- <entry>Biology-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>cad</filename></entry>
- <entry>Computer aided design tools.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>chinese</filename></entry>
- <entry>Chinese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>comms</filename></entry>
- <entry>Communication software.</entry>
- <entry>Mostly software to talk to your serial
- port.</entry>
- </row>
-
- <row>
- <entry><filename>converters</filename></entry>
- <entry>Character code converters.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>databases</filename></entry>
- <entry>Databases.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>deskutils</filename></entry>
- <entry>Things that used to be on the desktop before
- computers were invented.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>devel</filename></entry>
- <entry>Development utilities.</entry>
- <entry>Do not put libraries here just because they are
- libraries—unless they truly do not belong
- anywhere else, they should not be in this
- category.</entry>
- </row>
-
- <row>
- <entry><filename>dns</filename></entry>
- <entry>DNS-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>docs*</filename></entry>
- <entry>Meta-ports for &os; documentation.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>editors</filename></entry>
- <entry>General editors.</entry>
- <entry>Specialized editors go in the section for those
- tools (e.g., a mathematical-formula editor will go
- in <filename>math</filename>).</entry>
- </row>
-
- <row>
- <entry><filename>elisp*</filename></entry>
- <entry>Emacs-lisp ports.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>emulators</filename></entry>
- <entry>Emulators for other operating systems.</entry>
- <entry>Terminal emulators do <emphasis>not</emphasis>
- belong here—X-based ones should go to
- <filename>x11</filename> and text-based ones to
- either <filename>comms</filename> or
- <filename>misc</filename>, depending on the exact
- functionality.</entry>
- </row>
-
- <row>
- <entry><filename>finance</filename></entry>
- <entry>Monetary, financial and related
- applications.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>french</filename></entry>
- <entry>French language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ftp</filename></entry>
- <entry>FTP client and server utilities.</entry>
- <entry>If your port speaks both FTP and HTTP, put it
- in <filename>ftp</filename> with a secondary
- category of <filename>www</filename>.</entry>
- </row>
-
- <row>
- <entry><filename>games</filename></entry>
- <entry>Games.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>geography*</filename></entry>
- <entry>Geography-related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>german</filename></entry>
- <entry>German language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>gnome*</filename></entry>
- <entry>Ports from the
- <link xlink:href="http://www.gnome.org">GNOME</link>
- Project.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>gnustep*</filename></entry>
- <entry>Software related to the GNUstep desktop
- environment.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>graphics</filename></entry>
- <entry>Graphics utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hamradio*</filename></entry>
- <entry>Software for amateur radio.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>haskell*</filename></entry>
- <entry>Software related to the Haskell
- language.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hebrew</filename></entry>
- <entry>Hebrew language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>hungarian</filename></entry>
- <entry>Hungarian language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>ipv6*</filename></entry>
- <entry>IPv6 related software.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>irc</filename></entry>
- <entry>Internet Relay Chat utilities.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>japanese</filename></entry>
- <entry>Japanese language support.</entry>
- <entry/>
- </row>
-
- <row>
- <entry><filename>java</filename></entry>
- <entry>Software related to the Java™
- language.</entry>
- <entry>The <filename>java</filename> category must
- not be the only one for a port. Save for ports
- directly related to the Java language, porters are
- also encouraged not to use <filename>java</filename>
- as the main category of a port.</entry>
- </row>
-
- <row>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-head
mailing list