---
title: Chapter 15. Order of Variables in Port Makefiles
prev: books/porters-handbook/porting-samplem
next: books/porters-handbook/keeping-up
description: Order of Variables in FreeBSD Port Makefiles
tags: ["order", "PORTNAME", "PATCHFILES", "MAINTAINER", "LICENSE", "dependencies", "USES"]
showBookMenu: true
weight: 15
params:
  path: "/books/porters-handbook/order/"
---

[[porting-order]]
= Order of Variables in Port Makefiles
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 15
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

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.

[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:

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

* crossref:makefiles[porting-patchfiles,`PATCH_SITES`]
* crossref:makefiles[porting-patchfiles,`PATCHFILES`]
* crossref:makefiles[porting-patchfiles,`PATCH_DIST_STRIP`]

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

This block is mandatory.
The variables are:

* crossref:makefiles[makefile-maintainer,`MAINTAINER`]
* crossref:makefiles[makefile-comment,`COMMENT`]
* crossref:makefiles[makefile-www,`WWW`]

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

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

* crossref:makefiles[licenses-license,`LICENSE`]
* crossref:makefiles[licenses-license_comb,`LICENSE_COMB`]
* crossref:makefiles[licenses-license_groups,`LICENSE_GROUPS`] or `LICENSE_GROUPS_NAME`
* crossref:makefiles[licenses-license_name,`LICENSE_NAME`] or `LICENSE_NAME_NAME`
* crossref:makefiles[licenses-license_text,`LICENSE_TEXT`] or `LICENSE_TEXT_NAME`
* crossref:makefiles[licenses-license_file,`LICENSE_FILE`] or `LICENSE_FILE_NAME`
* crossref:makefiles[licenses-license_perms,`LICENSE_PERMS`] or `LICENSE_PERMS_NAME_`
* crossref:makefiles[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:

* crossref:porting-dads[dads-deprecated,`DEPRECATED`]
* crossref:porting-dads[dads-deprecated,`EXPIRATION_DATE`]
* crossref:porting-dads[dads-noinstall,`FORBIDDEN`]
* crossref:porting-dads[dads-noinstall,`BROKEN`]
* crossref:porting-dads[dads-noinstall,`BROKEN_*`]
* crossref:porting-dads[dads-noinstall,`IGNORE`]
* crossref:porting-dads[dads-noinstall,`IGNORE_*`]
* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS`]
* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS_REASON*`]
* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS`]
* crossref:porting-dads[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 crossref:uses[uses,`USES`],
place those in crossref:order[porting-order-uses, `USES` and `USE_x`].
For instance, `IGNORE_WITH_PHP` only works if crossref:uses[uses-php,`php`] is set, and `BROKEN_SSL` only if crossref:uses[uses-ssl,`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
crossref:order[porting-order-rest, The Rest of the Variables].
====

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

This block is optional. The variables are:

* crossref:makefiles[makefile-fetch_depends,`FETCH_DEPENDS`]
* crossref:makefiles[makefile-extract_depends,`EXTRACT_DEPENDS`]
* crossref:makefiles[makefile-patch_depends,`PATCH_DEPENDS`]
* crossref:makefiles[makefile-build_depends,`BUILD_DEPENDS`]
* crossref:makefiles[makefile-lib_depends,`LIB_DEPENDS`]
* crossref:makefiles[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 crossref:flavors[flavors-using,Using FLAVORS] 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 crossref:makefiles[makefile-master_sites-github,`USE_GITHUB`], always put the `GH_*` variables right after it.

[[porting-order-variables]]
== Standard 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 crossref:makefiles[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 crossref:order[porting-order-targets, The 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
....
====