Date: Sat, 12 Jun 2021 15:10:51 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: af2add0e2c - main - Use One Sentence Per Line in the Porter's Handbook Message-ID: <202106121510.15CFAp1G013915@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=af2add0e2cc2a2d92451693f40b7c94192d4937e commit af2add0e2cc2a2d92451693f40b7c94192d4937e Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-06-12 15:10:24 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-06-12 15:10:24 +0000 Use One Sentence Per Line in the Porter's Handbook --- .../en/books/porters-handbook/flavors/_index.adoc | 26 +- .../books/porters-handbook/keeping-up/_index.adoc | 51 +- .../books/porters-handbook/makefiles/_index.adoc | 971 +++++++++++++++------ .../en/books/porters-handbook/new-port/_index.adoc | 12 +- .../en/books/porters-handbook/order/_index.adoc | 52 +- .../books/porters-handbook/pkg-files/_index.adoc | 68 +- .../en/books/porters-handbook/plist/_index.adoc | 200 +++-- .../porters-handbook/porting-dads/_index.adoc | 155 +++- .../porters-handbook/porting-samplem/_index.adoc | 7 +- .../books/porters-handbook/porting-why/_index.adoc | 7 +- .../porters-handbook/quick-porting/_index.adoc | 90 +- .../en/books/porters-handbook/security/_index.adoc | 77 +- .../porters-handbook/slow-porting/_index.adoc | 129 ++- .../en/books/porters-handbook/special/_index.adoc | 626 +++++++++---- .../en/books/porters-handbook/testing/_index.adoc | 251 ++++-- .../books/porters-handbook/upgrading/_index.adoc | 85 +- .../en/books/porters-handbook/uses/_index.adoc | 501 ++++++++--- 17 files changed, 2420 insertions(+), 888 deletions(-) diff --git a/documentation/content/en/books/porters-handbook/flavors/_index.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc index 8499801376..5ac688fdb4 100644 --- a/documentation/content/en/books/porters-handbook/flavors/_index.adoc +++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc @@ -34,7 +34,8 @@ toc::[] [[flavors-intro]] == An Introduction to Flavors -Flavors are a way to have multiple variations of a port. The port is built multiple times, with variations. +Flavors are a way to have multiple variations of a port. +The port is built multiple times, with variations. For example, a port can have a normal version with many features and quite a few dependencies, and a light "lite" version with only basic features and minimal dependencies. @@ -43,7 +44,8 @@ Another example could be, a port can have a GTK flavor and a QT flavor, dependin [[flavors-using]] == Using FLAVORS -To declare a port having multiple flavors, add `FLAVORS` to its [.filename]#Makefile#. The first flavor in `FLAVORS` is the default flavor. +To declare a port having multiple flavors, add `FLAVORS` to its [.filename]#Makefile#. +The first flavor in `FLAVORS` is the default flavor. [TIP] ==== @@ -101,7 +103,8 @@ nox11_PKGNAMESUFFIX= -nox11 .More Complex Flavors Usage [example] ==== -Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>. With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36` +Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>. +With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36` [.programlisting] .... @@ -182,7 +185,8 @@ lite_PKGNAMESUFFIX= -lite [[flavors-auto-php]] == `USES=php` and Flavors -When using crossref:uses[uses-php,`php`] with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, the port will automatically have `FLAVORS` filled in with the PHP versions it supports. +When using crossref:uses[uses-php,`php`] with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, +the port will automatically have `FLAVORS` filled in with the PHP versions it supports. [[flavors-auto-php-ex1]] .Simple `USES=php` Extension @@ -242,13 +246,15 @@ USES= php:flavors [TIP] ==== -When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`. _Never_ use `FLAVOR` directly. +When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`. +_Never_ use `FLAVOR` directly. ==== [[flavors-auto-python]] == `USES=python` and Flavors -When using crossref:uses[uses-python,`python`] and `USE_PYTHON=distutils`, the port will automatically have `FLAVORS` filled in with the Python versions it supports. +When using crossref:uses[uses-python,`python`] and `USE_PYTHON=distutils`, +the port will automatically have `FLAVORS` filled in with the Python versions it supports. [[flavors-auto-python-ex1]] .Simple `USES=python` @@ -312,7 +318,8 @@ USE_PYTHON= distutils allflavors Will get these flavors: `py34`, `py35`, and `py36`. ==== -`PY_FLAVOR` is available to depend on the correct version of Python modules. All dependencies on flavored Python ports should use `PY_FLAVOR`, and not `FLAVOR` directly.. +`PY_FLAVOR` is available to depend on the correct version of Python modules. +All dependencies on flavored Python ports should use `PY_FLAVOR`, and not `FLAVOR` directly.. [[flavors-auto-python-ex3]] .For a Port Not Using `distutils` @@ -332,7 +339,10 @@ USES= python:3.5+ [[flavors-auto-lua]] == `USES=lua` and Flavors -When using crossref:uses[uses-lua,`lua:module`] or crossref:uses[uses-lua,`lua:flavors`], the port will automatically have `FLAVORS` filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use `USES=lua`. +When using crossref:uses[uses-lua,`lua:module`] or crossref:uses[uses-lua,`lua:flavors`], +the port will automatically have `FLAVORS` filled in with the Lua versions it supports. +However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; +most applications that embed or otherwise use Lua should simply use `USES=lua`. `LUA_FLAVOR` is available (and must be used) to depend on the correct version of dependencies regardless of whether the port used the `flavors` or `module` parameters. diff --git a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc index fb5143e781..d998432c5d 100644 --- a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc +++ b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc @@ -31,26 +31,39 @@ include::shared/en/urls.adoc[] toc::[] -The FreeBSD Ports Collection is constantly changing. Here is some information on how to keep up. +The FreeBSD Ports Collection is constantly changing. +Here is some information on how to keep up. [[freshports]] == FreshPorts -One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts]. Multiple ports can be monitored. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made. (These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.) +One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts]. +Multiple ports can be monitored. +Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made. +(These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical. +Also, in some cases, the changes are very minor in nature. +We expect everyone to use their best judgement in these cases.) -To use FreshPorts, an account is required. Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages. Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again. +To use FreshPorts, an account is required. +Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages. +Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again. -FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits. +FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. +If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits. [[cgit]] == The Web Interface to the Source Repository -It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files. +It is possible to browse the files in the source repository by using a web interface. +Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file. +Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file. +However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files. [[ports-mailing-list]] == The FreeBSD Ports Mailing List -As a ports maintainer, consider subscribing to {freebsd-ports}. Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#. +As a ports maintainer, consider subscribing to {freebsd-ports}. +Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#. If the volume of messages on this mailing list is too high, consider following {freebsd-ports-announce} which contains only announcements. @@ -59,16 +72,24 @@ If the volume of messages on this mailing list is too high, consider following { One of the least-publicized strengths of FreeBSD is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. -Individual ports are built unless they are specifically marked with `IGNORE`. Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved. (This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.) +Individual ports are built unless they are specifically marked with `IGNORE`. +Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved. +(This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.) [[distfile-survey]] == Portscout: the FreeBSD Ports Distfile Scanner -The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. Portscout can generate HTML reports and send emails about newly available ports to those who request them. Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed. +The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. +However, as the Internet continually changes, distfiles can quickly go missing. +http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. +Portscout can generate HTML reports and send emails about newly available ports to those who request them. +Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed. -Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date. The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown. +Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date. +The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown. -Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked. A search function on this page allows the user to search for a specific port. +Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked. +A search function on this page allows the user to search for a specific port. Clicking on a port name in the list displays the http://freshports.org[FreshPorts] port information. @@ -77,11 +98,17 @@ Additional documentation is available in the https://github.com/freebsd/portscou [[portsmon]] == The FreeBSD Ports Monitoring System -Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`). This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources. +Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`). +This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. +Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. +In the future, this will be expanded to include the distfile survey, as well as other sources. To get started, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port] search page to find all the information about a port. -This is the only resource available that maps PR entries to portnames. PR submitters do not always include the portname in their Synopsis, although we would prefer that they did. So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors, or if a new port the porter is considering creating has already been submitted. +This is the only resource available that maps PR entries to portnames. +PR submitters do not always include the portname in their Synopsis, although we would prefer that they did. +So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors, +or if a new port the porter is considering creating has already been submitted. [NOTE] ====== diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc index 60c878dbac..269ee28dca 100644 --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -32,16 +32,20 @@ include::shared/en/urls.adoc[] toc::[] -Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a crossref:porting-samplem[porting-samplem,sample Makefile] in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read. +Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. +Also, there is a crossref:porting-samplem[porting-samplem,sample Makefile] in this handbook, +so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read. Consider these problems in sequence during the design of the new [.filename]#Makefile#: [[makefile-source]] == The Original Source -Does it live in `DISTDIR` as a standard ``gzip``ped tarball named something like [.filename]#foozolix-1.2.tar.gz#? If so, go on to the next step. If not, the distribution file format might require overriding one or more of `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX`, or `DISTFILES`. +Does it live in `DISTDIR` as a standard ``gzip``ped tarball named something like [.filename]#foozolix-1.2.tar.gz#? If so, go on to the next step. +If not, the distribution file format might require overriding one or more of `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX`, or `DISTFILES`. -In the worst case, create a custom `do-extract` target to override the default. This is rarely, if ever, necessary. +In the worst case, create a custom `do-extract` target to override the default. +This is rarely, if ever, necessary. [[makefile-naming]] == Naming @@ -51,11 +55,14 @@ The first part of the port's [.filename]#Makefile# names the port, describes its [[makefile-portname]] === `PORTNAME` -Set `PORTNAME` to the base name of the software. It is used as the base for the FreeBSD package, and for <<makefile-distname,`DISTNAME`>>. +Set `PORTNAME` to the base name of the software. +It is used as the base for the FreeBSD package, and for <<makefile-distname,`DISTNAME`>>. [IMPORTANT] ==== -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, and that no other port already has the same `PKGBASE`. If the name has already been used, add either <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>. +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, and that no other port already has the same `PKGBASE`. +If the name has already been used, add either <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>. ==== [[makefile-versions]] @@ -63,7 +70,9 @@ The package name must be unique across the entire ports tree. Make sure that the Set `DISTVERSION` to the version number of the software. -`PORTVERSION` is the version used for the FreeBSD package. It will be automatically derived from `DISTVERSION` to be compatible with FreeBSD's package versioning scheme. If the version contains _letters_, it might be needed to set `PORTVERSION` and not `DISTVERSION`. +`PORTVERSION` is the version used for the FreeBSD package. +It will be automatically derived from `DISTVERSION` to be compatible with FreeBSD's package versioning scheme. +If the version contains _letters_, it might be needed to set `PORTVERSION` and not `DISTVERSION`. [IMPORTANT] ==== @@ -74,8 +83,8 @@ From time to time, some software will use a version scheme that is not compatibl [TIP] ==== - -When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before. See <<makefile-versions-ex-pkg-version>>. +When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before. +See <<makefile-versions-ex-pkg-version>>. ==== [[makefile-versions-ex-pkg-version]] @@ -109,7 +118,8 @@ When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument t [NOTE] **** -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. +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. **** ==== @@ -163,7 +173,8 @@ 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`: +Some of the time, projects using GitHub will use their name in their versions. +For example, the version could be `nekoto-1.2-4`: [.programlisting] .... @@ -236,7 +247,8 @@ 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. man:pkg-version[8] will verify this: +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. +man:pkg-version[8] will verify this: [source,shell] .... @@ -258,9 +270,11 @@ For some more advanced examples of setting `PORTVERSION`, when the software's ve [[makefile-portrevision]] ==== `PORTREVISION` -`PORTREVISION` is a monotonically increasing value which is reset to 0 with 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 `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available. +`PORTREVISION` is a monotonically increasing value which is reset to 0 with 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 `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available. -`PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way. That includes changes that only affect a package built with non-default <<makefile-options,options>>. +`PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way. +That includes changes that only affect a package built with non-default <<makefile-options,options>>. Examples of when `PORTREVISION` must be bumped: @@ -277,22 +291,28 @@ Examples of changes which do not require a `PORTREVISION` bump: * Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package have to go to the trouble of upgrading. * Build fixes which cause a package to become compilable where it was previously failing. As long as the changes do not introduce any functional change on any other platforms on which the port did previously build. Since `PORTREVISION` reflects the content of the package, if the package was not previously buildable then there is no need to increase `PORTREVISION` to mark a change. -A rule of thumb is to decide whether a change committed to a port is something which _some_ people would benefit from having. Either because of an enhancement, fix, or by virtue that the new package will actually work at all. Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, `PORTREVISION` must be bumped. +A rule of thumb is to decide whether a change committed to a port is something which _some_ people would benefit from having. +Either because of an enhancement, fix, or by virtue that the new package will actually work at all. +Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. +If yes, `PORTREVISION` must be bumped. [NOTE] ==== -People using binary packages will _never_ see the update if `PORTREVISION` is not bumped. Without increasing `PORTREVISION`, the package builders have no way to detect the change and thus, will not rebuild the package. +People using binary packages will _never_ see the update if `PORTREVISION` is not bumped. +Without increasing `PORTREVISION`, the package builders have no way to detect the change and thus, will not rebuild the package. ==== [[makefile-portepoch]] ==== `PORTEPOCH` -From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). +From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. +An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). [TIP] ==== - -The results of version number comparisons are not always obvious. `pkg version` (see man:pkg-version[8]) can be used to test the comparison of two version number strings. For example: +The results of version number comparisons are not always obvious. +`pkg version` (see man:pkg-version[8]) can be used to test the comparison of two version number strings. +For example: [source,shell] .... @@ -303,13 +323,21 @@ The results of version number comparisons are not always obvious. `pkg version` The `>` output indicates that version 0.031 is considered greater than version 0.29, which may not have been obvious to the porter. ==== -In situations such as this, `PORTEPOCH` must be increased. If `PORTEPOCH` is nonzero it is appended to the package name as described in section 0 above. `PORTEPOCH` must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail. For example, the package would not be detected as out of date. The new version number, `1.0,1` in the above example, is still numerically less than the previous version, 20000801, but the `,1` suffix is treated specially by automated tools and found to be greater than the implied suffix `,0` on the earlier package. +In situations such as this, `PORTEPOCH` must be increased. +If `PORTEPOCH` is nonzero it is appended to the package name as described in section 0 above. +`PORTEPOCH` must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail. +For example, the package would not be detected as out of date. +The new version number, `1.0,1` in the above example, is still numerically less than the previous version, 20000801, but the `,1` suffix is treated specially by automated tools and found to be greater than the implied suffix `,0` on the earlier package. -Dropping or resetting `PORTEPOCH` incorrectly leads to no end of grief. If the discussion above was not clear enough, please consult the {freebsd-ports}. +Dropping or resetting `PORTEPOCH` incorrectly leads to no end of grief. +If the discussion above was not clear enough, please consult the {freebsd-ports}. -It is expected that `PORTEPOCH` will not be used for the majority of ports, and that sensible use 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 FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made. +It is expected that `PORTEPOCH` will not be used for the majority of ports, and that sensible use 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 FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release. +The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made. -For example, if a snapshot release is made on the date `20000917`, and the previous version of the software was version `1.2`, do not use `20000917` for `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. +For example, if a snapshot release is made on the date `20000917`, and the previous version of the software was version `1.2`, do not use `20000917` for `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. [[makefile-portrevision-example]] ==== Example of `PORTREVISION` and `PORTEPOCH` Usage @@ -324,7 +352,8 @@ DISTVERSION= 0.10 `PKGNAME` becomes `gtkmumble-0.10`. -A security hole is discovered which requires a local FreeBSD patch. `PORTREVISION` is bumped accordingly. +A security hole is discovered which requires a local FreeBSD patch. +`PORTREVISION` is bumped accordingly. [.programlisting] .... @@ -335,7 +364,9 @@ PORTREVISION= 1 `PKGNAME` becomes `gtkmumble-0.10_1` -A new version is released by the vendor, numbered `0.2` (it turns out the author actually intended `0.10` to actually mean `0.1.0`, not "what comes after 0.9" - oops, too late now). Since the new minor version `2` is numerically less than the previous version `10`, `PORTEPOCH` must be bumped to manually force the new package to be detected as "newer". Since it is a new vendor release of the code, `PORTREVISION` is reset to 0 (or removed from the [.filename]#Makefile#). +A new version is released by the vendor, numbered `0.2` (it turns out the author actually intended `0.10` to actually mean `0.1.0`, not "what comes after 0.9" - oops, too late now). +Since the new minor version `2` is numerically less than the previous version `10`, `PORTEPOCH` must be bumped to manually force the new package to be detected as "newer". +Since it is a new vendor release of the code, `PORTREVISION` is reset to 0 (or removed from the [.filename]#Makefile#). [.programlisting] .... @@ -346,7 +377,8 @@ PORTEPOCH= 1 `PKGNAME` becomes `gtkmumble-0.2,1` -The next release is 0.3. Since `PORTEPOCH` never decreases, the version variables are now: +The next release is 0.3. +Since `PORTEPOCH` never decreases, the version variables are now: [.programlisting] .... @@ -359,47 +391,69 @@ PORTEPOCH= 1 [NOTE] ==== -If `PORTEPOCH` were reset to `0` with this upgrade, someone who had installed the `gtkmumble-0.10_1` package would not detect the `gtkmumble-0.3` package as newer, since `3` is still numerically less than `10`. Remember, this is the whole point of `PORTEPOCH` in the first place. +If `PORTEPOCH` were reset to `0` with this upgrade, someone who had installed the `gtkmumble-0.10_1` package would not detect the `gtkmumble-0.3` package as newer, since `3` is still numerically less than `10`. +Remember, this is the whole point of `PORTEPOCH` in the first place. ==== [[porting-pkgnameprefix-suffix]] === `PKGNAMEPREFIX` and `PKGNAMESUFFIX` -Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure this conforms to our <<porting-pkgname,guidelines for a good package name>>. In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed. Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively. Do not make them part of `PORTNAME`. +Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. +Make sure this conforms to our <<porting-pkgname,guidelines for a good package name>>. +In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed. +Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively. +Do not make them part of `PORTNAME`. [[porting-pkgname]] === Package Naming Conventions -These are the conventions to follow when naming packages. This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes! +These are the conventions to follow when naming packages. +This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes! Package names take the form of [.filename]#language_region-name-compiled.specifics-version.numbers#. -The package name is defined as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure to set the variables to conform to that format. +The package name is defined as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. +Make sure to set the variables to conform to that format. [[porting-pkgname-language]] [.filename]#language_region-#:: -FreeBSD strives to support the native language of its users. The _language-_ part is a two letter abbreviation of the natural language defined by ISO-639 when the port is specific to a certain language. Examples are `ja` for Japanese, `ru` for Russian, `vi` for Vietnamese, `zh` for Chinese, `ko` for Korean and `de` for German. +FreeBSD strives to support the native language of its users. +The _language-_ part is a two letter abbreviation of the natural language defined by ISO-639 when the port is specific to a certain language. +Examples are `ja` for Japanese, `ru` for Russian, `vi` for Vietnamese, `zh` for Chinese, `ko` for Korean and `de` for German. + -If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are `en_US` for US English and `fr_CH` for Swiss French. +If the port is specific to a certain region within the language area, add the two letter country code as well. +Examples are `en_US` for US English and `fr_CH` for Swiss French. + The _language-_ part is set in `PKGNAMEPREFIX`. [[porting-pkgname-name]] [.filename]#name#:: -Make sure that the port's name and version are clearly separated and placed into `PORTNAME` and `DISTVERSION`. The only reason for `PORTNAME` to contain a version part is if the upstream distribution is really named that way, as in the package:textproc/libxml2[] or package:japanese/kinput2-freewnn[] ports. Otherwise, `PORTNAME` cannot contain any version-specific information. It is quite normal for several ports to have the same `PORTNAME`, as the package:www/apache*[] ports do; in that case, different versions (and different index entries) are distinguished by `PKGNAMEPREFIX` and `PKGNAMESUFFIX` values. +Make sure that the port's name and version are clearly separated and placed into `PORTNAME` and `DISTVERSION`. +The only reason for `PORTNAME` to contain a version part is if the upstream distribution is really named that way, as in the package:textproc/libxml2[] or package:japanese/kinput2-freewnn[] ports. +Otherwise, `PORTNAME` cannot contain any version-specific information. +It is quite normal for several ports to have the same `PORTNAME`, as the package:www/apache*[] ports do; in that case, different versions (and different index entries) are distinguished by `PKGNAMEPREFIX` and `PKGNAMESUFFIX` values. + -There is a tradition of naming `Perl 5` modules by prepending `p5-` and converting the double-colon separator to a hyphen. For example, the `Data::Dumper` module becomes `p5-Data-Dumper`. +There is a tradition of naming `Perl 5` modules by prepending `p5-` and converting the double-colon separator to a hyphen. +For example, the `Data::Dumper` module becomes `p5-Data-Dumper`. [[porting-pkgname-compiled-specifics]] [.filename]#-compiled.specifics#:: -If the port can be built with different <<makefile-masterdir,hardcoded defaults>> (usually part of the directory name in a family of ports), the _-compiled.specifics_ part states the compiled-in defaults. The hyphen is optional. Examples are paper size and font units. +If the port can be built with different <<makefile-masterdir,hardcoded defaults>> (usually part of the directory name in a family of ports), the _-compiled.specifics_ part states the compiled-in defaults. +The hyphen is optional. +Examples are paper size and font units. + The _-compiled.specifics_ part is set in `PKGNAMESUFFIX`. [[porting-pkgname-version-numbers]] [.filename]#-version.numbers#:: -The version string follows a dash (`-`) and is a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string `pl` (meaning "patchlevel"), which can be used _only_ when there are no major and minor version numbers in the software. If the software version has strings like "alpha", "beta", "rc", or "pre", take the first letter and put it immediately after a period. If the version string continues after those names, the numbers follow the single alphabet without an extra period between them (for example, `1.0b2`). +The version string follows a dash (`-`) and is a period-separated list of integers and single lowercase alphabetics. +In particular, it is not permissible to have another dash inside the version string. +The only exception is the string `pl` (meaning "patchlevel"), which can be used _only_ when there are no major and minor version numbers in the software. +If the software version has strings like "alpha", "beta", "rc", or "pre", take the first letter and put it immediately after a period. +If the version string continues after those names, the numbers follow the single alphabet without an extra period between them (for example, `1.0b2`). + -The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the `d__yyyy.mm.dd__` format, not `_dd.mm.yyyy_` or the non-Y2K compliant `_yy.mm.dd_` format. It is important to prefix the version with a letter, here `d` (for date), in case a release with an actual version number is made, which would be numerically less than `_yyyy_`. +The idea is to make it easier to sort ports by looking at the version string. +In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the `d__yyyy.mm.dd__` format, not `_dd.mm.yyyy_` or the non-Y2K compliant `_yy.mm.dd_` format. +It is important to prefix the version with a letter, here `d` (for date), in case a release with an actual version number is made, which would be numerically less than `_yyyy_`. [IMPORTANT] ==== @@ -524,12 +578,13 @@ Here are some (real) examples on how to convert the name as called by the softwa |Package for 300dpi fonts |=== -If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to `1.0` (like the `piewm` example above). Otherwise, ask the original author or use the date string the source file was released on (`d__yyyy.mm.dd__`, or `d__yyyymmdd__`) as the version. +If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to `1.0` (like the `piewm` example above). +Otherwise, ask the original author or use the date string the source file was released on (`d__yyyy.mm.dd__`, or `d__yyyymmdd__`) as the version. [TIP] ==== - -Use any letter. Here, `d` here stands for date, if the source is a Git repository, `g` followed by the commit date is commonly used, using `s` for snapshot is also common. +Use any letter. +Here, `d` here stands for date, if the source is a Git repository, `g` followed by the commit date is commonly used, using `s` for snapshot is also common. ==== [[makefile-categories]] @@ -538,14 +593,21 @@ Use any letter. Here, `d` here stands for date, if the source is a Git repositor [[makefile-categories-definition]] === `CATEGORIES` -When a package is created, it is put under [.filename]#/usr/ports/packages/All# and links are made from one or more subdirectories of [.filename]#/usr/ports/packages#. The names of these subdirectories are specified by the variable `CATEGORIES`. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the <<porting-categories,current list of categories>> and pick the ones that are suitable for the port. +When a package is created, it is put under [.filename]#/usr/ports/packages/All# and links are made from one or more subdirectories of [.filename]#/usr/ports/packages#. +The names of these subdirectories are specified by the variable `CATEGORIES`. +It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. +Please take a look at the <<porting-categories,current list of categories>> and pick the ones that are suitable for the port. -This list also determines where in the ports tree the port is imported. If there is more than one category here, the port files must be put in the subdirectory with the name of the first category. See <<choosing-categories,below>> for more discussion about how to pick the right categories. +This list also determines where in the ports tree the port is imported. +If there is more than one category here, the port files must be put in the subdirectory with the name of the first category. +See <<choosing-categories,below>> for more discussion about how to pick the right categories. [[porting-categories]] === Current List of Categories -Here is the current list of port categories. Those marked with an asterisk (`*`) are _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree. They are only used as secondary categories, and only for search purposes. +Here is the current list of port categories. +Those marked with an asterisk (`*`) are _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree. +They are only used as secondary categories, and only for search purposes. [NOTE] ==== @@ -947,7 +1009,9 @@ For non-virtual categories, there is a one-line description in `COMMENT` in that [[choosing-categories]] === Choosing the Right Category -As many of the categories overlap, choosing which of the categories will be the primary category of the port can be tedious. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence: +As many of the categories overlap, choosing which of the categories will be the primary category of the port can be tedious. +There are several rules that govern this issue. +Here is the list of priorities, in decreasing order of precedence: * The first category must be a physical category (see <<porting-categories,above>>). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that. * Language specific categories always come first. For example, if the port installs Japanese X11 fonts, then the `CATEGORIES` line would read [.filename]#japanese x11-fonts#. @@ -958,16 +1022,22 @@ As many of the categories overlap, choosing which of the categories will be the * [.filename]#misc# does not appear with any other non-virtual category. If there is `misc` with something else in `CATEGORIES`, that means `misc` can safely be deleted and the port placed only in the other subdirectory. * If the port truly does not belong anywhere else, put it in [.filename]#misc#. -If the category is not clearly defined, please put a comment to that effect in the https://bugs.freebsd.org/submit/[port submission] in the bug database so we can discuss it before we import it. As a committer, send a note to the {freebsd-ports} so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. +If the category is not clearly defined, please put a comment to that effect in the https://bugs.freebsd.org/submit/[port submission] in the bug database so we can discuss it before we import it. +As a committer, send a note to the {freebsd-ports} so we can discuss it first. +Too often, new ports are imported to the wrong category only to be moved right away. [[proposing-categories]] === Proposing a New Category -As the Ports Collection has grown over time, various new categories have been introduced. New categories can either be _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree- or _physical_ categories-those that do. This section discusses the issues involved in creating a new physical category. Read it thouroughly before proposing a new one. +As the Ports Collection has grown over time, various new categories have been introduced. +New categories can either be _virtual_ categories-those that do not have a corresponding subdirectory in the ports tree- or _physical_ categories-those that do. This section discusses the issues involved in creating a new physical category. +Read it thouroughly before proposing a new one. Our existing practice has been to avoid creating a new physical category unless either a large number of ports would logically belong to it, or the ports that would belong to it are a logically distinct group that is of limited general interest (for instance, categories related to spoken human languages), or preferably both. -The rationale for this is that such a change creates a link:{committers-guide}#ports[fair amount of work] for both the committers and also for all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no clear consensus on when a category is "too big", nor whether categories should lend themselves to browsing (and thus what number of categories would be an ideal number), and so forth.) +The rationale for this is that such a change creates a link:{committers-guide}#ports[fair amount of work] for both the committers and also for all users who track changes to the Ports Collection. +In addition, proposed category changes just naturally seem to attract controversy. +(Perhaps this is because there is no clear consensus on when a category is "too big", nor whether categories should lend themselves to browsing (and thus what number of categories would be an ideal number), and so forth.) Here is the procedure: @@ -985,12 +1055,16 @@ Here is the procedure: . Since it affects the ports infrastructure and involves moving and patching many ports but also possibly running regression tests on the build cluster, assign the PR to the {portmgr}. . If that PR is approved, a committer will need to follow the rest of the procedure that is link:{committers-guide}#PORTS[outlined in the Committer's Guide]. -Proposing a new virtual category is similar to the above but much less involved, since no ports will actually have to move. In this case, the only patches to include in the PR would be those to add the new category to `CATEGORIES` of the affected ports. +Proposing a new virtual category is similar to the above but much less involved, since no ports will actually have to move. +In this case, the only patches to include in the PR would be those to add the new category to `CATEGORIES` of the affected ports. [[proposing-reorg]] === Proposing Reorganizing All the Categories -Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. Please read the history of these proposals in the mailing list archives before posting this idea. Furthermore, be prepared to be challenged to offer a working prototype. +Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. +To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. +Please read the history of these proposals in the mailing list archives before posting this idea. +Furthermore, be prepared to be challenged to offer a working prototype. [[makefile-distfiles]] == The Distribution Files @@ -1000,16 +1074,23 @@ The second part of the [.filename]#Makefile# describes the files that must be do [[makefile-distname]] === `DISTNAME` -`DISTNAME` is the name of the port as called by the authors of the software. `DISTNAME` defaults to `${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}`, and if not set, `DISTVERSION` defaults to `${PORTVERSION}` so override `DISTNAME` only if necessary. `DISTNAME` is only used in two places. First, the distribution file list (`DISTFILES`) defaults to `${DISTNAME}${EXTRACT_SUFX}`. Second, the distribution file is expected to extract into a subdirectory named `WRKSRC`, which defaults to [.filename]#work/${DISTNAME}#. +`DISTNAME` is the name of the port as called by the authors of the software. +`DISTNAME` defaults to `${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}`, and if not set, `DISTVERSION` defaults to `${PORTVERSION}` so override `DISTNAME` only if necessary. +`DISTNAME` is only used in two places. +First, the distribution file list (`DISTFILES`) defaults to `${DISTNAME}${EXTRACT_SUFX}`. +Second, the distribution file is expected to extract into a subdirectory named `WRKSRC`, which defaults to [.filename]#work/${DISTNAME}#. -Some vendor's distribution names which do not fit into the `${PORTNAME}-${PORTVERSION}`-scheme can be handled automatically by setting `DISTVERSIONPREFIX`, `DISTVERSION`, and `DISTVERSIONSUFFIX`. `PORTVERSION` will be derived from `DISTVERSION` automatically. +Some vendor's distribution names which do not fit into the `${PORTNAME}-${PORTVERSION}`-scheme can be handled automatically by setting `DISTVERSIONPREFIX`, `DISTVERSION`, and `DISTVERSIONSUFFIX`. +`PORTVERSION` will be derived from `DISTVERSION` automatically. [IMPORTANT] ==== -Only one of `PORTVERSION` and `DISTVERSION` can be set at a time. If `DISTVERSION` does not derive a correct `PORTVERSION`, do not use `DISTVERSION`. +Only one of `PORTVERSION` and `DISTVERSION` can be set at a time. +If `DISTVERSION` does not derive a correct `PORTVERSION`, do not use `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 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. @@ -1017,7 +1098,9 @@ If the upstream version scheme cannot easily be coerced into a ports-compatible .Deriving `PORTVERSION` Manually [example] ==== -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 to output `9.9.9p1`. +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 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]: @@ -1075,7 +1158,8 @@ 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`. +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`. ==== [[makefile-distname-ex3]] @@ -1117,21 +1201,28 @@ DIST_SUBDIR= ${PORTNAME}-${PORTVERSION} [NOTE] ==== -`PKGNAMEPREFIX` and `PKGNAMESUFFIX` do not affect `DISTNAME`. Also note that if `WRKSRC` is equal to [.filename]#${WRKDIR}/${DISTNAME}# while the original source archive is named something other than `${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}`, leave `DISTNAME` alone- defining only `DISTFILES` is easier than both `DISTNAME` and `WRKSRC` (and possibly `EXTRACT_SUFX`). +`PKGNAMEPREFIX` and `PKGNAMESUFFIX` do not affect `DISTNAME`. +Also note that if `WRKSRC` is equal to [.filename]#${WRKDIR}/${DISTNAME}# while the original source archive is named something other than `${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}`, leave `DISTNAME` alone- defining only `DISTFILES` is easier than both `DISTNAME` and `WRKSRC` (and possibly `EXTRACT_SUFX`). ==== [[makefile-master_sites]] === `MASTER_SITES` -Record the directory part of the FTP/HTTP-URL pointing at the original tarball in `MASTER_SITES`. Do not forget the trailing slash ([.filename]#/#)! +Record the directory part of the FTP/HTTP-URL pointing at the original tarball in `MASTER_SITES`. +Do not forget the trailing slash ([.filename]#/#)! The `make` macros will try to use this specification for grabbing the distribution file with `FETCH` if they cannot find it already on the system. -It is recommended that multiple sites are included on this list, preferably from different continents. This will safeguard against wide-area network problems. +It is recommended that multiple sites are included on this list, preferably from different continents. +This will safeguard against wide-area network problems. [IMPORTANT] ==== -`MASTER_SITES` must not be blank. It must point to the actual site hosting the distribution files. It cannot point to web archives, or the FreeBSD distribution files cache sites. The only exception to this rule is ports that do not have any distribution files. For example, meta-ports do not have any distribution files, so `MASTER_SITES` does not need to be set. +`MASTER_SITES` must not be blank. +It must point to the actual site hosting the distribution files. +It cannot point to web archives, or the FreeBSD distribution files cache sites. +The only exception to this rule is ports that do not have any distribution files. +For example, meta-ports do not have any distribution files, so `MASTER_SITES` does not need to be set. ==== [[makefile-master_sites-shorthand]] @@ -1144,7 +1235,8 @@ Shortcut abbreviations are available for popular archives like SourceForge (`SOU MASTER_SITES= GNU/make .... -The older expanded format still works, but all ports have been converted to the compact format. The expanded format looks like this: +The older expanded format still works, but all ports have been converted to the compact format. +The expanded format looks like this: [.programlisting] .... @@ -1152,12 +1244,13 @@ MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make .... -These values and variables are defined in https://cgit.freebsd.org/ports/tree/Mk/bsd.sites.mk[Mk/bsd.sites.mk]. New entries are added often, so make sure to check the latest version of this file before submitting a port. +These values and variables are defined in https://cgit.freebsd.org/ports/tree/Mk/bsd.sites.mk[Mk/bsd.sites.mk]. +New entries are added often, so make sure to check the latest version of this file before submitting a port. [TIP] ==== - -For any `MASTER_SITE_FOO` variable, the shorthand `_FOO_` can be used. For example, use: +For any `MASTER_SITE_FOO` variable, the shorthand `_FOO_` can be used. +For example, use: [.programlisting] .... @@ -1210,14 +1303,17 @@ Some `MASTER_SITE_*` names are quite long, and for ease of use, shortcuts have b [[makefile-master_sites-magic]] ==== Magic MASTER_SITES Macros -Several "magic" macros exist for popular sites with a predictable directory structure. For these, just use the abbreviation and the system will choose a subdirectory automatically. For a port named `Stardict`, of version `1.2.3`, and hosted on SourceForge, adding this line: +Several "magic" macros exist for popular sites with a predictable directory structure. +For these, just use the abbreviation and the system will choose a subdirectory automatically. +For a port named `Stardict`, of version `1.2.3`, and hosted on SourceForge, adding this line: [.programlisting] .... MASTER_SITES= SF .... -infers a subdirectory named `/project/stardict/stardict/1.2.3`. If the inferred directory is incorrect, it can be overridden: +infers a subdirectory named `/project/stardict/stardict/1.2.3`. +If the inferred directory is incorrect, it can be overridden: [.programlisting] .... @@ -1324,7 +1420,9 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} [[makefile-master_sites-github]] === `USE_GITHUB` -If the distribution file comes from a specific commit or tag on https://github.com[GitHub] for which there is no officially released file, there is an easy way to set the right `DISTNAME` and `MASTER_SITES` automatically. These variables are available: +If the distribution file comes from a specific commit or tag on https://github.com[GitHub] for which there is no officially released file, +there is an easy way to set the right `DISTNAME` and `MASTER_SITES` automatically. +These variables are available: [[makefile-master_sites-github-description]] .`USE_GITHUB` Description @@ -1399,7 +1497,6 @@ It will automatically have `MASTER_SITES` set to `GH` and `WRKSRC` to `${WRKDIR} [TIP] **** - `20140411` is the date of the commit referenced in `GH_TAGNAME`, not the date the [.filename]#Makefile# is edited, or the date the commit is made. **** @@ -1409,7 +1506,9 @@ It will automatically have `MASTER_SITES` set to `GH` and `WRKSRC` to `${WRKDIR} .Use of `USE_GITHUB` with `DISTVERSIONPREFIX` [example] ==== -From time to time, `GH_TAGNAME` is a slight variation from `DISTVERSION`. For example, if the version is `1.0.2`, the tag is `v1.0.2`. In those cases, it is possible to use `DISTVERSIONPREFIX` or `DISTVERSIONSUFFIX`: +From time to time, `GH_TAGNAME` is a slight variation from `DISTVERSION`. +For example, if the version is `1.0.2`, the tag is `v1.0.2`. +In those cases, it is possible to use `DISTVERSIONPREFIX` or `DISTVERSIONSUFFIX`: [.programlisting] .... @@ -1427,7 +1526,8 @@ It will automatically set `GH_TAGNAME` to `v1.0.2`, while `WRKSRC` will be kept .Using `USE_GITHUB` When Upstream Does Not Use Versions [example] ==== -If there never was a version upstream, do not invent one like `0.1` or `1.0`. Create the port with a `DISTVERSION` of `g__YYYYMMDD__`, where `g` is for Git, and `_YYYYMMDD_` represents the date the commit referenced in `GH_TAGNAME`. +If there never was a version upstream, do not invent one like `0.1` or `1.0`. +Create the port with a `DISTVERSION` of `g__YYYYMMDD__`, where `g` is for Git, and `_YYYYMMDD_` represents the date the commit referenced in `GH_TAGNAME`. [.programlisting] .... @@ -1453,7 +1553,6 @@ Which means using `PORTEPOCH` will not be needed in case upstream decides to cut .Using `USE_GITHUB` to Access a Commit Between Two Versions [example] ==== - If the current version of the software uses a Git tag, and the port needs to be updated to a newer, intermediate version, without a tag, use man:git-describe[1] to find out the version to use: [source,shell] @@ -1483,7 +1582,8 @@ DISTVERSIONSUFFIX= -gf0038b1 USE_GITHUB= yes .... -This creates a versioning scheme that increases over time (well, over commits), and does not conflict with the creation of a `0.7.4` version. (See <<makefile-versions-ex-pkg-version>> for details on man:pkg-version[8]): +This creates a versioning scheme that increases over time (well, over commits), and does not conflict with the creation of a `0.7.4` version. +(See <<makefile-versions-ex-pkg-version>> for details on man:pkg-version[8]): [source,shell] .... @@ -1495,7 +1595,8 @@ This creates a versioning scheme that increases over time (well, over commits), [NOTE] **** -If the requested commit is the same as a tag, a shorter description is shown by default. The longer version is equivalent: +If the requested commit is the same as a tag, a shorter description is shown by default. +The longer version is equivalent: [source,shell] .... @@ -1513,18 +1614,24 @@ v0.7.3-0-gc66c71d [[makefile-master_sites-github-multiple]] ==== Fetching Multiple Files from GitHub -The `USE_GITHUB` framework also supports fetching multiple distribution files from different places in GitHub. It works in a way very similar to <<porting-master-sites-n>>. +The `USE_GITHUB` framework also supports fetching multiple distribution files from different places in GitHub. +It works in a way very similar to <<porting-master-sites-n>>. -Multiple values are added to `GH_ACCOUNT`, `GH_PROJECT`, and `GH_TAGNAME`. Each different value is assigned a group. The main value can either have no group, or the `:DEFAULT` group. A value can be omitted if it is the same as the default as listed in <<makefile-master_sites-github-description>>. +Multiple values are added to `GH_ACCOUNT`, `GH_PROJECT`, and `GH_TAGNAME`. +Each different value is assigned a group. +The main value can either have no group, or the `:DEFAULT` group. +A value can be omitted if it is the same as the default as listed in <<makefile-master_sites-github-description>>. -`GH_TUPLE` can also be used when there are a lot of distribution files. It helps keep the account, project, tagname, and group information at the same place. +`GH_TUPLE` can also be used when there are a lot of distribution files. +It helps keep the account, project, tagname, and group information at the same place. -For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. +For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. +The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. [CAUTION] ==== - -The `:__group__` part _must_ be used for _only one_ distribution file. It is used as a unique key and using it more than once will overwrite the previous values. +The `:__group__` part _must_ be used for _only one_ distribution file. +It is used as a unique key and using it more than once will overwrite the previous values. ==== [NOTE] @@ -1532,7 +1639,8 @@ The `:__group__` part _must_ be used for _only one_ distribution file. It is use As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in <<porting-master-sites-n>> ==== -When fetching multiple files from GitHub, sometimes the default distribution file is not fetched from GitHub. To disable fetching the default distribution, set: +When fetching multiple files from GitHub, sometimes the default distribution file is not fetched from GitHub. +To disable fetching the default distribution, set: [.programlisting] .... @@ -1554,7 +1662,9 @@ DISTFILES= ${DISTNAME}${EXTRACT_SUFX} .Use of `USE_GITHUB` with Multiple Distribution Files [example] ==== -From time to time, there is a need to fetch more than one distribution file. For example, when the upstream git repository uses submodules. This can be done easily using groups in the `GH_*` variables: +From time to time, there is a need to fetch more than one distribution file. +For example, when the upstream git repository uses submodules. +This can be done easily using groups in the `GH_*` variables: [.programlisting] .... @@ -1570,11 +1680,21 @@ GH_SUBDIR= ext/icons:icons CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... -This will fetch three distribution files from github. The default one comes from [.filename]#foo/foo# and is version `1.0.2`. The second one, with the `icons` group, comes from [.filename]#bar/foo-icons# and is in version `1.0`. The third one comes from [.filename]#bar/foo-contrib# and uses the Git commit `fa579bc`. The distribution files are named [.filename]#foo-foo-1.0.2_GH0.tar.gz#, [.filename]#bar-foo-icons-1.0_GH0.tar.gz#, and [.filename]#bar-foo-contrib-fa579bc_GH0.tar.gz#. +This will fetch three distribution files from github. +The default one comes from [.filename]#foo/foo# and is version `1.0.2`. +The second one, with the `icons` group, comes from [.filename]#bar/foo-icons# and is in version `1.0`. +The third one comes from [.filename]#bar/foo-contrib# and uses the Git commit `fa579bc`. +The distribution files are named [.filename]#foo-foo-1.0.2_GH0.tar.gz#, [.filename]#bar-foo-icons-1.0_GH0.tar.gz#, and [.filename]#bar-foo-contrib-fa579bc_GH0.tar.gz#. -All the distribution files are extracted in `${WRKDIR}` in their respective subdirectories. The default file is still extracted in `${WRKSRC}`, in this case, [.filename]#${WRKDIR}/foo-1.0.2#. Each additional distribution file is extracted in `${WRKSRC_group}`. Here, for the `icons` group, it is called `${WRKSRC_icons}` and it contains [.filename]#${WRKDIR}/foo-icons-1.0#. The file with the `contrib` group is called `${WRKSRC_contrib}` and contains `${WRKDIR}/foo-contrib-fa579bc`. +All the distribution files are extracted in `${WRKDIR}` in their respective subdirectories. +The default file is still extracted in `${WRKSRC}`, in this case, [.filename]#${WRKDIR}/foo-1.0.2#. +Each additional distribution file is extracted in `${WRKSRC_group}`. +Here, for the `icons` group, it is called `${WRKSRC_icons}` and it contains [.filename]#${WRKDIR}/foo-icons-1.0#. +The file with the `contrib` group is called `${WRKSRC_contrib}` and contains `${WRKDIR}/foo-contrib-fa579bc`. -The software's build system expects to find the icons in a [.filename]#ext/icons# subdirectory in its sources, so `GH_SUBDIR` is used. `GH_SUBDIR` makes sure that [.filename]#ext# exists, but that [.filename]#ext/icons# does not already exist. Then it does this: +The software's build system expects to find the icons in a [.filename]#ext/icons# subdirectory in its sources, so `GH_SUBDIR` is used. +`GH_SUBDIR` makes sure that [.filename]#ext# exists, but that [.filename]#ext/icons# does not already exist. +Then it does this: [.programlisting] .... @@ -1603,18 +1723,24 @@ GH_TUPLE= bar:foo-icons:1.0:icons/ext/icons \ CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib} .... -Grouping was used in the previous example with `bar:icons,contrib`. Some redundant information is present with `GH_TUPLE` because grouping is not possible. +Grouping was used in the previous example with `bar:icons,contrib`. +Some redundant information is present with `GH_TUPLE` because grouping is not possible. ==== [[makefile-master_sites-github-submodules]] .How to Use `USE_GITHUB` with Git Submodules? [example] ==== -Ports with GitHub as an upstream repository sometimes use submodules. See man:git-submodule[1] for more information. +Ports with GitHub as an upstream repository sometimes use submodules. +See man:git-submodule[1] for more information. -The problem with submodules is that each is a separate repository. As such, they each must be fetched separately. +The problem with submodules is that each is a separate repository. +As such, they each must be fetched separately. -Using package:finance/moneymanagerex[] as an example, its GitHub repository is https://github.com/moneymanagerex/moneymanagerex[]. It has a https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules[.gitmodules] file at the root. This file describes all the submodules used in this repository, and lists additional repositories needed. This file will tell what additional repositories are needed: +Using package:finance/moneymanagerex[] as an example, its GitHub repository is https://github.com/moneymanagerex/moneymanagerex[]. +It has a https://github.com/moneymanagerex/moneymanagerex/blob/master/.gitmodules[.gitmodules] file at the root. +This file describes all the submodules used in this repository, and lists additional repositories needed. +This file will tell what additional repositories are needed: [.programlisting] .... @@ -1633,7 +1759,8 @@ Using package:finance/moneymanagerex[] as an example, its GitHub repository is h [...] .... -The only information missing from that file is the commit hash or tag to use as a version. This information is found after cloning the repository: +The only information missing from that file is the commit hash or tag to use as a version. +This information is found after cloning the repository: [source,shell] .... @@ -1665,11 +1792,14 @@ Submodule path 'lib/wxsqlite3': checked out 'fb66eb230d8aed21dec273b38c7c054dcb7 [...] .... -It can also be found on GitHub. Each subdirectory that is a submodule is shown as `_directory @ hash_`, for example, `mongoose @ 2140e59`. +It can also be found on GitHub. +Each subdirectory that is a submodule is shown as `_directory @ hash_`, for example, `mongoose @ 2140e59`. [NOTE] **** -While getting the information from GitHub seems more straightforward, the information found using `git submodule status` will provide more meaningful information. For example, here, ``lib/wxsqlite3``'s commit hash `fb66eb2` correspond to `v3.4.0`. Both can be used interchangeably, but when a tag is available, use it. +While getting the information from GitHub seems more straightforward, the information found using `git submodule status` will provide more meaningful information. +For example, here, ``lib/wxsqlite3``'s commit hash `fb66eb2` correspond to `v3.4.0`. +Both can be used interchangeably, but when a tag is available, use it. **** Now that all the required information has been gathered, the [.filename]#Makefile# can be written (only GitHub-related lines are shown): @@ -1768,28 +1898,36 @@ GL_COMMIT= 9c1669ce60c3f4f5eb43df874d7314483fb3f8a6 It will have `MASTER_SITES` set to `"https://gitlab.example.com"` and `WRKSRC` to `${WRKDIR}/bar-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6-9c1669ce60c3f4f5eb43df874d7314483fb3f8a6`. [TIP] +====== `20170906` is the date of the commit referenced in `GL_COMMIT`, not the date the [.filename]#Makefile# is edited, or the date the commit to the FreeBSD ports tree is made. +====== [NOTE] +====== ``GL_SITE``'s protocol, port and webroot can all be modified in the same variable. +====== ==== [[makefile-master_sites-gitlab-multiple]] ==== Fetching Multiple Files from GitLab -The `USE_GITLAB` framework also supports fetching multiple distribution files from different places from GitLab and GitLab hosted sites. It works in a way very similar to <<porting-master-sites-n>> and <<makefile-master_sites-gitlab-multiple>>. +The `USE_GITLAB` framework also supports fetching multiple distribution files from different places from GitLab and GitLab hosted sites. +It works in a way very similar to <<porting-master-sites-n>> and <<makefile-master_sites-gitlab-multiple>>. -Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`. Each different value is assigned a group. <<makefile-master_sites-gitlab-description>>. +Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`. +Each different value is assigned a group. <<makefile-master_sites-gitlab-description>>. -`GL_TUPLE` can also be used when there are a lot of distribution files. It helps keep the site, account, project, commit, and group information at the same place. +`GL_TUPLE` can also be used when there are a lot of distribution files. +It helps keep the site, account, project, commit, and group information at the same place. -For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. +For each group, a `${WRKSRC_group}` helper variable is created, containing the directory into which the file has been extracted. +The `${WRKSRC_group}` variables can be used to move directories around during `post-extract`, or add to `CONFIGURE_ARGS`, or whatever is needed so that the software builds correctly. [CAUTION] ==== - -The `:__group__` part _must_ be used for _only one_ distribution file. It is used as a unique key and using it more than once will overwrite the previous values. +The `:__group__` part _must_ be used for _only one_ distribution file. +It is used as a unique key and using it more than once will overwrite the previous values. ==== [NOTE] @@ -1797,7 +1935,8 @@ The `:__group__` part _must_ be used for _only one_ distribution file. It is use As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in <<porting-master-sites-n>> ==== -When fetching multiple files using GitLab, sometimes the default distribution file is not fetched from a GitLab site. To disable fetching the default distribution, set: +When fetching multiple files using GitLab, sometimes the default distribution file is not fetched from a GitLab site. +To disable fetching the default distribution, set: [.programlisting] .... @@ -1806,7 +1945,8 @@ USE_GITLAB= nodefault [IMPORTANT] ==== -When using `USE_GITLAB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its <<porting-order-portname,top block>>. The definition should be: +When using `USE_GITLAB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its <<porting-order-portname,top block>>. +The definition should be: [.programlisting] *** 6678 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202106121510.15CFAp1G013915>