Date: Fri, 21 Apr 2017 13:42:15 +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: r50191 - head/en_US.ISO8859-1/books/porters-handbook/makefiles Message-ID: <201704211342.v3LDgFc4013516@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat Date: Fri Apr 21 13:42:15 2017 New Revision: 50191 URL: https://svnweb.freebsd.org/changeset/doc/50191 Log: Expand on DISTVERSION and add examples. Sponsored by: Absolight Differential Revision: https://reviews.freebsd.org/D10370 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 Fri Apr 21 13:42:12 2017 (r50190) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Apr 21 13:42:15 2017 (r50191) @@ -1539,7 +1539,8 @@ PORTEPOCH= 1</programlisting> <varname>DISTNAME</varname> defaults to <literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>, and <varname>DISTVERSION</varname> defaults to - <literal>${PORTVERSION}</literal> so override it + <literal>${PORTVERSION}</literal> so override + <varname>DISTNAME</varname> only if necessary. <varname>DISTNAME</varname> is only used in two places. First, the distribution file list (<varname>DISTFILES</varname>) defaults to @@ -1551,23 +1552,182 @@ PORTEPOCH= 1</programlisting> <para>Some vendor's distribution names which do not fit into the <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be handled automatically by setting - <varname>DISTVERSION</varname>. - <varname>PORTVERSION</varname> will be derived from it - automatically.</para> + <varname>DISTVERSIONPREFIX</varname>, + <varname>DISTVERSION</varname>, and + <varname>DISTVERSIONSUFFIX</varname>. + <varname>PORTVERSION</varname> will be derived from + <varname>DISTVERSION</varname> automatically.</para> - <note> + <important> <para>Only one of <varname>PORTVERSION</varname> and <varname>DISTVERSION</varname> can be set at a time. If <varname>DISTVERSION</varname> does not derive a correct <varname>PORTVERSION</varname>, do not use - <varname>DISTVERSION</varname>, set - <varname>PORTVERSION</varname> to the right value and set - <varname>DISTNAME</varname> with <varname>PORTNAME</varname> - with either some computation of - <varname>PORTVERSION</varname> or the verbatim upstream - version.</para> - </note> + <varname>DISTVERSION</varname>.</para> + </important> + <para>If the upstream version scheme can be derived into a + ports-compatible version scheme, set some variable to the + upstream version, <emphasis>do not</emphasis> use + <varname>DISTVERSION</varname> as the variable name. Set + <varname>PORTVERSION</varname> to the computed version based + on the variable you + created, and set <varname>DISTNAME</varname> + accordingly.</para> + + <para>If the upstream version scheme cannot easily be coerced + into a ports-compatible value, set + <varname>PORTVERSION</varname> to a sensible value, and set + <varname>DISTNAME</varname> with <varname>PORTNAME</varname> + with the verbatim upstream version.</para> + + <example xml:id="makefile-distversion-ex1"> + <title>Deriving <varname>PORTVERSION</varname> + Manually</title> + + <para><application>BIND9</application> uses a version scheme + that is not compatible with the ports versions (it has + <literal>-</literal> in its versions) and cannot be derived + using <varname>DISTVERSION</varname> because after the 9.9.9 + release, it will release a <quote>patchlevels</quote> in the + form of <literal>9.9.9-P1</literal>. DISTVERSION would + translate that into <literal>9.9.9.p1</literal>, which, in + the ports versioning scheme means 9.9.9 pre-release 1, which + is before 9.9.9 and not after. So + <varname>PORTVERSION</varname> is manually derived from an + <varname>ISCVERSION</varname> variable in order to output + <literal>9.9.9p1</literal>.</para> + + <para>The order into which the ports framework, and pkg, will + sort versions is checked using the <literal>-t</literal> + argument of &man.pkg-version.8;:</para> + + <screen>&prompt.user; <userinput>pkg version -t 9.9.9 9.9.9.p1</userinput> +> <co xml:id="distversion-ex1-gt"/> +&prompt.user; <userinput>pkg version -t 9.9.9 9.9.9p1</userinput> +< <co xml:id="distversion-ex1-lt"/></screen> + + <calloutlist> + <callout arearefs="distversion-ex1-gt"> + <para>The <literal>></literal> sign means that the + first argument passed to <literal>-t</literal> is + greater than the second argument. + <literal>9.9.9</literal> is after + <literal>9.9.9.p1</literal>.</para> + </callout> + + <callout arearefs="distversion-ex1-lt"> + <para>The <literal><</literal> sign means that the + first argument passed to <literal>-t</literal> is less + than the second argument. <literal>9.9.9</literal> is + before <literal>9.9.9p1</literal>.</para> + </callout> + </calloutlist> + + <para>In the port <filename>Makefile</filename>, for example + <package role="port">dns/bind99</package>, it is achieved + by:</para> + + <programlisting>PORTNAME= bind +PORTVERSION= ${ISCVERSION:S/-P/P/:S/b/.b/:S/a/.a/:S/rc/.rc/} <co xml:id="distversion-ex1-portversion"/> +CATEGORIES= dns net ipv6 +MASTER_SITES= ISC/bind9/${ISCVERSION} <co xml:id="distversion-ex1-master_sites"/> +PKGNAMESUFFIX= 99 +DISTNAME= ${PORTNAME}-${ISCVERSION} <co xml:id="distversion-ex1-distname"/> + +MAINTAINER= mat@FreeBSD.org +COMMENT= BIND DNS suite with updated DNSSEC and DNS64 + +LICENSE= ISCL + +# ISC releases things like 9.8.0-P1 or 9.8.1rc1, which our versioning does not like +ISCVERSION= 9.9.9-P6 <co xml:id="distversion-ex1-iscversion"/></programlisting> + + <calloutlist> + <callout arearefs="distversion-ex1-iscversion"> + <para>Define upstream version in + <varname>ISCVERSION</varname>, with a comment saying + <emphasis>why</emphasis> it is needed.</para> + </callout> + + <callout arearefs="distversion-ex1-portversion"> + <para>Use <varname>ISCVERSION</varname> to get a + ports-compatible <varname>PORTVERSION</varname>.</para> + </callout> + + <callout arearefs="distversion-ex1-master_sites"> + <para>Use <varname>ISCVERSION</varname> directly to get + the correct <acronym>URL</acronym> for fetching the + distribution file.</para> + </callout> + + <callout arearefs="distversion-ex1-distname"> + <para>Use <varname>ISCVERSION</varname> directly to name + the distribution file.</para> + </callout> + </calloutlist> + </example> + + <example xml:id="makefile-distversion-ex2"> + <title>Derive <varname>DISTNAME</varname> from + <varname>PORTVERSION</varname></title> + + <para>From time to time, the distribution file name has little + or no relation to the version of the software.</para> + + <para>In <package role="port">comms/kermit</package>, only the + last element of the version is present in the distribution + file:</para> + + <programlisting>PORTNAME= kermit +PORTVERSION= 9.0.304 +CATEGORIES= comms ftp net +MASTER_SITES= ftp://ftp.kermitproject.org/kermit/test/tar/ +DISTNAME= cku${PORTVERSION:E}-dev20 <co xml:id="distversion-ex2-distname"/></programlisting> + + <calloutlist> + <callout arearefs="distversion-ex2-distname"> + <para>The <literal>:E</literal> &man.make.1; modifier + returns the suffix of the variable, in this case, + <literal>304</literal>. The distribution file is + correctly generated as + <literal>cku304-dev20.tar.gz</literal>.</para> + </callout> + </calloutlist> + </example> + + <example xml:id="makefile-distversion-ex3"> + <title>Exotic Case 1</title> + + <para>Sometimes, there is no relation between the software + name, its version, and the distribution file it is + distributed in.</para> + + <para>From <package + role="port">audio/libworkman</package>:</para> + + <programlisting>PORTNAME= libworkman +PORTVERSION= 1.4 +CATEGORIES= audio +MASTER_SITES= LOCAL/jim +DISTNAME= ${PORTNAME}-1999-06-20</programlisting> + </example> + + <example xml:id="makefile-distversion-ex4"> + <title>Exotic Case 2</title> + + <para>In <package role="port">comms/librs232</package>, the + distribution file is not versioned, so using <link + linkend="makefile-dist_subdir"><varname>DIST_SUBDIR</varname></link> + is needed:</para> + + <programlisting>PORTNAME= librs232 +PORTVERSION= 20160710 +CATEGORIES= comms +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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201704211342.v3LDgFc4013516>