From owner-svn-doc-all@freebsd.org Fri Aug 4 10:23:59 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 65662DD1D0F; Fri, 4 Aug 2017 10:23:59 +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 321C83333; Fri, 4 Aug 2017 10:23:59 +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 v74ANw4m068749; Fri, 4 Aug 2017 10:23:58 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v74ANw2b068747; Fri, 4 Aug 2017 10:23:58 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201708041023.v74ANw2b068747@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Fri, 4 Aug 2017 10:23:58 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: mat X-SVN-Commit-Paths: in head/en_US.ISO8859-1/books/porters-handbook: makefiles order X-SVN-Commit-Revision: 50628 X-SVN-Commit-Repository: doc 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, 04 Aug 2017 10:23:59 -0000 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. - <varname>PORTNAME</varname> and - <varname>PORTVERSION</varname> + <varname>PORTNAME</varname> - Set PORTNAME to the base - name of the port. Set PORTVERSION to the - version number of the port unless - DISTVERSION is used (see - ). + Set PORTNAME to the base name of the + software. It is used as the base for the &os; package, and + for DISTNAME. The package name must be unique across the entire ports tree. Make sure that the PORTNAME is not - already in use by an existing port. If the name has already - been used, add either - PKGBASE. If the + name has already been used, add either PKGNAMEPREFIX or PKGNAMESUFFIX. + + Versions, <varname>DISTVERSION</varname> + <emphasis>or</emphasis> <varname>PORTVERSION</varname> + + Set DISTVERSION to the version number + of the software. + + PORTVERSION is the version used for the + &os; package. It will be automatically derived from + DISTVERSION to be compatible with &os;'s + package versioning scheme. If the version contains + letters, it might be needed to set + PORTVERSION and not + DISTVERSION. + + + Only one of PORTVERSION and + DISTVERSION can be set at a time. + + + From time to time, some software will use a version + scheme that is not compatible with how + DISTVERSION translates in + PORTVERSION. + + + When updating a port, it is possible to use + &man.pkg-version.8;'s argument to + check if the new version is greater or lesser than before. + See . + + + + Using &man.pkg-version.8; to Compare Versions. + + pkg version -t takes two versions as + arguments, it will respond with <, + = or > if the first + version is less, equal, or more than the second + version, respectively. + + &prompt.user; pkg version -t 1.2 1.3 +< +&prompt.user; pkg version -t 1.2 1.2 += +&prompt.user; pkg version -t 1.2 1.2.0 += +&prompt.user; pkg version -t 1.2 1.2.p1 +> +&prompt.user; pkg version -t 1.2.a1 1.2.b1 +< +&prompt.user; pkg version -t 1.2 1.2p1 +< + + + + 1.2 is before + 1.3. + + + + 1.2 and 1.2 + are equal as they have the same version. + + + + 1.2 and 1.2.0 + are equal as nothing equals zero. + + + + 1.2 is after + 1.2.p1 as .p1, + think pre-release 1. + + + + 1.2.a1 is before + 1.2.b1, think alpha + and beta, and a is + before b. + + + + 1.2 is before + 1.2p1 as 2p1, + think 2, patch level 1 which is a version + after any 2.X but before + 3. + + + + + In here, the a, + b, and p are used as + if meaning alpha, beta or + pre-release and patch level, + but they are only letters and are sorted alphabetically, + so any letter can be used, and they will be sorted + appropriately. + + + + + Examples of <varname>DISTVERSION</varname> and the + Derived <varname>PORTVERSION</varname> + + + + + DISTVERSION + PORTVERSION + + + + + + 0.7.1d + 0.7.1.d + + + + 10Alpha3 + 10.a3 + + + + 3Beta7-pre2 + 3.b7.p2 + + + + 8:f_17 + 8f.17 + + + +
+ + + Using <varname>DISTVERSION</varname> + + When the version only contains numbers separated by + dots, dashes or underscores, use + DISTVERSION. + + PORTNAME= nekoto +DISTVERSION= 1.2-4 + + It will generate a PORTVERSION of + 1.2.4. + + + + Using <varname>DISTVERSION</varname> When the Version + Starts with a Letter or a Prefix + + When the version starts or ends with a letter, or a + prefix or a suffix that is not part of the version, use + DISTVERSIONPREFIX, + DISTVERSION, and + DISTVERSIONSUFFIX. + + If the version is v1.2-4: + + PORTNAME= nekoto +DISTVERSIONPREFIX= v +DISTVERSION= 1_2_4 + + Some of the time, projects using + GitHub will use their name in + their versions. For example, the version could be + nekoto-1.2-4: + + PORTNAME= nekoto +DISTVERSIONPREFIX= nekoto- +DISTVERSION= 1.2_4 + + Those projects also sometimes use some string at the end + of the version, for example, + 1.2-4_RELEASE: + + PORTNAME= nekoto +DISTVERSION= 1.2-4 +DISTVERSIONSUFFIX= _RELEASE + + Or they do both, for example, + nekoto-1.2-4_RELEASE: + + PORTNAME= nekoto +DISTVERSIONPREFIX= nekoto- +DISTVERSION= 1.2-4 +DISTVERSIONSUFFIX= _RELEASE + + DISTVERSIONPREFIX and + DISTVERSIONSUFFIX will not be used while + constructing PORTVERSION, but only used + in DISTNAME. + + All will generate a PORTVERSION of + 1.2.4. + + + + Using <varname>DISTVERSION</varname> When the Version + Contains Letters Meaning <quote>alpha</quote>, + <quote>beta</quote>, or <quote>pre-release</quote> + + When the version contains numbers separated by dots, + dashes or underscores, and letters are used to mean + alpha, beta or + pre-release, which is, before the version + without the letters, use + DISTVERSION. + + PORTNAME= nekoto +DISTVERSION= 1.2-pre4 + + PORTNAME= nekoto +DISTVERSION= 1.2p4 + + Both will generate a PORTVERSION of + 1.2.p4. + + + + Not Using <varname>DISTVERSION</varname> When the + Version Contains Letters Meaning "patch level" + + When the version contains letters that are not meant as + alpha, beta, or + pre, but more in a patch + level, and meaning after the version without the + letters, use PORTVERSION. + + PORTNAME= nekoto +PORTVERSION= 1.2p4 + + In this case, using DISTVERSION is + not possible because it would generate a version of + 1.2.p4 which would be before + 1.2 and not after. + + + For some more advanced examples of setting + PORTVERSION, when the software's versioning + is really not compatible with &os;'s, or + DISTNAME when the distribution file does + not contain the version itself, see . + + <varname>PORTREVISION</varname> and <varname>PORTEPOCH</varname> @@ -1531,8 +1782,8 @@ PORTEPOCH= 1 describes the files that must be downloaded to build the port, and where they can be downloaded. - - <varname>DISTVERSION/DISTNAME</varname> + + <varname>DISTNAME</varname> DISTNAME is the name of the port as called by the authors of the software. @@ -1581,7 +1832,7 @@ PORTEPOCH= 1 DISTNAME with PORTNAME with the verbatim upstream version. - + Deriving <varname>PORTVERSION</varname> Manually @@ -1668,7 +1919,7 @@ ISCVERSION= 9.9.9-P6 + Derive <varname>DISTNAME</varname> from <varname>PORTVERSION</varname> @@ -1696,7 +1947,7 @@ DISTNAME= cku${PORTVERSION:E}-dev20 + Exotic Case 1 Sometimes, there is no relation between the software @@ -1713,7 +1964,7 @@ MASTER_SITES= LOCAL/jim DISTNAME= ${PORTNAME}-1999-06-20 - + Exotic Case 2 In comms/librs232, the @@ -1728,42 +1979,6 @@ MASTER_SITES= http://www.teuniz.net/RS-232/ DISTNAME= RS-232 DIST_SUBDIR= ${PORTNAME}-${PORTVERSION} - - - Examples of <varname>DISTVERSION</varname> and the - Derived <varname>PORTVERSION</varname> - - - - - DISTVERSION - PORTVERSION - - - - - - 0.7.1d - 0.7.1.d - - - - 10Alpha3 - 10.a3 - - - - 3Beta7-pre2 - 3.b7.p2 - - - - 8:f_17 - 8f.17 - - - -
PKGNAMEPREFIX 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 @@ PORTVERSION + linkend="makefile-versions">PORTVERSION DISTVERSIONPREFIX + linkend="makefile-versions">DISTVERSIONPREFIX DISTVERSION + linkend="makefile-versions">DISTVERSION DISTVERSIONSUFFIX + linkend="makefile-versions">DISTVERSIONSUFFIX @@ -116,7 +116,7 @@ DISTNAME + linkend="makefile-distname">DISTNAME