From owner-svn-doc-head@FreeBSD.ORG Wed Apr 8 11:41:19 2015 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 78B8D886; Wed, 8 Apr 2015 11:41:19 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 625F6984; Wed, 8 Apr 2015 11:41:19 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t38BfJQW065889; Wed, 8 Apr 2015 11:41:19 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t38BfJuW065888; Wed, 8 Apr 2015 11:41:19 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201504081141.t38BfJuW065888@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Wed, 8 Apr 2015 11:41:19 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r46502 - head/en_US.ISO8859-1/books/porters-handbook/makefiles X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 08 Apr 2015 11:41:19 -0000 Author: mat Date: Wed Apr 8 11:41:18 2015 New Revision: 46502 URL: https://svnweb.freebsd.org/changeset/doc/46502 Log: Reindent/rewrap chapter. Differential Revision: https://reviews.freebsd.org/D2217 Approved by: wblock (mentor) Sponsored by: Absolight Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Wed Apr 8 09:16:56 2015 (r46501) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Wed Apr 8 11:41:18 2015 (r46502) @@ -58,8 +58,9 @@ 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 PORTNAME and if there is add one of + PKGNAMEPREFIX or PKGNAMESUFFIX. @@ -106,9 +107,9 @@ Changes in the packing list or the install-time - behavior of the package. For example, a change to a script which - generates initial data for the package, like &man.ssh.1; 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. @@ -121,8 +122,8 @@ Silent changes to the port distfile which have - significant functional differences. For example, changes to the - distfile requiring a correction to + significant functional differences. For example, + changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a diff -ru of the old and new versions @@ -166,8 +167,9 @@ 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, + 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 @@ -177,7 +179,7 @@ People using binary packages will never see the update if - PORTREVISION is not bumped. Without + PORTREVISION is not bumped. Without increasing PORTREVISION, the package builders have no way to detect the change and thus, will not rebuild the package. @@ -215,13 +217,13 @@ 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 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 @@ -242,8 +244,8 @@ 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, and the previous version of the + software was version 1.2, do not use 20000917 for PORTVERSION. The correct way is a PORTVERSION of @@ -398,14 +400,15 @@ PORTEPOCH= 1 version part is if the upstream distribution is really named that way, as in the textproc/libxml2 or - japanese/kinput2-freewnn ports. - Otherwise, PORTNAME cannot + 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, - different versions (and different index entries) are - distinguished by PKGNAMEPREFIX + 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 @@ -806,8 +809,8 @@ PORTEPOCH= 1 editors General editors. Specialized editors go in the section for those - tools. For example, a mathematical-formula editor will - go in math, and have + tools. For example, a mathematical-formula editor + will go in math, and have editors as a second category. @@ -844,8 +847,10 @@ PORTEPOCH= 1 ftp - FTP client and server utilities. - If the 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. @@ -1648,186 +1653,186 @@ PORTEPOCH= 1 MASTER_SITE_* Variables - Shortcut abbreviations are available for popular archives - like SourceForge (SF), GNU - (GNU), or Perl CPAN - (CPAN). MASTER_SITES can - use them directly: - - MASTER_SITES= GNU/make - - The older expanded format still works, but all ports - should be converted to the compact format. The expanded - format looks like this: + Shortcut abbreviations are available for popular + archives like SourceForge (SF), GNU + (GNU), or Perl CPAN + (CPAN). MASTER_SITES + can use them directly: + + MASTER_SITES= GNU/make + + The older expanded format still works, but all ports + should be converted to the compact format. The expanded + format looks like this: - MASTER_SITES= ${MASTER_SITE_GNU} + MASTER_SITES= ${MASTER_SITE_GNU} MASTER_SITE_SUBDIR= make - These values and variables are defined in 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 Mk/bsd.sites.mk. + New entries are added often, so make sure to check the + latest version of this file before submitting a port. - - 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: - MASTER_SITES= FOO + MASTER_SITES= FOO - If MASTER_SITE_SUBDIR is needed, use - this: + If MASTER_SITE_SUBDIR is needed, + use this: - MASTER_SITES= FOO/bar - + MASTER_SITES= FOO/bar + 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 try to - guess the correct 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 try to + guess the correct subdirectory automatically. For a port + named Stardict, of version + 1.2.3, and hosted on SourceForge, adding + this line: - MASTER_SITES= SF + MASTER_SITES= SF - Will infer a subdirectory named - /project/stardict/stardict/1.2.3. If the - guess is incorrect, it can be overridden as follows. + Will infer a subdirectory named + /project/stardict/stardict/1.2.3. If the + guess is incorrect, it can be overridden as follows. - MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION} + MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION} - This can also be written as + This can also be written as - MASTER_SITES= SF + MASTER_SITES= SF MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION} - - Popular Magic <varname>MASTER_SITES</varname> - Macros +
+ Popular Magic <varname>MASTER_SITES</varname> + Macros - - - - Macro - Assumed subdirectory - - + + + + Macro + Assumed subdirectory + + - - - APACHE_JAKARTA - ${PORTNAME:S,-,/,}/source - + + + APACHE_JAKARTA + ${PORTNAME:S,-,/,}/source + - - BERLIOS - ${PORTNAME:tl}.berlios - + + BERLIOS + ${PORTNAME:tl}.berlios + - - CHEESESHOP - source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/} - + + CHEESESHOP + source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/} + - - DEBIAN - pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME} - + + DEBIAN + pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME} + - - FARSIGHT - ${PORTNAME} - + + FARSIGHT + ${PORTNAME} + - - GCC - releases/${DISTNAME} - + + GCC + releases/${DISTNAME} + - - GH - ${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/ - + + GH + ${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/ + - - GHC - ${GH_ACCOUNT}/${GH_PROJECT}/ - + + GHC + ${GH_ACCOUNT}/${GH_PROJECT}/ + - - GHL - ${GH_ACCOUNT}/${GH_PROJECT}/legacy.tar.gz/${GH_TAGNAME}?dummy=/ - + + GHL + ${GH_ACCOUNT}/${GH_PROJECT}/legacy.tar.gz/${GH_TAGNAME}?dummy=/ + - - GNOME - sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/} - + + GNOME + sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/} + - - GIMP - ${PORTNAME}/${PORTVERSION:R}/ - + + GIMP + ${PORTNAME}/${PORTVERSION:R}/ + - - GNU - ${PORTNAME} - + + GNU + ${PORTNAME} + - - GNU_ALPHA - ${PORTNAME} - + + GNU_ALPHA + ${PORTNAME} + - - HORDE - ${PORTNAME} - + + HORDE + ${PORTNAME} + - - LODEV - ${PORTNAME} - + + LODEV + ${PORTNAME} + - - MATE - ${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/} - + + MATE + ${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/} + - - MOZDEV - ${PORTNAME:tl} - + + MOZDEV + ${PORTNAME:tl} + - - NL - ${PORTNAME} - + + NL + ${PORTNAME} + - - CPAN - ${PORTNAME:C/-.*//} - + + CPAN + ${PORTNAME:C/-.*//} + - - SAVANNAH - ${PORTNAME:tl} - + + SAVANNAH + ${PORTNAME:tl} + - - SF - ${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION} - - - -
+ + SF + ${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION} + + + + @@ -2025,7 +2030,8 @@ EXTRACT_ONLY= source.tar.gzPATCHFILES If the port requires some additional patches that are - available by FTP or HTTP, set PATCHFILES to + 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). @@ -2224,8 +2230,8 @@ DISTFILES= source1.tar.gz:source1 \ [a-zA-Z_][0-9a-zA-Z_]+ for now. - Moreover, string matching is case sensitive; that is, - n is different from + Moreover, string matching is case sensitive; that + is, n is different from N. However, these words cannot be used for @@ -3373,7 +3379,7 @@ xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr 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 making - that change, make sure to run: + that change, make sure to run: cd /usr/ports; make index. That process can be quite slow on older machines, but it may be able to save a large number of people, including yourself, @@ -3431,22 +3437,23 @@ BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/f <varname>USE_<replaceable>*</replaceable></varname> and <varname>WANT_<replaceable>*</replaceable></varname> - USE_* are set by the port - maintainer to define software on which this port depends. A - port that needs Firefox would set + 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_* can accept version - numbers or other parameters. For example, a port that - requires Apache 2.2 would set + 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_* are available to more - precisely specify what is needed. For example, consider the - mail/squirrelmail port. This + 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 USE_PHP: @@ -3458,8 +3465,10 @@ BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/f WANT_PHP_WEB= yes - Available USE_* and - WANT_* are defined in the files in + Available + USE_* and + WANT_* are + defined in the files in /usr/ports/Mk. @@ -3540,8 +3549,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 Info Files - If the package needs to install GNU info files, list them - in INFO (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. Change @@ -3579,12 +3588,12 @@ MASTERDIR= ${.CURDIR}/../xdvi300 Background - OPTIONS_* give the - user installing the port a dialog showing the available - options, and then saves those options to + OPTIONS_* + give the user installing the port a dialog showing the + available options, and then saves those options to ${PORT_DBDIR}/${OPTIONS_NAME}/options. The next time the port is built, the options are - reused. PORT_DBDIR defaults to + 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 @@ -3596,7 +3605,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 framework checks for ${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 options is saved and the configured variables are used when building the port. @@ -3708,7 +3718,9 @@ OPTIONS_GROUP_GG1= OPT9 OPT10bsd.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> @@ -3734,7 +3746,7 @@ BAR_RUN_DEPENDS= bar:${PORTSDIR}/bar/bar CONFIGURE_ARGS+=--without-examples .endif - The form shown above is discouraged. The preferred + 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: @@ -3974,12 +3986,13 @@ USE_XORG= x11 xextproto xext xrandr OPT_CONFIGURE_ENABLE then --enable-entry - is appended to CONFIGURE_ARGS. When option - OPT is not selected, + is appended to CONFIGURE_ARGS. When + option OPT is not selected, --disable-entry - is appended to CONFIGURE_ARGS. An optional - argument can be specified with an = - symbol. This argument is only appended to the + is appended to CONFIGURE_ARGS. An + optional argument can be specified with an + = symbol. This argument is only appended + to the --enable-entry configure option. For example: @@ -4014,12 +4027,13 @@ CONFIGURE_ARGS+= --disable-test2 OPT_CONFIGURE_ENABLE then --with-entry - is appended to CONFIGURE_ARGS. When option - OPT is not selected, + is appended to CONFIGURE_ARGS. When + option OPT is not selected, --without-entry - is appended to CONFIGURE_ARGS. An optional - argument can be specified with an = - symbol. This argument is only appended to the + is appended to CONFIGURE_ARGS. An + optional argument can be specified with an + = symbol. This argument is only appended + to the --with-entry configure option. For example: @@ -4529,20 +4543,21 @@ PORTVERSION= 1.0 that CONFLICTS_INSTALL does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer - work. CONFLICTS_INSTALL check is done after the build - stage and prior to the install stage. + work. CONFLICTS_INSTALL check is done + after the build stage and prior to the install stage. <varname>CONFLICTS_BUILD</varname> - If the port cannot be built when other specific ports are already - installed, list the other port names in + 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. 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. + CONFLICTS_BUILD check is done prior to the + build stage. Build conflicts are not recorded in the + resulting package. @@ -4558,8 +4573,8 @@ PORTVERSION= 1.0 CONFLICTS does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer - work. CONFLICTS check is done prior to the build stage - and prior to the install stage. + work. CONFLICTS check is done prior to the + build stage and prior to the install stage. @@ -4567,7 +4582,8 @@ PORTVERSION= 1.0 Installing Files - <varname>INSTALL_<replaceable>*</replaceable></varname> Macros + <varname>INSTALL_<replaceable>*</replaceable></varname> + Macros Use the macros provided in bsd.port.mk to ensure correct modes of @@ -4707,7 +4723,8 @@ PORTVERSION= 1.0 Additional find arguments can be passed via the third argument to - COPYTREE_* macros. For example, to install + COPYTREE_* + macros. For example, to install all files from the first example except Makefiles, one can use these commands.