Index: head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml (revision 54412) +++ head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml (revision 54413) @@ -1,551 +1,551 @@ 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 and variables 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 + linkend="makefile-versions">PORTVERSIONOnly one of + PORTVERSION and + DISTVERSION can be + used. DISTVERSIONPREFIX DISTVERSION + linkend="makefile-versions">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, etc. With the exception of variables that depend on a USES, place those in . For instance, IGNORE_WITH_PHP only works if USES=php is set, and BROKEN_SSL only if USES=ssl is set. 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 Flavors This block is optional. Start this section with defining FLAVORS. Continue with the possible Flavors helpers. See for more Information. Constructs setting variables not available as helpers using .if ${FLAVOR:U} == foo should go in their respective sections below. <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 and Helpers 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. Options Variables Order Example The FOO and BAR options do not have a standard description, so one need to be written. The other options already have one in Mk/bsd.options.desc.mk so writing one is not needed. The DOCS and EXAMPLES use target helpers to install their files, they are shown here for completeness, though they belong in , so other variables and targets could be inserted before them. OPTIONS_DEFINE= DOCS EXAMPLES FOO BAR OPTIONS_DEFAULT= FOO OPTIONS_RADIO= SSL OPTIONS_RADIO_SSL= OPENSSL GNUTLS OPTIONS_SUB= yes BAR_DESC= Enable bar support FOO_DESC= Enable foo support BAR_CONFIGURE_WITH= bar=${LOCALBASE} FOO_CONFIGURE_ENABLE= foo GNUTLS_CONFIGURE_ON= --with-ssl=gnutls OPENSSL_CONFIGURE_ON= --with-ssl=openssl post-install-DOCS-on: ${MKDIR} ${STAGEDIR}${DOCSDIR} cd ${WRKSRC}/doc && ${COPYTREE_SHARE} . ${STAGEDIR}${DOCSDIR} post-install-EXAMPLES-on: ${MKDIR} ${STAGEDIR}${EXAMPLESDIR} cd ${WRKSRC}/ex && ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} 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 When using options helpers target keep them alphabetically sorted, but keep the *-on before the *-off. When also using the main target, keep the main target before the optional ones: post-install: # install generic bits post-install-DOCS-on: # Install documentation post-install-X11-on: # Install X11 related bits post-install-X11-off: # Install bits that should be there if X11 is disabled