svn commit: r50628 - in head/en_US.ISO8859-1/books/porters-handbook: makefiles order
Mathieu Arnold
mat at FreeBSD.org
Fri Aug 4 10:23:59 UTC 2017
Author: mat
Date: Fri Aug 4 10:23:58 2017
New Revision: 50628
URL: https://svnweb.freebsd.org/changeset/doc/50628
Log:
Rewrite the Makefile chapter a bit to promote DISTVERSION.
Reviewed by: bcr
Sponsored by: Absolight, The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D11822
Modified:
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml (contents, props changed)
Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Aug 4 10:23:55 2017 (r50627)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Aug 4 10:23:58 2017 (r50628)
@@ -49,26 +49,277 @@
the correct category.</para>
<sect2 xml:id="makefile-portname">
- <title><varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname></title>
+ <title><varname>PORTNAME</varname></title>
- <para>Set <varname>PORTNAME</varname> to the base
- name of the port. Set <varname>PORTVERSION</varname> to the
- version number of the port unless
- <varname>DISTVERSION</varname> is used (see
- <xref linkend="makefile-distversion"/>).</para>
+ <para>Set <varname>PORTNAME</varname> to the base name of the
+ software. It is used as the base for the &os; package, and
+ for <link
+ linkend="makefile-distname"><varname>DISTNAME</varname></link>.</para>
<important>
<para>The package name must be unique across the entire ports
tree. Make sure that the <varname>PORTNAME</varname> is not
- already in use by an existing port. If the name has already
- been used, add either
- <link
+ already in use by an existing port, and that no other port
+ already has the same <varname>PKGBASE</varname>. If the
+ name has already been used, add either <link
linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
or <varname>PKGNAMESUFFIX</varname></link>.</para>
</important>
</sect2>
+ <sect2 xml:id="makefile-versions">
+ <title>Versions, <varname>DISTVERSION</varname>
+ <emphasis>or</emphasis> <varname>PORTVERSION</varname></title>
+
+ <para>Set <varname>DISTVERSION</varname> to the version number
+ of the software.</para>
+
+ <para><varname>PORTVERSION</varname> is the version used for the
+ &os; package. It will be automatically derived from
+ <varname>DISTVERSION</varname> to be compatible with &os;'s
+ package versioning scheme. If the version contains
+ <emphasis>letters</emphasis>, it might be needed to set
+ <varname>PORTVERSION</varname> and not
+ <varname>DISTVERSION</varname>.</para>
+
+ <important>
+ <para>Only one of <varname>PORTVERSION</varname> and
+ <varname>DISTVERSION</varname> can be set at a time.</para>
+ </important>
+
+ <para>From time to time, some software will use a version
+ scheme that is not compatible with how
+ <varname>DISTVERSION</varname> translates in
+ <varname>PORTVERSION</varname>.</para>
+
+ <tip>
+ <para>When updating a port, it is possible to use
+ &man.pkg-version.8;'s <option>-t</option> argument to
+ check if the new version is greater or lesser than before.
+ See <xref
+ linkend="makefile-versions-ex-pkg-version"/>.</para>
+ </tip>
+
+ <example xml:id="makefile-versions-ex-pkg-version">
+ <title>Using &man.pkg-version.8; to Compare Versions.</title>
+
+ <para><command>pkg version -t</command> takes two versions as
+ arguments, it will respond with <literal><</literal>,
+ <literal>=</literal> or <literal>></literal> if the first
+ version is less, equal, or more than the second
+ version, respectively.</para>
+
+ <screen>&prompt.user; <userinput>pkg version -t 1.2 1.3</userinput>
+< <co xml:id="makefile-versions-tip-co1"/>
+&prompt.user; <userinput>pkg version -t 1.2 1.2</userinput>
+= <co xml:id="makefile-versions-tip-co2"/>
+&prompt.user; <userinput>pkg version -t 1.2 1.2.0</userinput>
+= <co xml:id="makefile-versions-tip-co3"/>
+&prompt.user; <userinput>pkg version -t 1.2 1.2.p1</userinput>
+> <co xml:id="makefile-versions-tip-co4"/>
+&prompt.user; <userinput>pkg version -t 1.2.a1 1.2.b1</userinput>
+< <co xml:id="makefile-versions-tip-co5"/>
+&prompt.user; <userinput>pkg version -t 1.2 1.2p1</userinput>
+< <co xml:id="makefile-versions-tip-co6"/></screen>
+
+ <calloutlist>
+ <callout arearefs="makefile-versions-tip-co1">
+ <para><literal>1.2</literal> is before
+ <literal>1.3</literal>.</para>
+ </callout>
+
+ <callout arearefs="makefile-versions-tip-co3">
+ <para><literal>1.2</literal> and <literal>1.2</literal>
+ are equal as they have the same version.</para>
+ </callout>
+
+ <callout arearefs="makefile-versions-tip-co3">
+ <para><literal>1.2</literal> and <literal>1.2.0</literal>
+ are equal as nothing equals zero.</para>
+ </callout>
+
+ <callout arearefs="makefile-versions-tip-co4">
+ <para><literal>1.2</literal> is after
+ <literal>1.2.p1</literal> as <literal>.p1</literal>,
+ think <quote>pre-release 1</quote>.</para>
+ </callout>
+
+ <callout arearefs="makefile-versions-tip-co4">
+ <para><literal>1.2.a1</literal> is before
+ <literal>1.2.b1</literal>, think <quote>alpha</quote>
+ and <quote>beta</quote>, and <literal>a</literal> is
+ before <literal>b</literal>.</para>
+ </callout>
+
+ <callout arearefs="makefile-versions-tip-co6">
+ <para><literal>1.2</literal> is before
+ <literal>1.2p1</literal> as <literal>2p1</literal>,
+ think <quote>2, patch level 1</quote> which is a version
+ after any <literal>2.X</literal> but before
+ <literal>3</literal>.</para>
+ </callout>
+ </calloutlist>
+
+ <note>
+ <para>In here, the <literal>a</literal>,
+ <literal>b</literal>, and <literal>p</literal> are used as
+ if meaning <quote>alpha</quote>, <quote>beta</quote> or
+ <quote>pre-release</quote> and <quote>patch level</quote>,
+ but they are only letters and are sorted alphabetically,
+ so any letter can be used, and they will be sorted
+ appropriately.</para>
+ </note>
+ </example>
+
+ <table frame="none" pgwide="0">
+ <title>Examples of <varname>DISTVERSION</varname> and the
+ Derived <varname>PORTVERSION</varname></title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry><varname>DISTVERSION</varname></entry>
+ <entry><varname>PORTVERSION</varname></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>0.7.1d</entry>
+ <entry>0.7.1.d</entry>
+ </row>
+
+ <row>
+ <entry>10Alpha3</entry>
+ <entry>10.a3</entry>
+ </row>
+
+ <row>
+ <entry>3Beta7-pre2</entry>
+ <entry>3.b7.p2</entry>
+ </row>
+
+ <row>
+ <entry>8:f_17</entry>
+ <entry>8f.17</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example xml:id="makefile-versions-ex1">
+ <title>Using <varname>DISTVERSION</varname></title>
+
+ <para>When the version only contains numbers separated by
+ dots, dashes or underscores, use
+ <varname>DISTVERSION</varname>.</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSION= 1.2-4</programlisting>
+
+ <para>It will generate a <varname>PORTVERSION</varname> of
+ <literal>1.2.4</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-versions-ex2">
+ <title>Using <varname>DISTVERSION</varname> When the Version
+ Starts with a Letter or a Prefix</title>
+
+ <para>When the version starts or ends with a letter, or a
+ prefix or a suffix that is not part of the version, use
+ <varname>DISTVERSIONPREFIX</varname>,
+ <varname>DISTVERSION</varname>, and
+ <varname>DISTVERSIONSUFFIX</varname>.</para>
+
+ <para>If the version is <literal>v1.2-4</literal>:</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSIONPREFIX= v
+DISTVERSION= 1_2_4</programlisting>
+
+ <para>Some of the time, projects using
+ <application>GitHub</application> will use their name in
+ their versions. For example, the version could be
+ <literal>nekoto-1.2-4</literal>:</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSIONPREFIX= nekoto-
+DISTVERSION= 1.2_4</programlisting>
+
+ <para>Those projects also sometimes use some string at the end
+ of the version, for example,
+ <literal>1.2-4_RELEASE</literal>:</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSION= 1.2-4
+DISTVERSIONSUFFIX= _RELEASE</programlisting>
+
+ <para>Or they do both, for example,
+ <literal>nekoto-1.2-4_RELEASE</literal>:</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSIONPREFIX= nekoto-
+DISTVERSION= 1.2-4
+DISTVERSIONSUFFIX= _RELEASE</programlisting>
+
+ <para><varname>DISTVERSIONPREFIX</varname> and
+ <varname>DISTVERSIONSUFFIX</varname> will not be used while
+ constructing <varname>PORTVERSION</varname>, but only used
+ in <varname>DISTNAME</varname>.</para>
+
+ <para>All will generate a <varname>PORTVERSION</varname> of
+ <literal>1.2.4</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-versions-ex3">
+ <title>Using <varname>DISTVERSION</varname> When the Version
+ Contains Letters Meaning <quote>alpha</quote>,
+ <quote>beta</quote>, or <quote>pre-release</quote></title>
+
+ <para>When the version contains numbers separated by dots,
+ dashes or underscores, and letters are used to mean
+ <quote>alpha</quote>, <quote>beta</quote> or
+ <quote>pre-release</quote>, which is, before the version
+ without the letters, use
+ <varname>DISTVERSION</varname>.</para>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSION= 1.2-pre4</programlisting>
+
+ <programlisting>PORTNAME= nekoto
+DISTVERSION= 1.2p4</programlisting>
+
+ <para>Both will generate a <varname>PORTVERSION</varname> of
+ <literal>1.2.p4</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-versions-ex4">
+ <title>Not Using <varname>DISTVERSION</varname> When the
+ Version Contains Letters Meaning "patch level"</title>
+
+ <para>When the version contains letters that are not meant as
+ <quote>alpha</quote>, <quote>beta</quote>, or
+ <quote>pre</quote>, but more in a <quote>patch
+ level</quote>, and meaning after the version without the
+ letters, use <varname>PORTVERSION</varname>.</para>
+
+ <programlisting>PORTNAME= nekoto
+PORTVERSION= 1.2p4</programlisting>
+
+ <para>In this case, using <varname>DISTVERSION</varname> is
+ not possible because it would generate a version of
+ <literal>1.2.p4</literal> which would be before
+ <literal>1.2</literal> and not after.</para>
+ </example>
+
+ <para>For some more advanced examples of setting
+ <varname>PORTVERSION</varname>, when the software's versioning
+ is really not compatible with &os;'s, or
+ <varname>DISTNAME</varname> when the distribution file does
+ not contain the version itself, see <xref
+ linkend="makefile-distname"/>.</para>
+ </sect2>
+
<sect2 xml:id="makefile-naming-revepoch">
<title><varname>PORTREVISION</varname> and
<varname>PORTEPOCH</varname></title>
@@ -1531,8 +1782,8 @@ PORTEPOCH= 1</programlisting>
describes the files that must be downloaded to build
the port, and where they can be downloaded.</para>
- <sect2 xml:id="makefile-distversion">
- <title><varname>DISTVERSION/DISTNAME</varname></title>
+ <sect2 xml:id="makefile-distname">
+ <title><varname>DISTNAME</varname></title>
<para><varname>DISTNAME</varname> is the name of the port as
called by the authors of the software.
@@ -1581,7 +1832,7 @@ PORTEPOCH= 1</programlisting>
<varname>DISTNAME</varname> with <varname>PORTNAME</varname>
with the verbatim upstream version.</para>
- <example xml:id="makefile-distversion-ex1">
+ <example xml:id="makefile-distname-ex1">
<title>Deriving <varname>PORTVERSION</varname>
Manually</title>
@@ -1668,7 +1919,7 @@ ISCVERSION= 9.9.9-P6 <co xml:id="distversion-ex1-iscve
</calloutlist>
</example>
- <example xml:id="makefile-distversion-ex2">
+ <example xml:id="makefile-distname-ex2">
<title>Derive <varname>DISTNAME</varname> from
<varname>PORTVERSION</varname></title>
@@ -1696,7 +1947,7 @@ DISTNAME= cku${PORTVERSION:E}-dev20 <co xml:id="distve
</calloutlist>
</example>
- <example xml:id="makefile-distversion-ex3">
+ <example xml:id="makefile-distname-ex3">
<title>Exotic Case 1</title>
<para>Sometimes, there is no relation between the software
@@ -1713,7 +1964,7 @@ MASTER_SITES= LOCAL/jim
DISTNAME= ${PORTNAME}-1999-06-20</programlisting>
</example>
- <example xml:id="makefile-distversion-ex4">
+ <example xml:id="makefile-distname-ex4">
<title>Exotic Case 2</title>
<para>In <package role="port">comms/librs232</package>, the
@@ -1728,42 +1979,6 @@ MASTER_SITES= http://www.teuniz.net/RS-232/
DISTNAME= RS-232
DIST_SUBDIR= ${PORTNAME}-${PORTVERSION}</programlisting>
</example>
-
- <table frame="none" pgwide="0">
- <title>Examples of <varname>DISTVERSION</varname> and the
- Derived <varname>PORTVERSION</varname></title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry><varname>DISTVERSION</varname></entry>
- <entry><varname>PORTVERSION</varname></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>0.7.1d</entry>
- <entry>0.7.1.d</entry>
- </row>
-
- <row>
- <entry>10Alpha3</entry>
- <entry>10.a3</entry>
- </row>
-
- <row>
- <entry>3Beta7-pre2</entry>
- <entry>3.b7.p2</entry>
- </row>
-
- <row>
- <entry>8:f_17</entry>
- <entry>8f.17</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
<note>
<para><varname>PKGNAMEPREFIX</varname> and
Modified: head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml Fri Aug 4 10:23:55 2017 (r50627)
+++ head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml Fri Aug 4 10:23:58 2017 (r50628)
@@ -60,22 +60,22 @@
<listitem>
<para><link
- linkend="makefile-portname"><varname>PORTVERSION</varname></link></para>
+ linkend="makefile-versions"><varname>PORTVERSION</varname></link></para>
</listitem>
<listitem>
<para><link
- linkend="makefile-distversion"><varname>DISTVERSIONPREFIX</varname></link></para>
+ linkend="makefile-versions"><varname>DISTVERSIONPREFIX</varname></link></para>
</listitem>
<listitem>
<para><link
- linkend="makefile-distversion"><varname>DISTVERSION</varname></link></para>
+ linkend="makefile-versions"><varname>DISTVERSION</varname></link></para>
</listitem>
<listitem>
<para><link
- linkend="makefile-distversion"><varname>DISTVERSIONSUFFIX</varname></link></para>
+ linkend="makefile-versions"><varname>DISTVERSIONSUFFIX</varname></link></para>
</listitem>
<listitem>
@@ -116,7 +116,7 @@
<listitem>
<para><link
- linkend="makefile-distversion"><varname>DISTNAME</varname></link></para>
+ linkend="makefile-distname"><varname>DISTNAME</varname></link></para>
</listitem>
<listitem>
More information about the svn-doc-all
mailing list