From owner-svn-doc-all@freebsd.org Fri Apr 21 13:42:17 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 29FF3D414ED; Fri, 21 Apr 2017 13:42:17 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id E127B1E04; Fri, 21 Apr 2017 13:42:16 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v3LDgF0g013517; Fri, 21 Apr 2017 13:42:15 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v3LDgFc4013516; Fri, 21 Apr 2017 13:42:15 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201704211342.v3LDgFc4013516@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Fri, 21 Apr 2017 13:42:15 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 21 Apr 2017 13:42:17 -0000 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 DISTNAME defaults to ${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}, and DISTVERSION defaults to - ${PORTVERSION} so override it + ${PORTVERSION} so override + DISTNAME only if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to @@ -1551,23 +1552,182 @@ PORTEPOCH= 1 Some vendor's distribution names which do not fit into the ${PORTNAME}-${PORTVERSION}-scheme can be handled automatically by setting - DISTVERSION. - PORTVERSION will be derived from it - automatically. + DISTVERSIONPREFIX, + DISTVERSION, and + DISTVERSIONSUFFIX. + PORTVERSION will be derived from + DISTVERSION automatically. - + Only one of PORTVERSION and DISTVERSION can be set at a time. If DISTVERSION does not derive a correct PORTVERSION, do not use - DISTVERSION, set - PORTVERSION to the right value and set - DISTNAME with PORTNAME - with either some computation of - PORTVERSION or the verbatim upstream - version. - + DISTVERSION. + + If the upstream version scheme can be derived into a + ports-compatible version scheme, set some variable to the + upstream version, do not use + DISTVERSION as the variable name. Set + PORTVERSION to the computed version based + on the variable you + created, and set DISTNAME + accordingly. + + If the upstream version scheme cannot easily be coerced + into a ports-compatible value, set + PORTVERSION to a sensible value, and set + DISTNAME with PORTNAME + with the verbatim upstream version. + + + Deriving <varname>PORTVERSION</varname> + Manually + + BIND9 uses a version scheme + that is not compatible with the ports versions (it has + - in its versions) and cannot be derived + using DISTVERSION because after the 9.9.9 + release, it will release a patchlevels in the + form of 9.9.9-P1. DISTVERSION would + translate that into 9.9.9.p1, which, in + the ports versioning scheme means 9.9.9 pre-release 1, which + is before 9.9.9 and not after. So + PORTVERSION is manually derived from an + ISCVERSION variable in order to output + 9.9.9p1. + + The order into which the ports framework, and pkg, will + sort versions is checked using the -t + argument of &man.pkg-version.8;: + + &prompt.user; pkg version -t 9.9.9 9.9.9.p1 +> +&prompt.user; pkg version -t 9.9.9 9.9.9p1 +< + + + + The > sign means that the + first argument passed to -t is + greater than the second argument. + 9.9.9 is after + 9.9.9.p1. + + + + The < sign means that the + first argument passed to -t is less + than the second argument. 9.9.9 is + before 9.9.9p1. + + + + In the port Makefile, for example + dns/bind99, it is achieved + by: + + PORTNAME= bind +PORTVERSION= ${ISCVERSION:S/-P/P/:S/b/.b/:S/a/.a/:S/rc/.rc/} +CATEGORIES= dns net ipv6 +MASTER_SITES= ISC/bind9/${ISCVERSION} +PKGNAMESUFFIX= 99 +DISTNAME= ${PORTNAME}-${ISCVERSION} + +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 + + + + Define upstream version in + ISCVERSION, with a comment saying + why it is needed. + + + + Use ISCVERSION to get a + ports-compatible PORTVERSION. + + + + Use ISCVERSION directly to get + the correct URL for fetching the + distribution file. + + + + Use ISCVERSION directly to name + the distribution file. + + + + + + Derive <varname>DISTNAME</varname> from + <varname>PORTVERSION</varname> + + From time to time, the distribution file name has little + or no relation to the version of the software. + + In comms/kermit, only the + last element of the version is present in the distribution + file: + + PORTNAME= kermit +PORTVERSION= 9.0.304 +CATEGORIES= comms ftp net +MASTER_SITES= ftp://ftp.kermitproject.org/kermit/test/tar/ +DISTNAME= cku${PORTVERSION:E}-dev20 + + + + The :E &man.make.1; modifier + returns the suffix of the variable, in this case, + 304. The distribution file is + correctly generated as + cku304-dev20.tar.gz. + + + + + + Exotic Case 1 + + Sometimes, there is no relation between the software + name, its version, and the distribution file it is + distributed in. + + From audio/libworkman: + + PORTNAME= libworkman +PORTVERSION= 1.4 +CATEGORIES= audio +MASTER_SITES= LOCAL/jim +DISTNAME= ${PORTNAME}-1999-06-20 + + + + Exotic Case 2 + + In comms/librs232, the + distribution file is not versioned, so using DIST_SUBDIR + is needed: + + PORTNAME= librs232 +PORTVERSION= 20160710 +CATEGORIES= comms +MASTER_SITES= http://www.teuniz.net/RS-232/ +DISTNAME= RS-232 +DIST_SUBDIR= ${PORTNAME}-${PORTVERSION} + Examples of <varname>DISTVERSION</varname> and the