os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Expand on DISTVERSION and add examples.

Browse source 
Sponsored by:	Absolight
Differential Revision:	https://reviews.freebsd.org/D10370
This commit is contained in:
Mathieu Arnold 2017-04-21 13:42:15 +00:00
parent 7e4ae0ab92
commit 496def4170
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=50191
1 changed files with 172 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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>
&gt; <co xml:id="distversion-ex1-gt"/>
&prompt.user; <userinput>pkg version -t 9.9.9 9.9.9p1</userinput>
&lt; <co xml:id="distversion-ex1-lt"/></screen>
<calloutlist>
<callout arearefs="distversion-ex1-gt">
<para>The <literal>&gt;</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>&lt;</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