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 @@ -11,35 +11,34 @@ Configuring the Makefile Configuring the Makefile is pretty - simple, and again we suggest that you look at existing examples + simple, and again we suggest looking at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of - variables and sections in that template to make your port easier + variables and sections in that template to make the port easier for others to read. - Now, consider the following problems in sequence as you - design your new Makefile: + Consider these problems in sequence during the + design of the new Makefile: The Original Source Does it live in DISTDIR as a standard gzipped tarball named something like - foozolix-1.2.tar.gz? If so, you can go on - to the next step. If not, you should look at overriding any of - the DISTVERSION, DISTNAME, + 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 - variables, depending on how alien a format your port's - distribution file is. + EXTRACT_SUFX, or + DISTFILES. - In the worst case, you can simply create your own + In the worst case, create a custom do-extract target to override the - default, though this should be rarely, if ever, - necessary. + default. This is rarely, if ever, necessary. @@ -53,17 +52,17 @@ <varname>PORTNAME</varname> and <varname>PORTVERSION</varname> - You should set PORTNAME to the base - name of your port, and PORTVERSION to the + Set PORTNAME to the base + name of the port, and PORTVERSION to the version number of the port. - - Package name should be unique among all of the ports - tree, check that there is not already a port with the same + + The package name must be unique among all of the ports + tree. Make sure that there is not already a port with the same PORTNAME and if there is add one of PKGNAMEPREFIX or PKGNAMESUFFIX. - + @@ -73,24 +72,24 @@ <varname>PORTREVISION</varname> - The PORTREVISION variable is a + PORTREVISION is a monotonically increasing value which is reset to 0 with - every increase of PORTVERSION (i.e., - every time a new official vendor release is made), and - appended to the package name if non-zero. Changes to + every increase of PORTVERSION, 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 - (e.g., pkg version, see - &man.pkg-version.8;) to highlight the fact that a new - package is available. + like &man.pkg-version.8; to determine that a new package is + available. - PORTREVISION should be increased each + 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 options. Examples of when PORTREVISION - should be bumped: + must be bumped: @@ -107,9 +106,9 @@ Changes in the packing list or the install-time - behavior of the package (e.g., change to a script which - generates initial data for the package, like ssh host - keys). + behavior of the package. For example, a change to a script which + generates initial data for the package, like &man.ssh.1; host + keys. @@ -122,7 +121,7 @@ Silent changes to the port distfile which have - significant functional differences, i.e., changes to the + significant functional differences. For example, changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a @@ -150,30 +149,39 @@ Trivial patches to the distfile such as correction of typos, which are not important enough that users of - the package should go to the trouble 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 + 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 + 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 ask yourself whether a change - committed to a port is something which everyone would - benefit from having (either because of an enhancement, fix, + 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), and weigh that against that fact that it will cause + 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, the - PORTREVISION should be bumped. + compelled to update. If yes, + PORTREVISION must be bumped. + + + 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. + @@ -194,38 +202,38 @@ two version number strings. For example: &prompt.user; pkg version -t 0.031 0.29 -> + > 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, the - PORTEPOCH version should be increased. + 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 (i.e., the package - would not be detected as out of date): the new version - number (e.g., 1.0,1 in the above example) - is still numerically less than the previous version - (20000801), but the ,1 suffix is treated + 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 you do not - understand the above discussion, please keep after it until - you do, or ask questions on the mailing lists. + incorrectly leads to no end of grief. If the discussion + above was not clear enough, please consult the + &a.ports;. It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of PORTVERSION can often preempt it becoming necessary if a future release of the software - should change the version structure. However, care is + changes the version structure. However, care is needed by &os; porters when a vendor release is made without an official version number — such as a code snapshot release. The temptation is to label @@ -234,11 +242,14 @@ 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, the snapshot release should be given a - PORTVERSION of 1.2.20000917 or similar, - not 20000917, so that the succeeding release, say 1.3, is - still a numerically greater value. + 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 + 1.2.20000917, or similar, so that the + succeeding release, say 1.3, is still a + numerically greater value. @@ -250,7 +261,7 @@ collection: PORTNAME= gtkmumble -PORTVERSION= 0.10 + PORTVERSION= 0.10 PKGNAME becomes gtkmumble-0.10. @@ -260,8 +271,8 @@ accordingly. PORTNAME= gtkmumble -PORTVERSION= 0.10 -PORTREVISION= 1 + PORTVERSION= 0.10 + PORTREVISION= 1 PKGNAME becomes gtkmumble-0.10_1 @@ -270,9 +281,9 @@ 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 + 0.9 - oops, too late now). Since the new minor version 2 is numerically less than the - previous version 10, 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 @@ -280,8 +291,8 @@ removed from the Makefile). PORTNAME= gtkmumble -PORTVERSION= 0.2 -PORTEPOCH= 1 + PORTVERSION= 0.2 + PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.2,1 @@ -291,8 +302,8 @@ variables are now: PORTNAME= gtkmumble -PORTVERSION= 0.3 -PORTEPOCH= 1 + PORTVERSION= 0.3 + PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.3,1 @@ -321,9 +332,10 @@ ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good - package name. In particular, you are - not allowed to use a hyphen - (-) in PORTVERSION. + 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 @@ -370,8 +382,7 @@ French. The language- part is - set in the PKGNAMEPREFIX - variable. + set in PKGNAMEPREFIX. @@ -379,34 +390,30 @@ name - The first letter of the name - part should be lowercase. (The rest of the name may - contain capital letters, so use your own discretion when - converting a software name that has some capital letters - in it.) 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. - Make sure that the port's name and version are - clearly separated and placed into the + clearly separated and placed into PORTNAME and - PORTVERSION variables. The only + PORTVERSION. The only reason for PORTNAME to contain a version part is if the upstream distribution is really named that way, as in the - textproc/libxml2 or - japanese/kinput2-freewnn ports. - Otherwise, the PORTNAME should not + textproc/libxml2 or + 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 - www/apache* ports do; in that case, + www/apache* ports do; in that case, different versions (and different index entries) are - distinguished by the PKGNAMEPREFIX + 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. @@ -419,13 +426,12 @@ (usually part of the directory name in a family of ports), the -compiled.specifics part - should state the compiled-in defaults (the hyphen is - optional). Examples are paper size and font + states the compiled-in defaults. The hyphen is + optional. Examples are paper size and font units. The -compiled.specifics - part is set in the PKGNAMESUFFIX - variable. + part is set in PKGNAMESUFFIX. @@ -446,9 +452,9 @@ 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 should follow + continues after those names, the numbers follow the single alphabet without an extra period between - them. + 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 @@ -461,26 +467,28 @@ yy.mm.dd format. It is important to prefix the version with 0.0. in case a release with an actual - version number is made, which would of course be + version number is made, which would be numerically less than yyyy. - + Package name must be unique among all of the ports tree, check that there is not already a port with the same PORTNAME and if there is add one of PKGNAMEPREFIX or PKGNAMESUFFIX. - + Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name: - + + Package Naming Examples + @@ -504,6 +512,15 @@ + mule-1.0.1 + (empty) + mule + 1 + 1.0.1 + mule already exists + + + EmiClock-1.0.2 (empty) emiclock @@ -608,14 +625,15 @@ - +
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 + original author or use the date string the source file was + released on (0.0.yyyy.mm.dd) as the version. @@ -637,12 +655,12 @@ packages on the FTP site or the CDROM. Please take a look at the current list of categories and pick the ones that are suitable for - your port. + the port. This list also determines where in the ports tree the port - is imported. If you put more than one category here, it is - assumed that the port files will be put in the subdirectory - with the name in the first category. See + 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 below for more discussion about how to pick the right categories. @@ -658,8 +676,8 @@ purposes. - For non-virtual categories, you will find a one-line - description in the COMMENT in that + For non-virtual categories, there is a one-line + description in COMMENT in that subdirectory's Makefile. @@ -740,7 +758,7 @@ comms Communication software. - Mostly software to talk to your serial + Mostly software to talk to the serial port. @@ -767,9 +785,9 @@ devel Development utilities. Do not put libraries here just because they are - libraries—unless they truly do not belong - anywhere else, they should not be in this - category. + libraries. They should not be + in this category unless they truly do not belong + anywhere else. @@ -788,8 +806,10 @@ editors General editors. Specialized editors go in the section for those - tools (e.g., a mathematical-formula editor will go - in math). + tools. For example, a mathematical-formula editor will + go in math, and have + editors as a second + category. @@ -802,7 +822,7 @@ emulators Emulators for other operating systems. Terminal emulators do not - belong here—X-based ones should go to + belong here. X-based ones go to x11 and text-based ones to either comms or misc, depending on the exact @@ -824,8 +844,8 @@ ftp - FTP client and server utilities. - If your port speaks both FTP and HTTP, put it + FTP client and server utilities. + If the port speaks both FTP and HTTP, put it in ftp with a secondary category of www. @@ -984,10 +1004,10 @@ misc Miscellaneous utilities - Basically things that do not belong anywhere + Things that do not belong anywhere else. If at all possible, try to find a better - category for your port than misc, - as ports tend to get overlooked in here. + category for the port than misc, + as ports tend to be overlooked in here. @@ -1212,7 +1232,7 @@ The X Window System and friends. This category is only for software that directly supports the window system. Do not put regular X - applications here; most of them should go into other + applications here. Most of them go into other x11-* categories (see below). @@ -1288,9 +1308,9 @@ Choosing the Right Category - As many of the categories overlap, you often have to - choose which of the categories should be the primary category - of your port. There are several rules that govern this issue. + 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: @@ -1305,16 +1325,16 @@ Language specific categories always come first. For - example, if your port installs Japanese X11 fonts, then - your CATEGORIES line would read + example, if the port installs Japanese X11 fonts, then + the CATEGORIES line would read japanese x11-fonts. Specific categories are listed before less-specific - ones. For instance, an HTML editor should be listed as + ones. For instance, an HTML editor is listed as www editors, not the other way - around. Also, you should not list + around. Also, do not list net when the port belongs to any of irc, mail, news, security, @@ -1325,49 +1345,50 @@ x11 is used as a secondary category only when the primary category is a natural - language. In particular, you should not put + language. In particular, do not put x11 in the category line for X applications. - Emacs modes should be + Emacs modes are placed in the same ports category as the application supported by the mode, not in editors. For example, an Emacs mode to edit source files - of some programming language should go into + of some programming language goes into lang. - Ports which install loadable kernel modules should + Ports installing loadable kernel modules also have the virtual category kld in their CATEGORIES line. This is one of the things handled automatically by adding - kmod to the USES - line. + USES=kmod. - misc should not appear with any - other non-virtual category. If you have - misc with something else in your - CATEGORIES line, that means you can - safely delete misc and just put the - port in that other subdirectory! + 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 your port truly does not belong anywhere else, + If the port truly does not belong anywhere else, put it in misc. - If you are not sure about the category, please put a - comment to that effect in your &man.send-pr.1; submission so - we can discuss it before we import it. If you are a - committer, send a note to the &a.ports; so we can discuss it + If the category is not clearly defined, please put a + comment to that effect in the port + submission in the bug database so + we can discuss it before we import it. As a committer, + send a note to the &a.ports; so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. This causes unnecessary and undesirable bloat in the master source repository. @@ -1381,9 +1402,9 @@ virtual categories—those that do not have a corresponding subdirectory in the ports tree— or physical categories—those that - do. The following text discusses the issues involved in - creating a new physical category so that you can understand - them before you propose one. + 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 @@ -1407,15 +1428,15 @@ - Propose the new category on &a.ports;. You should - include a detailed rationale for the new category, - including why you feel the existing categories are not + Propose the new category on &a.ports;. Include + a detailed rationale for the new category, + including why the existing categories are not sufficient, and the list of existing ports proposed to move. (If there are new ports pending in - GNATS that would fit this + Bugzilla that would fit this category, list them too.) If you are the maintainer and/or submitter, respectively, mention that as it may - help you to make your case. + help the case. @@ -1423,10 +1444,10 @@ - If it seems that there is support for your idea, file + If it seems that there is support for the idea, file a PR which includes both the rationale and the list of existing ports that need to be moved. Ideally, this PR - should also include patches for the following: + would also include these patches: @@ -1450,7 +1471,7 @@ - (for extra credit, you can include the other files + (for extra credit, include the other files that have to change, as per the procedure in the Committer's Guide.) @@ -1459,9 +1480,9 @@ Since it affects the ports infrastructure and involves - not only performing repo-copies but also possibly running - regression tests on the build cluster, the PR should be - assigned to the &a.portmgr;. + moving and patching many ports but also possibly running + regression tests on the build cluster, assign the PR to + the &a.portmgr;. @@ -1472,10 +1493,10 @@ - Proposing a new virtual category should be similar to the + 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 the + the PR would be those to add the new category to CATEGORIES of the affected ports. @@ -1489,8 +1510,8 @@ 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 you post this idea; - furthermore, you should be prepared to be challenged to offer + the mailing list archives before posting this idea. + Furthermore, be prepared to be challenged to offer a working prototype. @@ -1499,8 +1520,8 @@ The Distribution Files The second part of the Makefile - describes the files that must be downloaded in order to build - the port, and where they can be downloaded from. + describes the files that must be downloaded to build + the port, and where they can be downloaded. <varname>DISTVERSION/DISTNAME</varname> @@ -1528,9 +1549,9 @@ Only one of PORTVERSION and - DISTVERSION can be set at a time. If you - set DISTVERSION and the derived - PORTVERSION is not right, do not use + DISTVERSION can be set at a time. If + DISTVERSION does not derive a correct + PORTVERSION, do not use DISTVERSION, set PORTVERSION to the right value and set DISTNAME with PORTNAME @@ -1539,11 +1560,11 @@ version. - The following table lists some examples of - DISTVERSION and the derived - PORTVERSION: - + + Examples of <varname>DISTVERSION</varname> and the + Derived <varname>PORTVERSION</varname> + @@ -1574,19 +1595,19 @@ - +
PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. Also note that if WRKSRC is equal to - work/${DISTNAME} while + ${WRKDIR}/${DISTNAME} while the original source archive is named something other than ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}, - you should probably leave DISTNAME - alone— you are better off defining - DISTFILES than having to set both + leave DISTNAME + alone— defining only + DISTFILES is easier than both DISTNAME and WRKSRC (and possibly EXTRACT_SUFX). @@ -1604,7 +1625,7 @@ FETCH if they cannot find it already on the system. - It is recommended that you put multiple sites on this + It is recommended that multiple sites are included on this list, preferably from different continents. This will safeguard against wide-area network problems. We are even planning to add support for automatically determining the @@ -1612,20 +1633,20 @@ sites will go a long way towards helping this effort. If the original tarball is part of one of the popular - archives such as SourceForge, GNU, or Perl CPAN, you may be - able refer to those sites in an easy compact form using - predefined macros (e.g., SF, - GNU or CPAN). Simply - set MASTER_SITES to one of these values. + archives such as SourceForge, GNU, or Perl CPAN, it may be + possible refer to those sites in an easy compact form using + predefined macros (for example, SF, + GNU or CPAN). + Set MASTER_SITES to one of these values. Here is an example: MASTER_SITES= GNU/make - Or you can use the older expanded format, though there - really are no reason to do so: + The older expanded format can still be used, although there + really is no reason to do so: MASTER_SITES= ${MASTER_SITE_GNU} -MASTER_SITE_SUBDIR= make + MASTER_SITE_SUBDIR= make These values and variables are defined in /usr/ports/Mk/bsd.sites.mk. There are @@ -1635,7 +1656,7 @@ Several magic macros exist for popular sites with a predictable directory structure. For these, just use the abbreviation and the system will try to - guess the correct subdirectory for you. + guess the correct subdirectory automatically. MASTER_SITES= SF @@ -1647,7 +1668,7 @@ This can also be written as MASTER_SITES= SF -MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} + MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} Popular Magic <varname>MASTER_SITES</varname> @@ -1828,11 +1849,11 @@ this (slightly stripped for the example):</para> <programlisting>PORTNAME= pkg -PORTVERSION= 1.2.7 + PORTVERSION= 1.2.7 -USE_GITHUB= yes -GH_ACCOUNT= freebsd -GH_COMMIT= f53e577</programlisting> + USE_GITHUB= yes + GH_ACCOUNT= freebsd + GH_COMMIT= f53e577</programlisting> <para>It will automatically have <varname>MASTER_SITES</varname> set to <literal>GH @@ -1852,13 +1873,13 @@ this (slightly stripped for the example):</para> <programlisting>PORTNAME= pkg-devel -PORTVERSION= 1.3.0.a.20140411 + PORTVERSION= 1.3.0.a.20140411 -USE_GITHUB= yes -GH_ACCOUNT= freebsd -GH_PROJECT= pkg -GH_TAGNAME= ${GH_COMMIT} -GH_COMMIT= 6dbb17b</programlisting> + USE_GITHUB= yes + GH_ACCOUNT= freebsd + GH_PROJECT= pkg + GH_TAGNAME= ${GH_COMMIT} + GH_COMMIT= 6dbb17b</programlisting> <para>It will automatically have <varname>MASTER_SITES</varname> set to <literal>GH @@ -1872,16 +1893,16 @@ <sect2 xml:id="makefile-extract_sufx"> <title><varname>EXTRACT_SUFX</varname> - If you have one distribution file, and it uses an odd + If there is one distribution file, and it uses an odd suffix to indicate the compression mechanism, set EXTRACT_SUFX. For example, if the distribution file was named foo.tar.gzip instead of the more normal - foo.tar.gz, you would write: + foo.tar.gz, write:DISTNAME= foo -EXTRACT_SUFX= .tar.gzip + EXTRACT_SUFX= .tar.gzipThe USES=tar[:xxx], @@ -1893,9 +1914,8 @@ .tar.gz. - You never need to set both - EXTRACT_SUFX and - DISTFILES. + As EXTRACT_SUFX is only used in + DISTFILES, only set one of them.. @@ -1929,11 +1949,11 @@ EXTRACT_ONLY.DISTFILES= source.tar.gz manual.html -EXTRACT_ONLY= source.tar.gz + EXTRACT_ONLY= source.tar.gz - If none of the - DISTFILES should be uncompressed then set - EXTRACT_ONLY to the empty string. + When none of the DISTFILES need to be + uncompressed, set EXTRACT_ONLY to the empty + string.EXTRACT_ONLY= @@ -1941,14 +1961,14 @@ <varname>PATCHFILES</varname> - If your port requires some additional patches that are - available by FTP or HTTP, set PATCHFILES to + If the port requires some additional patches that are + available by FTP or HTTP, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES). If the patch is not relative to the top of the source tree - (i.e., WRKSRC) because it contains some + (that is, WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra foozolix-1.0/ in front of the @@ -1961,16 +1981,16 @@ .bz2 or .xz. If the patch is distributed with some other files, such as - documentation, in a gzipped tarball, you - cannot just use PATCHFILES. If that is the + documentation, in a gzipped tarball, using + PATCHFILES is not possible. If that is the case, add the name and the location of the patch tarball to DISTFILES and - MASTER_SITES. Then, use the - EXTRA_PATCHES variable to point to those + MASTER_SITES. Then, use + EXTRA_PATCHES to point to those files and bsd.port.mk will automatically - apply them for you. In particular, do - not copy patch files into the - PATCHDIR directory—that directory may + apply them. In particular, do + not copy patch files into + ${PATCHDIR}. That directory may not be writable. @@ -1982,7 +2002,7 @@ This does not conflict with the master site grouping - feature, the following also works: + feature, adding a group also works: PATCHFILES= patch2:-p1:source2 @@ -1991,9 +2011,9 @@ The tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular gzipped or - compressed tarball. If you do the - latter, take extra care not to overwrite something that - already exists in that directory. Also, do not forget to + compressed tarball. Take extra care not + to overwrite something that already exists in that + directory if extracting it manually. Also, do not forget to add a command to remove the copied patch in the pre-clean target. @@ -2014,8 +2034,8 @@ mechanism as MASTER_SITES:n. A little background first. OpenBSD has a neat feature - inside the DISTFILES and - PATCHFILES variables which allows files and + inside DISTFILES and + PATCHFILES which allows files and patches to be postfixed with :n identifiers. Here, n can be both [0-9] and denote a group designation. For @@ -2055,13 +2075,13 @@ Simplified Information - This section tells you how to quickly prepare fine + This section explains how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories. We describe here a case of simplified MASTER_SITES:n usage. - This will be sufficient for most scenarios. However, if you - need further information, you will have to refer to the next - section. + This will be sufficient for most scenarios. More detailed + information are available in . Some applications consist of multiple distribution files that must be downloaded from a number of different sites. @@ -2076,8 +2096,8 @@ DISTFILES may be followed by a colon and a tag name. Each site listed in MASTER_SITES is then followed by a colon, - and the tag that indicates which distribution files should - be downloaded from this site. + and the tag that indicates which distribution files are + downloaded from this site. For example, consider an application with the source split in two parts, source1.tar.gz and @@ -2093,15 +2113,15 @@ with One File Per Site MASTER_SITES= ftp://ftp.example1.com/:source1 \ - ftp://ftp.example2.com/:source2 -DISTFILES= source1.tar.gz:source1 \ - source2.tar.gz:source2 + ftp://ftp.example2.com/:source2 + DISTFILES= source1.tar.gz:source1 \ + source2.tar.gz:source2 Multiple distribution files can have the same tag. Continuing the previous example, suppose that there was a third distfile, source3.tar.gz, that - should be downloaded from + is downloaded from ftp.example2.com. The Makefile would then be written like MASTER_SITES= ftp://ftp.example1.com/:source1 \ - ftp://ftp.example2.com/:source2 -DISTFILES= source1.tar.gz:source1 \ - source2.tar.gz:source2 \ - source3.tar.gz:source2 + ftp://ftp.example2.com/:source2 + DISTFILES= source1.tar.gz:source1 \ + source2.tar.gz:source2 \ + source3.tar.gz:source2 Detailed Information - Okay, so the previous section example did not reflect - your needs? In this section we will explain in detail how + Okay, so the previous example did not reflect the new + port's needs? In this section we will explain in detail how the fine grained fetching mechanism - MASTER_SITES:n works and how you can - modify your ports to use it. + MASTER_SITES:n works and how it can + be used. Elements can be postfixed with :n where n is - [^:,]+, i.e., + [^:,]+, that is, n could conceptually be any alphanumeric string but we will limit it to [a-zA-Z_][0-9a-zA-Z_]+ for now. - Moreover, string matching is case sensitive; i.e., + Moreover, string matching is case sensitive; that is, n is different from N. - However, the following words cannot be used for + However, these words cannot be used for postfixing purposes since they yield special meaning: default, all and ALL (they are used internally in @@ -2164,16 +2184,16 @@ - Elements without a postfix are groupless, i.e., they + Elements without a postfix are groupless, they all belong to the special group - DEFAULT. If you postfix any elements - with DEFAULT, you are just being - redundant unless you want to have an element belonging + DEFAULT. Any elements postfixed + with DEFAULT, is just being + redundant unless an element belongs to both DEFAULT and other groups at the same time (check item ). - The following examples are equivalent but the first + These examples are equivalent but the first one is preferred: MASTER_SITES= alpha @@ -2185,13 +2205,12 @@ Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or - none at all. Repeated elements within the same group - will be simply that, repeated elements. + none at all. - When you want an element to belong to several groups - at the same time, you can use the comma operator + When an element belongs to several groups + at the same time, use the comma operator (,). Instead of repeating it several times, each time @@ -2201,7 +2220,7 @@ to group m, n and o. - All the following examples are equivalent but the + All these examples are equivalent but the last one is preferred: MASTER_SITES= alpha alpha:SOME_SITE @@ -2222,13 +2241,13 @@ - Group semantics can be used in any of the following + Group semantics can be used in any of the variables MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR, PATCH_SITE_SUBDIR, DISTFILES, and - PATCHFILES according to the following + PATCHFILES according to this syntax: @@ -2295,19 +2314,19 @@ Multiple Subdirectories MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \ - http://site3/:group3 http://site4/:group4 \ - http://site5/:group5 http://site6/:group6 \ - http://site7/:DEFAULT,group6 \ - http://site8/%SUBDIR%/:group6,group7 \ - http://site9/:group8 -DISTFILES= file1 file2:DEFAULT file3:group3 \ - file4:group4,group5,group6 file5:grouping \ - file6:group7 -MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ - directory-one/:group6,DEFAULT \ - directory + http://site3/:group3 http://site4/:group4 \ + http://site5/:group5 http://site6/:group6 \ + http://site7/:DEFAULT,group6 \ + http://site8/%SUBDIR%/:group6,group7 \ + http://site9/:group8 + DISTFILES= file1 file2:DEFAULT file3:group3 \ + file4:group4,group5,group6 file5:grouping \ + file6:group7 + MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ + directory-one/:group6,DEFAULT \ + directory - The previous example results in the following + The previous example results in this fine grained fetching. Sites are listed in the exact order they will be used. @@ -2478,7 +2497,7 @@ How do I group one of the special variables from - bsd.sites.mk, e.g., + bsd.sites.mk, for example, MASTER_SITE_SOURCEFORGE? See MASTER_SITE_SOURCEFORGE MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} -DISTFILES= something.tar.gz:sourceforge + DISTFILES= something.tar.gz:sourceforge something.tar.gz will be @@ -2502,12 +2521,11 @@ How do I use this with - PATCH* - variables? + PATCH*? All examples were done with MASTER* - variables but they work exactly the same for + but they work exactly the same for PATCH* ones as can be seen in . @@ -2520,7 +2538,7 @@ PATCH_SITES PATCH_SITES= http://site1/ http://site2/:test -PATCHFILES= patch1:test + PATCHFILES= patch1:test @@ -2650,30 +2668,30 @@ <varname>DIST_SUBDIR</varname> - Do not let your port clutter - /usr/ports/distfiles. If your port + Do not let the port clutter + /usr/ports/distfiles. If the port requires a lot of files to be fetched, or contains a file that - has a name that might conflict with other ports (e.g., + has a name that might conflict with other ports (for example, Makefile), set DIST_SUBDIR to the name of the port (${PORTNAME} or - ${PKGNAMEPREFIX}${PORTNAME} should work + ${PKGNAMEPREFIX}${PORTNAME} are fine). This will change DISTDIR from the default /usr/ports/distfiles to /usr/ports/distfiles/DIST_SUBDIR, and in - effect puts everything that is required for your port into + effect puts everything that is required for the port into that subdirectory. It will also look at the subdirectory with the same name on the backup master site at ftp.FreeBSD.org. (Setting - DISTDIR explicitly in your - Makefile will not accomplish this, so + DISTDIR explicitly in + Makefile will not accomplish this, so please use DIST_SUBDIR.) - This does not affect the - MASTER_SITES you define in your + This does not affect + MASTER_SITES defined in the Makefile. @@ -2681,9 +2699,9 @@ <varname>ALWAYS_KEEP_DISTFILES</varname> - If your port uses binary distfiles and has a license that + If the port uses binary distfiles and has a license that requires that the source code is provided with packages - distributed in binary form, e.g., GPL, + distributed in binary form, like GPL, ALWAYS_KEEP_DISTFILES will instruct the &os; build cluster to keep a copy of the files specified in DISTFILES. Users of these ports will @@ -2698,13 +2716,13 @@ ALWAYS_KEEP_DISTFILES .if defined(PACKAGE_BUILDING) -DISTFILES+= foo.tar.gz -ALWAYS_KEEP_DISTFILES= yes -.endif + DISTFILES+= foo.tar.gz + ALWAYS_KEEP_DISTFILES= yes + .endif When adding extra files to DISTFILES, - make sure you also add them to distinfo. + make sure to also add them to distinfo. Also, the additional files will normally be extracted into WRKDIR as well, which for some ports may lead to undesirable side effects and require special @@ -2809,7 +2827,7 @@ <varname>COMMENT</varname> This is a one-line description of the port. Please respect - the following rules: + these rules: @@ -2825,12 +2843,12 @@ - The comment should begin with a capital and end without + The comment must begin with a capital and end without a period; - Do not start with an indefinite article (i.e., A or + Do not start with an indefinite article (that is, A or An); @@ -2840,8 +2858,8 @@ - For lists of words, use the Oxford comma (e.g., green, - red, and blue); + For lists of words, use the Oxford comma (for example, + green, red, and blue); @@ -2853,7 +2871,7 @@ COMMENT= Cat chasing a mouse all over the screen - The COMMENT variable should immediately follow the + The COMMENT variable immediately follows the MAINTAINER variable in the Makefile. @@ -2864,16 +2882,16 @@ distfile check utility for the &os; Ports Collection, described in detail in . - The PORTSCOUT variable defines special + PORTSCOUT defines special conditions within which the Portscout - distfile scanner should be restricted. + distfile scanner is restricted. - Situations where the PORTSCOUT variable - should be set include: + Situations where PORTSCOUT + is set include: - When distfiles should be ignored, whether for specific + When distfiles have to be ignored, whether for specific versions, or specific minor revisions. For example, to exclude version 8.2 from distfile version checks because it is known to be broken, add: @@ -2883,8 +2901,8 @@ When specific versions or specific major and minor - revisions of a distfile should be checked. For example, if - only version 0.6.4 should be + revisions of a distfile must be checked. For example, if + only version 0.6.4 must be monitored because newer versions have compatibility issues with &os;, add: @@ -2930,7 +2948,7 @@ will check for a shared jpeg library with any version, and descend into the graphics/jpeg - subdirectory of your ports tree to build and install it if it + subdirectory of the ports tree to build and install it if it is not found. The dependency is checked twice, once from within the @@ -2962,21 +2980,21 @@ For example, RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \ - xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr + xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr will check if the file or directory /usr/local/news/bin/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will also see if an executable called xmlcatmgr - is in the search path, and descend into the - textproc/xmlcatmgr subdirectory of your - ports tree to build and install it if it is not found. + is in the search path, and descend into + textproc/xmlcatmgr + to build and install it if it is not found. In this case, innd is actually an executable; if an executable is in a place that is not - expected to be in the search path, you should use the full + expected to be in the search path, use the full pathname. @@ -3010,14 +3028,14 @@ BUILD_DEPENDS. This happens because of &man.make.1;'s lazy evaluation of variable assignment. Consider a Makefile with - USE_* variables, + USE_*, which are processed by ports/Mk/bsd.*.mk to augment initial build dependencies. For example, USES= gmake adds devel/gmake to BUILD_DEPENDS. To prevent such additional dependencies from polluting RUN_DEPENDS, - take care to assign with expansion, i.e., expand the value + take care to assign with expansion, that is, expand the value before assigning it to the variable: RUN_DEPENDS:= ${BUILD_DEPENDS} @@ -3036,7 +3054,7 @@ will check for an executable called unzip, and descend into the - archivers/unzip subdirectory of your + archivers/unzip subdirectory of the ports tree to build and install it if it is not found. @@ -3060,7 +3078,7 @@ will check for an executable called ncftp2, and descend into the - net/ncftp2 subdirectory of your ports + net/ncftp2 subdirectory of the ports tree to build and install it if it is not found. The dependency is checked from within the @@ -3081,7 +3099,7 @@ will check for an executable called unzip, and descend into the - archivers/unzip subdirectory of your + archivers/unzip subdirectory of the ports tree to build and install it if it is not found. The dependency is checked from within the @@ -3110,7 +3128,7 @@ PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract will descend into the java/jfc - subdirectory of your ports tree to extract it. + subdirectory of the ports tree to extract it. The dependency is checked from within the patch target. The @@ -3164,9 +3182,7 @@
- The - <varname>USE_<replaceable>*</replaceable></varname> - Variables + <varname>USE_<replaceable>*</replaceable></varname> @@ -3193,9 +3209,9 @@ required version can be specified as 4.6+. The GCC from the base system is used when it satisfies the requested version, - otherwise an appropriate compiler in built from the - port, and the CC and - CXX variables are adjusted + otherwise an appropriate compiler is built from the + port, and CC and + CXX are adjusted accordingly. @@ -3203,7 +3219,7 @@
Variables related to gmake and - the configure script are described in + configure are described in , while autoconf, automake and @@ -3233,8 +3249,8 @@ A minimal version of a dependency can be specified in any *_DEPENDS - variable except LIB_DEPENDS using the - following syntax: + except LIB_DEPENDS using this + syntax: p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy @@ -3252,16 +3268,16 @@ DEPENDS_TARGET. It defaults to install. This is a user variable; it is never defined in a port's Makefile. If - your port needs a special way to handle a dependency, use the - :target part of the + the port needs a special way to handle a dependency, use the + :target part of *_DEPENDS - variables instead of redefining + instead of redefining DEPENDS_TARGET. - When you type make clean, its - dependencies are automatically cleaned too. If you do not - wish this to happen, define the variable - NOCLEANDEPENDS in your environment. This + When running make clean, the port + dependencies are automatically cleaned too. If this is not + desirable, define + NOCLEANDEPENDS in the environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla. @@ -3269,9 +3285,9 @@ To depend on another port unconditionally, use the variable ${NONEXISTENT} as the first field of BUILD_DEPENDS or - RUN_DEPENDS. Use this only when you need - to get the source of the other port. You can often save - compilation time by specifying the target too. For + RUN_DEPENDS. Use this only when + the source of the other port is needed. Compilation time can + be saved by specifying the target too. For instance BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract @@ -3289,14 +3305,14 @@ The ports building technology does not tolerate circular - dependencies. If you introduce one, you will have someone, - somewhere in the world, whose &os; installation will break + dependencies. If one is introduced, someone, somewhere in the + world, will have their &os; installation broken almost immediately, with many others quickly to follow. These - can really be hard to detect; if in doubt, before you make - that change, make sure you have done the following: + can really be hard to detect. If in doubt, before making + that change, make sure to run: cd /usr/ports; make index. That process - can be quite slow on older machines, but you may be able to - save a large number of people—including yourself— + can be quite slow on older machines, but it may be able to + save a large number of people, including yourself, a lot of grief in the process. @@ -3315,9 +3331,9 @@ .include <bsd.port.pre.mk> -.if exists(${LOCALBASE}/bin/foo) -LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar -.endif + .if exists(${LOCALBASE}/bin/foo) + LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar + .endif The problem with trying to automatically add dependencies @@ -3334,9 +3350,9 @@ Correct Declaration of an Optional Dependency OPTIONS_DEFINE= BAR -BAR_DESC= Calling cellphones via bar + BAR_DESC= Calling cellphones via bar -BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar + BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar Testing option variables is the correct method. It will @@ -3348,38 +3364,38 @@ - <varname>USE_</varname> and - <varname>WANT_</varname> + <varname>USE_<replaceable>*</replaceable></varname> and + <varname>WANT_<replaceable>*</replaceable></varname> - USE_ variables are set by the port + USE_* are set by the port maintainer to define software on which this port depends. A port that needs Firefox would set USE_FIREFOX= yes - Some USE_ variables can accept version + Some USE_* can accept version numbers or other parameters. For example, a port that requires Apache 2.2 would set USE_APACHE= 22 For more control over dependencies in some cases, - WANT_ variables are available to more + WANT_* are available to more precisely specify what is needed. For example, consider the mail/squirrelmail port. This - port needs some PHP modules, which are listed in the - USE_PHP variable: + port needs some PHP modules, which are listed in + USE_PHP: USE_PHP= session mhash gettext mbstring pcre openssl xml Those modules may be available in CLI or web versions, so - the web version is selected with a - WANT_ variable: + the web version is selected with + WANT_*: WANT_PHP_WEB= yes - Available USE_ and - WANT_ variables are defined in the files in + Available USE_* and + WANT_* are defined in the files in /usr/ports/Mk. @@ -3387,14 +3403,14 @@ <varname>MASTERDIR</varname> - If your port needs to build slightly different versions of + If the port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try - to share as many files as possible between ports. Typically you - only need a very short Makefile in all but - one of the directories if you use variables cleverly. In the - sole Makefile, you can use + to share as many files as possible between ports. Typically, by + using variables cleverly, only a very short + Makefile is needed in all but one of the + directories. In the sole Makefile, use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX @@ -3404,21 +3420,21 @@ of japanese/xdvi300/Makefile; PORTNAME= xdvi -PORTVERSION= 17 -PKGNAMEPREFIX= ja- -PKGNAMESUFFIX= ${RESOLUTION} - : -# default -RESOLUTION?= 300 -.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ - ${RESOLUTION} != 300 && ${RESOLUTION} != 400 - @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" - @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400." - @${FALSE} -.endif + PORTVERSION= 17 + PKGNAMEPREFIX= ja- + PKGNAMESUFFIX= ${RESOLUTION} + : + # default + RESOLUTION?= 300 + .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ + ${RESOLUTION} != 300 && ${RESOLUTION} != 400 + @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" + @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400." + @${FALSE} + .endif japanese/xdvi300 also has all - the regular patches, package files, etc. If you type + the regular patches, package files, etc. Running make there, it will take the default value for the resolution (300) and build the port normally. @@ -3427,12 +3443,12 @@ xdvi118/Makefile: RESOLUTION= 118 -MASTERDIR= ${.CURDIR}/../xdvi300 + MASTERDIR= ${.CURDIR}/../xdvi300 -.include "${MASTERDIR}/Makefile" + .include "${MASTERDIR}/Makefile" (xdvi240/Makefile and - xdvi400/Makefile are similar). The + xdvi400/Makefile are similar). MASTERDIR definition tells bsd.port.mk that the regular set of subdirectories like FILESDIR and @@ -3447,25 +3463,25 @@ Man Pages - If your port anchors its man tree somewhere other than - PREFIX, you can use + If the port anchors its man tree somewhere other than + PREFIX, use MANDIRS to specify those directories. Note - that the files corresponding to manual pages should be placed in + that the files corresponding to manual pages must be be placed in pkg-plist along with the rest of the files. The purpose of MANDIRS is to enable automatic - compression of manual pages, therefore the file names should be + compression of manual pages, therefore the file names are suffixed with .gz. Info Files - If your package needs to install GNU info files, they should - be listed in the INFO variable (without the + If the package needs to install GNU info files, list them + in INFO (without the trailing .info), one entry per document. These files are assumed to be installed to - PREFIX/INFO_PATH. You can change - INFO_PATH if your package uses a different + PREFIX/INFO_PATH. Change + INFO_PATH if the package uses a different location. However, this is not recommended. These entries contain just the path relative to PREFIX/INFO_PATH. For example, @@ -3499,21 +3515,26 @@ Background - The OPTIONS_* variables give the + OPTIONS_* give the user installing the port a dialog showing the available options, and then saves those options to - /var/db/ports/${UNIQUENAME}/options. + ${PORT_DBDIR}/${OPTIONS_NAME}/options. The next time the port is built, the options are - reused. + reused. PORT_DBDIR defaults to + /var/db/ports. + OPTIONS_NAME is to the port origin with + an underscore as the space separator, for example, for + dns/bind99 it will be + dns_bind99. When the user runs make config (or runs make build for the first time), the framework checks for - /var/db/ports/${UNIQUENAME}/options. + ${PORT_DBDIR}/${OPTIONS_NAME}/options. If that file does not exist, the values of - OPTIONS_* are used, and a dialog box is + OPTIONS_* are used, and a dialog box is displayed where the options can be enabled or disabled. - Then the options file is saved and the + Then options is saved and the configured variables are used when building the port. If a new version of the port adds new @@ -3539,21 +3560,21 @@ described (optional, but strongly recommended): OPT1_DESC= Describe OPT1 -OPT2_DESC= Describe OPT2 -OPT3_DESC= Describe OPT3 -OPT4_DESC= Describe OPT4 -OPT5_DESC= Describe OPT5 -OPT6_DESC= Describe OPT6 + OPT2_DESC= Describe OPT2 + OPT3_DESC= Describe OPT3 + OPT4_DESC= Describe OPT4 + OPT5_DESC= Describe OPT5 + OPT6_DESC= Describe OPT6 ports/Mk/bsd.options.desc.mk has descriptions for many common OPTIONS. - While often useful, they should be overridden if the + While often useful, override them if the description is insufficient for the port. When describing options, view it from the perspective of the user: What functionality does it - change? + change? and Why would I want to enable this? Do not just repeat the name. For example, describing the NLS option as @@ -3564,22 +3585,22 @@ helpful. - - Option names should always be in all uppercase. They - should not use mixed case or lowercase. - + + Option names are always in all uppercase. They + cannot use mixed case or lowercase. + OPTIONS can be grouped as radio choices, where only one choice from each group is allowed: OPTIONS_SINGLE= SG1 -OPTIONS_SINGLE_SG1= OPT3 OPT4 - + OPTIONS_SINGLE_SG1= OPT3 OPT4 + There must be one of each OPTIONS_SINGLE group selected at all - time for the options to be valid. One option of each + times for the options to be valid. One option of each group must be added to OPTIONS_DEFAULT. @@ -3614,8 +3635,8 @@ OPTIONS definitions must appear before the inclusion of - bsd.port.options.mk. The - PORT_OPTIONS variable can only be tested + bsd.port.options.mk. + PORT_OPTIONS values can only be tested after the inclusion of bsd.port.options.mk. Inclusion of bsd.port.pre.mk can be used instead, @@ -3623,7 +3644,7 @@ introduction of bsd.port.options.mk. But be aware that some variables will not work as expected after the inclusion of bsd.port.pre.mk, - typically some USE_* flags. + typically some USE_* flags. Simple Use of <varname>OPTIONS</varname> @@ -3649,9 +3670,10 @@ CONFIGURE_ARGS+=--without-examples .endif - Though, you should use the following so that the - configure knob is really enabled and disabled when the - option is. + The form shown above is discouraged. The preferred + method is using a configure knob to really enable and + disable the feature to match the option: + # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples @@ -3695,7 +3717,7 @@ Default Options - The following options are always on by default. + These options are always on by default. @@ -3733,8 +3755,8 @@ When using a GNU configure script, keep an eye on which optional features are activated by auto-detection. Explicitly - disable optional features you do not wish to be used by - passing respective --without-xxx or + disable optional features that are not needed by + adding --without-xxx or --disable-xxx in CONFIGURE_ARGS. @@ -3767,8 +3789,8 @@ Under some circumstances, the shorthand conditional - syntax can cause problems with complex constructs. If you - receive errors such as + syntax can cause problems with complex constructs. The + errors are usually Malformed conditional, an alternative syntax can be used. @@ -3828,7 +3850,7 @@ OPT_USE the corresponding USE_KEY - variable will be set to value. + will be set to value. If value has spaces in it, replace them with commas, they will be changed back to spaces during processing. For example: @@ -4020,7 +4042,7 @@ Dependencies - For any of the following dependency type: + For any of these dependency types: @@ -4107,7 +4129,7 @@ Generic Variables Replacement - For any of the following variables: + For any of these variables: @@ -4210,7 +4232,7 @@ values set after the options are processed. - With the following lines in the + With these lines in the Makefile: ALL_TARGET= all @@ -4292,11 +4314,11 @@ Specifying the Working Directory - Each port is extracted in to a working directory, which must - be writable. The ports system defaults to having the + Each port is extracted into a working directory, which must + be writable. The ports system defaults to having DISTFILES unpack in to a directory called - ${DISTNAME}. In other words, if you have - set: + ${DISTNAME}. In other words, if the + Makefile has: PORTNAME= foo PORTVERSION= 1.0 @@ -4305,7 +4327,7 @@ directory, foo-1.0, and the rest of the files are located under that directory. - There are a number of variables you can override if that is + A number of variables can overriden if that is not the case. @@ -4315,7 +4337,7 @@ created when the application's distfiles are extracted. If our previous example extracted into a directory called foo (and not - foo-1.0) you would write: + foo-1.0) write: WRKSRC= ${WRKDIR}/foo @@ -4327,8 +4349,8 @@ <varname>NO_WRKSUBDIR</varname> - If the port does not extract in to a subdirectory at all - then you should set NO_WRKSUBDIR to + If the port does not extract in to a subdirectory at all, + then set NO_WRKSUBDIR to indicate that. NO_WRKSUBDIR= yes @@ -4350,54 +4372,53 @@ When removing one of several conflicting ports, it is - advisable to retain the CONFLICTS entries in + advisable to retain CONFLICTS in those other ports for a few months to cater for users who only update once in a while. <varname>CONFLICTS_INSTALL</varname> - If your package cannot coexist with other packages + If the package cannot coexist with other packages (because of file conflicts, runtime incompatibilities, etc.), - list the other package names in the - CONFLICTS_INSTALL variable. You can use + list the other package names in + CONFLICTS_INSTALL. Use shell globs like * and ? - here. Package names should be enumerated the same way they - appear in /var/db/pkg. Please make sure + here. Enumerate package names in there, not port names or + origins. Please make sure that CONFLICTS_INSTALL does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer - work. The CONFLICTS_INSTALL check is done after the build + work. CONFLICTS_INSTALL check is done after the build stage and prior to the install stage. <varname>CONFLICTS_BUILD</varname> - If your port cannot be built if a certain port is already - installed, list the other port names in the - CONFLICTS_BUILD variable. You can use + If the port cannot be built when other specific ports are already + installed, list the other port names in + CONFLICTS_BUILD. Use shell globs like * and ? - here. Package names should be enumerated the same way they - appear in /var/db/pkg. The - CONFLICTS_BUILD check is done prior to the build stage. Build + here. Use package names, not port names or origins. + CONFLICTS_BUILD check is done prior to the build stage. Build conflicts are not recorded in the resulting package. <varname>CONFLICTS</varname> - If your port cannot be built if a certain port is already + If the port cannot be built if a certain port is already installed and the resulting package cannot coexist with the - other package, list the other package name in the - CONFLICTS variable. You can use shell + other package, list the other package name in + CONFLICTS. use shell globs like * and ? here. - Packages names should be enumerated the same way they appear - in /var/db/pkg. Please make sure that - CONFLICTS_INSTALL does not match this + Enumerate package names in there, not port names or + origins. Please make sure that + CONFLICTS does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer - work. The CONFLICTS check is done prior to the build stage + work. CONFLICTS check is done prior to the build stage and prior to the install stage. @@ -4406,7 +4427,7 @@ Installing Files - <varname>INSTALL_*</varname> Macros + <varname>INSTALL_<replaceable>*</replaceable></varname> Macros Use the macros provided in bsd.port.mk to ensure correct modes of @@ -4457,7 +4478,7 @@ - These are basically the install + These are the install command with all the appropriate flags. @@ -4471,17 +4492,17 @@ Stripping Binaries and Shared Libraries - Do not strip binaries manually unless you have to. All - binaries should be stripped, but the + Installed binaries should be stripped. Do not strip + binaries manually unless forced to. The INSTALL_PROGRAM macro will install and strip a binary at the same time (see the next section). The INSTALL_LIB macro does the same thing to shared libraries. - If you need to strip a file, but wish to use neither + When a file must be stripped, but neither INSTALL_PROGRAM nor - INSTALL_LIB macros, - ${STRIP_CMD} will strip your program or + INSTALL_LIB macros are desirable, + ${STRIP_CMD} will strip the program or shared library. This is typically done within the post-install target. For example: @@ -4532,9 +4553,9 @@ ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} (cd ${WRKSRC}/examples && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR}) - This example will install the contents of + This example will install the contents of the examples directory in the vendor distfile - to the proper examples location of your port. + to the proper examples location of the port. post-install: ${MKDIR} ${STAGEDIR}${DATADIR}/summer @@ -4545,10 +4566,10 @@ DATADIR. Additional find arguments can be - passed via the third argument to the - COPYTREE_* macros. For example, to install + passed via the third argument to + COPYTREE_* macros. For example, to install all files from the first example except Makefiles, one can use - the following command. + these commands. post-install: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} @@ -4568,18 +4589,18 @@ Install Additional Documentation - If your software has some documentation other than the - standard man and info pages that you think is useful for the - user, install it under PREFIX/share/doc. + If the software has some documentation other than the + standard man and info pages that is useful for the + user, install it under DOCSDIR This can be done, like the previous item, in the post-install target. - Create a new directory for your port. The directory name - should reflect what the port is. This usually means - PORTNAME. However, if you think the user + Create a new directory for the port. The directory name + is DOCSDIR. This usually equals + PORTNAME. However, if the user might want different versions of the port to be installed at - the same time, you can use the whole - PKGNAME. + the same time, the whole + PKGNAME can be used. Since only the files listed in pkg-plist are installed, it is safe to @@ -4648,7 +4669,7 @@ here.) All conditionally installed documentation files and - directories should be included in + directories are included in pkg-plist with the %%PORTDOCS%% prefix, for example: @@ -4661,8 +4682,8 @@ PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a - port that utilizes PORTDOCS and uses a - non-default location for its documentation should set + port that utilizes PORTDOCS, and uses a + non-default location for its documentation, must set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained @@ -4702,8 +4723,8 @@ incorrect. Also, many ports put everything except binaries, header files and manual pages in a subdirectory of lib, which does not work well with the - BSD paradigm. Many of the files should be moved to one of the - following: etc (setup/configuration + BSD paradigm. Many of the files must be moved to one of these + directories: etc (setup/configuration files), libexec (executables started internally), sbin (executables for superusers/managers), info (documentation