From owner-svn-doc-all@freebsd.org Wed Aug 2 12:19:41 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id DFCF1DCF4CD; Wed, 2 Aug 2017 12:19:41 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::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 8F17C2FEE; Wed, 2 Aug 2017 12:19:41 +0000 (UTC) (envelope-from mat@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v72CJe6b010178; Wed, 2 Aug 2017 12:19:40 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v72CJeOg010172; Wed, 2 Aug 2017 12:19:40 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201708021219.v72CJeOg010172@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Wed, 2 Aug 2017 12:19:40 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50619 - in head/en_US.ISO8859-1/books/porters-handbook: . order porting-samplem X-SVN-Group: doc-head X-SVN-Commit-Author: mat X-SVN-Commit-Paths: in head/en_US.ISO8859-1/books/porters-handbook: . order porting-samplem X-SVN-Commit-Revision: 50619 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 02 Aug 2017 12:19:42 -0000 Author: mat Date: Wed Aug 2 12:19:40 2017 New Revision: 50619 URL: https://svnweb.freebsd.org/changeset/doc/50619 Log: Extract the "Order of Variables in Port Makefiles" into its own chapter. Translators, the only changed things are the xml:id's. Sponsored by: Absolight, The FreeBSD Foundation Added: head/en_US.ISO8859-1/books/porters-handbook/order/ head/en_US.ISO8859-1/books/porters-handbook/order/Makefile (contents, props changed) head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile head/en_US.ISO8859-1/books/porters-handbook/book.xml head/en_US.ISO8859-1/books/porters-handbook/chapters.ent head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/Makefile Wed Aug 2 09:55:07 2017 (r50618) +++ head/en_US.ISO8859-1/books/porters-handbook/Makefile Wed Aug 2 12:19:40 2017 (r50619) @@ -33,6 +33,7 @@ SRCS+= upgrading/chapter.xml SRCS+= security/chapter.xml SRCS+= porting-dads/chapter.xml SRCS+= porting-samplem/chapter.xml +SRCS+= order/chapter.xml SRCS+= keeping-up/chapter.xml SRCS+= uses/chapter.xml SRCS+= versions/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Wed Aug 2 09:55:07 2017 (r50618) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Wed Aug 2 12:19:40 2017 (r50619) @@ -77,6 +77,7 @@ &chap.security; &chap.porting-dads; &chap.porting-samplem; + &chap.order; &chap.keeping-up; &chap.uses; &chap.versions; Modified: head/en_US.ISO8859-1/books/porters-handbook/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/chapters.ent Wed Aug 2 09:55:07 2017 (r50618) +++ head/en_US.ISO8859-1/books/porters-handbook/chapters.ent Wed Aug 2 12:19:40 2017 (r50619) @@ -23,6 +23,7 @@ + Added: head/en_US.ISO8859-1/books/porters-handbook/order/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/order/Makefile Wed Aug 2 12:19:40 2017 (r50619) @@ -0,0 +1,15 @@ +# +# Build the Porters Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= order/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" Added: head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml Wed Aug 2 12:19:40 2017 (r50619) @@ -0,0 +1,460 @@ + + + + + + Order of Variables in Port Makefiles + + The first sections of the Makefile + must always come in the same order. This standard makes it so + everyone can easily read any port without having to search for + variables in a random order. + + The first line of a Makefile is always + a comment containing the Subversion + version control ID, followed by an empty line. In new ports, it + looks like this: + + # $FreeBSD$ +  + + In existing ports, Subversion + has expanded it to look like this: + + # $FreeBSD: head/ports-mgmt/pkg/Makefile 437007 2017-03-26 21:25:47Z bapt $ +  + + + The sections and variables described here are mandatory in + a ordinary port. In a slave port, many sections variables and + can be skipped. + + + + Each following block must be separated from the previous + block by a single blank line. + + In the following blocks, only set the variables that are + required by the port. Define these variables in the order + they are shown here. + + + + <varname>PORTNAME</varname> Block + + This block is the most important. It defines the port + name, version, distribution file location, and category. The + variables must be in this order: + + + + PORTNAME + + + + PORTVERSION + + + + DISTVERSIONPREFIX + + + + DISTVERSION + + + + DISTVERSIONSUFFIX + + + + PORTREVISION + + + + PORTEPOCH + + + + CATEGORIES + + + + MASTER_SITES + + + + MASTER_SITE_SUBDIR + (deprecated) + + + + PKGNAMEPREFIX + + + + PKGNAMESUFFIX + + + + DISTNAME + + + + EXTRACT_SUFX + + + + DISTFILES + + + + DIST_SUBDIR + + + + EXTRACT_ONLY + + + + + Only one of PORTVERSION and + DISTVERSION can be used. + + + + + <varname>PATCHFILES</varname> Block + + This block is optional. The variables are: + + + + PATCH_SITES + + + + PATCHFILES + + + + PATCH_DIST_STRIP + + + + + + <varname>MAINTAINER</varname> Block + + This block is mandatory. The variables are: + + + + MAINTAINER + + + + COMMENT + + + + + + <varname>LICENSE</varname> Block + + This block is optional, although it is highly recommended. + The variables are: + + + + LICENSE + + + + LICENSE_COMB + + + + LICENSE_GROUPS + or + LICENSE_GROUPS_NAME + + + + LICENSE_NAME + or + LICENSE_NAME_NAME + + + + LICENSE_TEXT + or + LICENSE_TEXT_NAME + + + + LICENSE_FILE + or + LICENSE_FILE_NAME + + + + LICENSE_PERMS + or + LICENSE_PERMS_NAME + + + + LICENSE_DISTFILES + or + LICENSE_DISTFILES_NAME + + + + If there are multiple licenses, sort the different + LICENSE_VAR_NAME + variables by license name. + + + + Generic + <varname>BROKEN</varname>/<varname>IGNORE</varname>/<varname>DEPRECATED</varname> + Messages + + This block is optional. The variables are: + + + + DEPRECATED + + + + EXPIRATION_DATE + + + + FORBIDDEN + + + + BROKEN + + + + BROKEN_* + + + + IGNORE + + + + IGNORE_* + + + + ONLY_FOR_ARCHS + + + + ONLY_FOR_ARCHS_REASON* + + + + NOT_FOR_ARCHS + + + + NOT_FOR_ARCHS_REASON* + + + + + BROKEN* + and IGNORE* + can be any generic variables, for example, + IGNORE_amd64, + BROKEN_FreeBSD_10, + BROKEN_SSL, etc. + + If the port is marked BROKEN when some conditions are + met, and such conditions can only be tested after including + bsd.port.options.mk or + bsd.port.pre.mk, then those variables + should be set later, in . + + + + + The Dependencies Block + + This block is optional. The variables are: + + + + FETCH_DEPENDS + + + + EXTRACT_DEPENDS + + + + PATCH_DEPENDS + + + + BUILD_DEPENDS + + + + LIB_DEPENDS + + + + RUN_DEPENDS + + + + + TEST_DEPENDS + + + + + + <varname>USES</varname> and + <varname>USE_<replaceable>x</replaceable></varname> + + Start this section with defining USES, + and then possible + USE_x. + + Keep related variables close together. For example, if + using USE_GITHUB, + always put the + GH_* variables + right after it. + + + + Standard <filename>bsd.port.mk</filename> Variables + + This section block is for variables that can be defined in + bsd.port.mk that do not belong in any + of the previous section blocks. + + Order is not important, however try to keep similar variables together. + For example uid and gid variables USERS and GROUPS. + Configuration variables CONFIGURE_* and + *_CONFIGURE. List of files, and directories + PORTDOCS and PORTEXAMPLES. + + + + Options + + If the port uses the options framework, define + OPTIONS_DEFINE and + OPTIONS_DEFAULT first, then the other + OPTIONS_* + variables first, then the + *_DESC + descriptions, then the options helpers. Try and sort all of + those alphabetically. + + + + The Rest of the Variables + + And then, the rest of the variables that are not + mentioned in the previous blocks. + + + + The Targets + + After all the variables are defined, the optional + &man.make.1; targets can be defined. Keep + pre-* before + post-* and in + the same order as the different stages run: + + + + fetch + + + + extract + + + + patch + + + + configure + + + + build + + + + install + + + + test + + + + Modified: head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml Wed Aug 2 09:55:07 2017 (r50618) +++ head/en_US.ISO8859-1/books/porters-handbook/porting-samplem/chapter.xml Wed Aug 2 12:19:40 2017 (r50619) @@ -112,455 +112,4 @@ pre-install: [and then the epilogue] .include <bsd.port.mk> - - - Order of Variables in Port Makefiles - - The first sections of the Makefile - must always come in the same order. This standard makes it so - everyone can easily read any port without having to search for - variables in a random order. - - The first line of a Makefile is always - a comment containing the Subversion - version control ID, followed by an empty line. In new ports, it - looks like this: - - # $FreeBSD$ -  - - In existing ports, Subversion - has expanded it to look like this: - - # $FreeBSD: head/ports-mgmt/pkg/Makefile 437007 2017-03-26 21:25:47Z bapt $ -  - - - The sections and variables described here are mandatory in - a ordinary port. In a slave port, many sections variables and - can be skipped. - - - - Each following block must be separated from the previous - block by a single blank line. - - In the following blocks, only set the variables that are - required by the port. Define these variables in the order - they are shown here. - - - - <varname>PORTNAME</varname> Block - - This block is the most important. It defines the port - name, version, distribution file location, and category. The - variables must be in this order: - - - - PORTNAME - - - - PORTVERSION - - - - DISTVERSIONPREFIX - - - - DISTVERSION - - - - DISTVERSIONSUFFIX - - - - PORTREVISION - - - - PORTEPOCH - - - - CATEGORIES - - - - MASTER_SITES - - - - MASTER_SITE_SUBDIR - (deprecated) - - - - PKGNAMEPREFIX - - - - PKGNAMESUFFIX - - - - DISTNAME - - - - EXTRACT_SUFX - - - - DISTFILES - - - - DIST_SUBDIR - - - - EXTRACT_ONLY - - - - - Only one of PORTVERSION and - DISTVERSION can be used. - - - - - <varname>PATCHFILES</varname> Block - - This block is optional. The variables are: - - - - PATCH_SITES - - - - PATCHFILES - - - - PATCH_DIST_STRIP - - - - - - <varname>MAINTAINER</varname> Block - - This block is mandatory. The variables are: - - - - MAINTAINER - - - - COMMENT - - - - - - <varname>LICENSE</varname> Block - - This block is optional, although it is highly recommended. - The variables are: - - - - LICENSE - - - - LICENSE_COMB - - - - LICENSE_GROUPS - or - LICENSE_GROUPS_NAME - - - - LICENSE_NAME - or - LICENSE_NAME_NAME - - - - LICENSE_TEXT - or - LICENSE_TEXT_NAME - - - - LICENSE_FILE - or - LICENSE_FILE_NAME - - - - LICENSE_PERMS - or - LICENSE_PERMS_NAME - - - - LICENSE_DISTFILES - or - LICENSE_DISTFILES_NAME - - - - If there are multiple licenses, sort the different - LICENSE_VAR_NAME - variables by license name. - - - - Generic - <varname>BROKEN</varname>/<varname>IGNORE</varname>/<varname>DEPRECATED</varname> - Messages - - This block is optional. The variables are: - - - - DEPRECATED - - - - EXPIRATION_DATE - - - - FORBIDDEN - - - - BROKEN - - - - BROKEN_* - - - - IGNORE - - - - IGNORE_* - - - - ONLY_FOR_ARCHS - - - - ONLY_FOR_ARCHS_REASON* - - - - NOT_FOR_ARCHS - - - - NOT_FOR_ARCHS_REASON* - - - - - BROKEN* - and IGNORE* - can be any generic variables, for example, - IGNORE_amd64, - BROKEN_FreeBSD_10, - BROKEN_SSL, etc. - - If the port is marked BROKEN when some conditions are - met, and such conditions can only be tested after including - bsd.port.options.mk or - bsd.port.pre.mk, then those variables - should be set later, in . - - - - - The Dependencies Block - - This block is optional. The variables are: - - - - FETCH_DEPENDS - - - - EXTRACT_DEPENDS - - - - PATCH_DEPENDS - - - - BUILD_DEPENDS - - - - LIB_DEPENDS - - - - RUN_DEPENDS - - - - - TEST_DEPENDS - - - - - - <varname>USES</varname> and - <varname>USE_<replaceable>x</replaceable></varname> - - Start this section with defining USES, - and then possible - USE_x. - - Keep related variables close together. For example, if - using USE_GITHUB, - always put the - GH_* variables - right after it. - - - - Standard <filename>bsd.port.mk</filename> Variables - - This section block is for variables that can be defined in - bsd.port.mk that do not belong in any - of the previous section blocks. - - Order is not important, however try to keep similar variables together. - For example uid and gid variables USERS and GROUPS. - Configuration variables CONFIGURE_* and - *_CONFIGURE. List of files, and directories - PORTDOCS and PORTEXAMPLES. - - - - Options - - If the port uses the options framework, define - OPTIONS_DEFINE and - OPTIONS_DEFAULT first, then the other - OPTIONS_* - variables first, then the - *_DESC - descriptions, then the options helpers. Try and sort all of - those alphabetically. - - - - The Rest of the Variables - - And then, the rest of the variables that are not - mentioned in the previous blocks. - - - - The Targets - - After all the variables are defined, the optional - &man.make.1; targets can be defined. Keep - pre-* before - post-* and in - the same order as the different stages run: - - - - fetch - - - - extract - - - - patch - - - - configure - - - - build - - - - install - - - - test - - - -