svn commit: r50191 - head/en_US.ISO8859-1/books/porters-handbook/makefiles

Mathieu Arnold <[email protected]>
Newsgroups gmane.os.freebsd.devel.cvs.doc
Message-ID <[email protected]> 
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>
+&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=	[email protected]
+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
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.