Index: en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml @@ -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 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> @@ -78,7 +329,7 @@ PORTREVISION is a monotonically increasing value which is reset to 0 with - every increase of PORTVERSION, typically + every increase of DISTVERSION, typically every time there is a new official vendor release. If PORTREVISION is non-zero, the value is appended to the package name. Changes to @@ -128,7 +379,7 @@ significant functional differences. For example, changes to the distfile requiring a correction to distinfo with no corresponding - change to PORTVERSION, where a + change to DISTVERSION, where a diff -ru of the old and new versions shows non-trivial changes to the code. @@ -236,7 +487,9 @@ It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use - of PORTVERSION can often preempt it + of DISTVERSION, or that use + PORTVERSION carefully, can often preempt + it becoming necessary if a future release of the software changes the version structure. However, care is needed by &os; porters when a vendor release is made without @@ -250,8 +503,8 @@ 20000917, and the previous version of the software was version 1.2, do not use 20000917 for - PORTVERSION. The correct way is a - PORTVERSION of + DISTVERSION. The correct way is a + DISTVERSION of 1.2.20000917, or similar, so that the succeeding release, say 1.3, is still a numerically greater value. @@ -266,7 +519,7 @@ collection: PORTNAME= gtkmumble -PORTVERSION= 0.10 +DISTVERSION= 0.10 PKGNAME becomes gtkmumble-0.10. @@ -276,7 +529,7 @@ accordingly. PORTNAME= gtkmumble -PORTVERSION= 0.10 +DISTVERSION= 0.10 PORTREVISION= 1 PKGNAME becomes @@ -296,7 +549,7 @@ removed from the Makefile). PORTNAME= gtkmumble -PORTVERSION= 0.2 +DISTVERSION= 0.2 PORTEPOCH= 1 PKGNAME becomes @@ -307,7 +560,7 @@ variables are now: PORTNAME= gtkmumble -PORTVERSION= 0.3 +DISTVERSION= 0.3 PORTEPOCH= 1 PKGNAME becomes @@ -398,7 +651,7 @@ Make sure that the port's name and version are clearly separated and placed into PORTNAME and - PORTVERSION. The only + DISTVERSION. The only reason for PORTNAME to contain a version part is if the upstream distribution is really named that way, as in the @@ -489,8 +742,11 @@ Here are some (real) examples on how to convert the name - as called by the software authors to a suitable package - name: + as called by the software authors to a suitable package name, + for each line, only one of DISTVERSION or + PORTVERSION is set in, depending on which + would be used in the port's + Makefile: Package Naming Examples @@ -502,8 +758,9 @@ PKGNAMEPREFIXPORTNAMEPKGNAMESUFFIX + DISTVERSIONPORTVERSION - Reason + Reason or comment @@ -514,6 +771,7 @@ mule(empty)2.2.2 + No changes required @@ -523,7 +781,10 @@ mule11.0.1 - mule already exists + + This is version 1 of + mule, and version 2 already + exists @@ -532,6 +793,7 @@ emiclock (empty) 1.0.2 + No uppercase names for single programs @@ -540,9 +802,9 @@ (empty)rdist(empty) - 1.3.a - No strings like alpha - allowed + 1.3alpha + + Version will be 1.3.a @@ -550,9 +812,9 @@ (empty) es (empty) - 0.9.b1 - No strings like beta - allowed + 0.9-beta1 + + Version will be 0.9.b1 @@ -560,9 +822,9 @@ (empty) mailman (empty) - 2.0.r3 - No strings like rc - allowed + 2.0rc3 + + Version will be 2.0.r3 @@ -570,6 +832,7 @@ (empty) tiff (empty) + 3.3 What the heck was that anyway? @@ -579,8 +842,10 @@ (empty)tvtwm(empty) - pl11 - Version string always required + + p11 + No version in the filename, use what upstream + says it is @@ -589,7 +854,9 @@ piewm (empty) 1.0 - Version string always required + + No version in the filename, use what upstream + says it is @@ -597,9 +864,10 @@ (empty) xvgr (empty) - 2.10.1 - pl allowed only when no - major/minor version numbers + + 2.10.pl1 + In that case, pl1 means patch + level, so using DISTVERSION is not possible. @@ -608,6 +876,7 @@ gawk (empty) 2.15.6 + Japanese language version @@ -617,6 +886,7 @@ psutils-letter1.13 + Paper size hardcoded at package build time @@ -627,6 +897,7 @@ pkfonts3001.0 + Package for 300dpi fonts @@ -1531,14 +1802,14 @@ 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. DISTNAME defaults to ${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}, - and DISTVERSION defaults to + and if not set, DISTVERSION defaults to ${PORTVERSION} so override DISTNAME only if necessary. DISTNAME is only used @@ -1581,7 +1852,7 @@ DISTNAME with PORTNAME with the verbatim upstream version. - + Deriving <varname>PORTVERSION</varname> Manually @@ -1668,7 +1939,7 @@ - + Derive <varname>DISTNAME</varname> from <varname>PORTVERSION</varname> @@ -1696,7 +1967,7 @@ - + Exotic Case 1 Sometimes, there is no relation between the software @@ -1713,7 +1984,7 @@ DISTNAME= ${PORTNAME}-1999-06-20 - + Exotic Case 2 In comms/librs232, the @@ -1729,42 +2000,6 @@ 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 PKGNAMESUFFIX do not affect @@ -2186,7 +2421,7 @@ this (slightly stripped for the example): PORTNAME= pkg -PORTVERSION= 1.2.7 +DISTVERSION= 1.2.7 USE_GITHUB= yes GH_ACCOUNT= freebsd @@ -2209,7 +2444,7 @@ this (slightly stripped for the example): PORTNAME= pkg-devel -PORTVERSION= 1.3.0.a.20140411 +DISTVERSION= 1.3.0.a.20140411 USE_GITHUB= yes GH_ACCOUNT= freebsd @@ -2234,8 +2469,8 @@ DISTVERSIONSUFFIX: PORTNAME= foo -PORTVERSION= 1.0.2 DISTVERSIONPREFIX= v +DISTVERSION= 1.0.2 USE_GITHUB= yes @@ -2315,7 +2550,7 @@ variables: PORTNAME= foo -PORTVERSION= 1.0.2 +DISTVERSION= 1.0.2 USE_GITHUB= yes GH_ACCOUNT= bar:icons,contrib @@ -2375,7 +2610,7 @@ using GH_TUPLE: PORTNAME= foo -PORTVERSION= 1.0.2 +DISTVERSION= 1.0.2 USE_GITHUB= yes GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ @@ -2480,8 +2715,8 @@ (only GitHub-related lines are shown): PORTNAME= moneymanagerex -PORTVERSION= 1.3.0 DISTVERSIONPREFIX= v +DISTVERSION= 1.3.0 USE_GITHUB= yes GH_TUPLE= utelle:wxsqlite3:v3.4.0:wxsqlite3/lib/wxsqlite3 \ @@ -5233,7 +5468,7 @@ of japanese/xdvi300/Makefile; PORTNAME= xdvi -PORTVERSION= 17 +DISTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} @@ -6682,7 +6917,7 @@ Makefile has: PORTNAME= foo -PORTVERSION= 1.0 +DISTVERSION= 1.0 then the port's distribution files contain a top-level directory, foo-1.0, and the rest of the Index: en_US.ISO8859-1/books/porters-handbook/order/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/order/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/order/chapter.xml @@ -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 Index: en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml @@ -318,7 +318,7 @@ Makefile: PORTNAME= Machine-Build -PORTVERSION= 1 +DISTVERSION= 1 CATEGORIES= devel perl5 MASTER_SITES= CPAN PKGNAMEPREFIX= p5- Index: en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml @@ -29,13 +29,13 @@ this line back to "$FreeBSD$". SVN deals with it automatically.] [section to describe the port itself and the master site - PORTNAME - and PORTVERSION are always first, followed by CATEGORIES, - and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. - PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. - Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then - EXTRACT_ONLY, as necessary.] + and PORTVERSION or the DISTVERSION* variables are always first, + followed by CATEGORIES, and then MASTER_SITES, which can be followed + by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, + will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or + DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi -PORTVERSION= 18.2 +DISTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if not using MASTER_SITE_* macros] Index: en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml @@ -48,7 +48,7 @@ # $FreeBSD$ PORTNAME= oneko -PORTVERSION= 1.1b +DISTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ Index: en_US.ISO8859-1/books/porters-handbook/security/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/security/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/security/chapter.xml @@ -76,12 +76,12 @@ to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. Bump PORTREVISION unless - PORTVERSION has changed in the course of + DISTVERSION has changed in the course of correcting the vulnerability. That is, bump PORTREVISION if adding a patch file to the port, but do not bump it if updating the port to the latest software version and thus already touched - PORTVERSION. Please refer to the + DISTVERSION. Please refer to the corresponding section for more information. Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml @@ -1454,7 +1454,7 @@ # $FreeBSD$ PORTNAME= regexxer -PORTVERSION= 0.10 +DISTVERSION= 0.10 CATEGORIES= devel textproc gnome MASTER_SITES= GNOME @@ -3519,7 +3519,7 @@ Example Makefile for PEAR Class PORTNAME= Date -PORTVERSION= 1.4.3 +DISTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= example@domain.com @@ -3554,7 +3554,7 @@ Module PORTNAME= Horde_Core -PORTVERSION= 2.14.0 +DISTVERSION= 2.14.0 CATEGORIES= devel www pear MAINTAINER= horde@FreeBSD.org @@ -3707,7 +3707,7 @@ Module PORTNAME= sample -PORTVERSION= 1.2.3 +DISTVERSION= 1.2.3 CATEGORIES= devel MAINTAINER= john@doe.tld