Date: Fri, 4 Aug 2017 10:23:58 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50628 - in head/en_US.ISO8859-1/books/porters-handbook: makefiles order Message-ID: <201708041023.v74ANw2b068747@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201708041023.v74ANw2b068747>