Index: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -49,26 +49,277 @@
the correct category.
- PORTNAME and
- PORTVERSION
+ PORTNAME
- 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, DISTVERSION
+ orPORTVERSION
+
+ 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.
+
+
+
+
+
+
+ Using DISTVERSION
+
+ 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 DISTVERSION 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 DISTVERSION When the Version
+ Contains Letters Meaning alpha,
+ beta, or pre-release
+
+ 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 DISTVERSION 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 .
+
+
PORTREVISION and
PORTEPOCH
@@ -1531,8 +1782,8 @@
describes the files that must be downloaded to build
the port, and where they can be downloaded.
-
- DISTVERSION/DISTNAME
+
+ DISTNAMEDISTNAME is the name of the port as
called by the authors of the software.
@@ -1581,7 +1832,7 @@
DISTNAME with PORTNAME
with the verbatim upstream version.
-
+ Deriving PORTVERSION
Manually
@@ -1668,7 +1919,7 @@
-
+ Derive DISTNAME from
PORTVERSION
@@ -1696,7 +1947,7 @@
-
+ Exotic Case 1Sometimes, there is no relation between the software
@@ -1713,7 +1964,7 @@
DISTNAME= ${PORTNAME}-1999-06-20
-
+ Exotic Case 2In comms/librs232, the
@@ -1728,42 +1979,6 @@
DISTNAME= RS-232
DIST_SUBDIR= ${PORTNAME}-${PORTVERSION}
-
-