---
title: Chapter 15. Order of Variables in Port Makefiles
prev: books/porters-handbook/porting-samplem
next: books/porters-handbook/keeping-up
---

[[porting-order]]
= Order of Variables in Port Makefiles
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:toc-title: 目录
:part-signifier: 部分
:chapter-signifier: 第
:appendix-caption: 附录
:table-caption: 表
:figure-caption: 图
:example-caption: 例 
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 15

include::shared/mirrors.adoc[]
include::shared/authors.adoc[]
include::shared/releases.adoc[]
include::shared/zh-tw/mailing-lists.adoc[]
include::shared/zh-tw/urls.adoc[]

toc::[]

The first sections of the [.filename]#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 [.filename]#Makefile# is always a comment containing the Subversion version control ID, followed by an empty line. In new ports, it looks like this:

[.programlisting]
....
# $FreeBSD$
....

In existing ports, Subversion has expanded it to look like this:

[.programlisting]
....
# $FreeBSD: head/ports-mgmt/pkg/Makefile 437007 2017-03-26 21:25:47Z bapt $
....

[NOTE]
====
The sections and variables described here are mandatory in a ordinary port. In a slave port, many sections and variables can be skipped.
====

[IMPORTANT]
====
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.
====

[[porting-order-portname]]
== `PORTNAME` 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:

* <<makefile-portname,`PORTNAME`>>
* <<makefile-versions,`PORTVERSION`>>[<<portversion-footnote, 1>>]
* <<makefile-versions,`DISTVERSIONPREFIX`>>
* <<makefile-versions,`DISTVERSION`>>[<<portversion-footnote, 1>>]
* <<makefile-versions,`DISTVERSIONSUFFIX`>>
* <<makefile-portrevision,`PORTREVISION`>>
* <<makefile-portepoch,`PORTEPOCH`>>
* <<makefile-categories,`CATEGORIES`>>
* <<makefile-master_sites,`MASTER_SITES`>>
* <<makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`>> (deprecated)
* <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`>>
* <<porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`>>
* <<makefile-distname,`DISTNAME`>>
* <<makefile-extract_sufx,`EXTRACT_SUFX`>>
* <<makefile-distfiles-definition,`DISTFILES`>>
* <<makefile-dist_subdir,`DIST_SUBDIR`>>
* <<makefile-extract_only,`EXTRACT_ONLY`>>

[[portversion-footnote]]
[IMPORTANT]
====
Only one of PORTVERSION and DISTVERSION can be used.
====

[[porting-order-patch]]
== `PATCHFILES` Block

This block is optional. The variables are:

* <<porting-patchfiles,`PATCH_SITES`>>
* <<porting-patchfiles,`PATCHFILES`>>
* <<porting-patchfiles,`PATCH_DIST_STRIP`>>

[[porting-order-maintainer]]
== `MAINTAINER` Block

This block is mandatory. The variables are:

* <<makefile-maintainer,`MAINTAINER`>>
* <<makefile-comment,`COMMENT`>>

[[porting-order-license]]
== `LICENSE` Block

This block is optional, although it is highly recommended. The variables are:

* <<licenses-license,`LICENSE`>>
* <<licenses-license_comb,`LICENSE_COMB`>>
* <<licenses-license_groups,`LICENSE_GROUPS`>> or `LICENSE_GROUPS_NAME`
* <<licenses-license_name,`LICENSE_NAME`>> or `LICENSE_NAME_NAME`
* <<licenses-license_text,`LICENSE_TEXT`>> or `LICENSE_TEXT_NAME`
* <<licenses-license_file,`LICENSE_FILE`>> or `LICENSE_FILE_NAME`
* <<licenses-license_perms,`LICENSE_PERMS`>> or `LICENSE_PERMS_NAME_`
* <<licenses-license_distfiles,`LICENSE_DISTFILES`>> or `LICENSE_DISTFILES_NAME`

If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by license name.

[[porting-order-broken]]
== Generic `BROKEN`/`IGNORE`/`DEPRECATED` Messages

This block is optional. The variables are:

* <<dads-deprecated,`DEPRECATED`>>
* <<dads-deprecated,`EXPIRATION_DATE`>>
* <<dads-noinstall,`FORBIDDEN`>>
* <<dads-noinstall,`BROKEN`>>
* <<dads-noinstall,`BROKEN_*`>>
* <<dads-noinstall,`IGNORE`>>
* <<dads-noinstall,`IGNORE_*`>>
* <<dads-noinstall,`ONLY_FOR_ARCHS`>>
* <<dads-noinstall,`ONLY_FOR_ARCHS_REASON*`>>
* <<dads-noinstall,`NOT_FOR_ARCHS`>>
* <<dads-noinstall,`NOT_FOR_ARCHS_REASON*`>>

[NOTE]
====
`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,`USES`>>, place those in <<porting-order-uses>>. For instance, `IGNORE_WITH_PHP` only works if <<uses-php,`USES=php`>> is set, and `BROKEN_SSL` only if <<uses-ssl,`USES=ssl`>> is set.

If the port is marked BROKEN when some conditions are met, and such conditions can only be tested after including [.filename]#bsd.port.options.mk# or [.filename]#bsd.port.pre.mk#, then those variables should be set later, in <<porting-order-rest>>.
====

[[porting-order-depends]]
== The Dependencies Block

This block is optional. The variables are:

* <<makefile-fetch_depends,`FETCH_DEPENDS`>>
* <<makefile-extract_depends,`EXTRACT_DEPENDS`>>
* <<makefile-patch_depends,`PATCH_DEPENDS`>>
* <<makefile-build_depends,`BUILD_DEPENDS`>>
* <<makefile-lib_depends,`LIB_DEPENDS`>>
* <<makefile-run_depends,`RUN_DEPENDS`>>
* `TEST_DEPENDS`

[[porting-order-flavors]]
== Flavors

This block is optional.

Start this section with defining `FLAVORS`. Continue with the possible Flavors helpers. See <<flavors-using>> for more Information.

Constructs setting variables not available as helpers using `.if ${FLAVOR:U} == foo` should go in their respective sections below.

[[porting-order-uses]]
== `USES` and `USE_x`

Start this section with defining `USES`, and then possible `USE_x`.

Keep related variables close together. For example, if using <<makefile-master_sites-github,`USE_GITHUB`>>, always put the `GH_*` variables right after it.

[[porting-order-variables]]
== Standard [.filename]#bsd.port.mk# Variables

This section block is for variables that can be defined in [.filename]#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`.

[[porting-order-options]]
== Options and Helpers

If the port uses the <<makefile-options,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.

[[porting-order-options-ex1]]
.Options Variables Order Example
[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 [.filename]#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 <<porting-order-targets>>, so other variables and targets could be inserted before them.

[.programlisting]
....
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}
....

====

[[porting-order-rest]]
== The Rest of the Variables

And then, the rest of the variables that are not mentioned in the previous blocks.

[[porting-order-targets]]
== 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`

[TIP]
====

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:

[.programlisting]
....
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
....

====
