1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
---
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
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`][<<portversion-footnote, 1>>]
* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`]
* crossref:makefiles[makefile-versions,`DISTVERSION`][<<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`]
[[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 <<porting-order-uses>>.
For instance, `IGNORE_WITH_PHP` only works if crossref:uses[xuses-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 <<porting-order-rest>>.
====
[[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 <<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
....
====
|
