1 This is a guide to explain various useful variables in Userland component |
1 This is a guide to explain various useful variables in Userland component |
2 Makefiles. To distinguish these from the Makefile(s) that are part of each |
2 Makefiles. To distinguish these from the Makefile(s) that are part of each |
3 component distribution, the latter will be referred to as native Makefiles. |
3 component distribution, the latter will be referred to as native Makefiles. |
4 |
4 |
5 The following are the basics that just about every Makefile should have. |
5 The following are the basics that just about every Makefile should have. |
|
6 |
|
7 * BUILD_BITS declares which bits this component should be built for and |
|
8 which binaries are the preferred ones (i.e. should be installed in /usr/bin); |
|
9 values are: 64, 64_and_32, 32, 32_and_64. |
6 * COMPONENT_NAME is typically a short name (e.g., vim). |
10 * COMPONENT_NAME is typically a short name (e.g., vim). |
7 * COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3). |
11 * COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3). |
8 * COMPONENT_SRC is where the archive is extracted. A common value for this is |
12 * COMPONENT_SRC is where the archive is extracted; it has a default value of |
9 "$(COMPONENT_NAME)-$(COMPONENT_VERSION)". |
13 "$(COMPONENT_NAME)-$(COMPONENT_VERSION)". |
10 * COMPONENT_PROJECT_URL is the general web site for the component. |
14 * COMPONENT_PROJECT_URL is the general web site for the component. |
11 * COMPONENT_ARCHIVE is the base name of the archive to be downloaded. A common |
15 * COMPONENT_ARCHIVE is the base name of the archive to be downloaded; it has |
12 value for this is "$(COMPONENT_SRC).tar.gz". |
16 a default value of "$(COMPONENT_SRC).tar.gz". |
13 * COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output |
17 * COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output |
14 field of `sha256sum $(COMPONENT_ARCHIVE)`. |
18 field of `sha256sum $(COMPONENT_ARCHIVE)`. |
15 * COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is |
19 * COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is |
16 typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE). |
20 typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE). |
17 * COMPONENT_SIG_URL is the URL where the PGP signature for $(COMPONENT_ARCHIVE) |
21 * COMPONENT_SIG_URL is the URL where the PGP signature for $(COMPONENT_ARCHIVE) |
40 * HG_REV is the tag or changeset that you wish to pull from Mercurial. |
41 * HG_REV is the tag or changeset that you wish to pull from Mercurial. |
41 |
42 |
42 * SVN_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component |
43 * SVN_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component |
43 source from the Subversion repository referenced in the value. |
44 source from the Subversion repository referenced in the value. |
44 * SVN_REV is the tag or changeset that you wish to pull from Subversion. |
45 * SVN_REV is the tag or changeset that you wish to pull from Subversion. |
|
46 |
|
47 The following are basic variables that can be overridden but provide default |
|
48 values: |
|
49 |
|
50 * BUILD_ARCH declares which architecture this component should be built for; |
|
51 possible values are: i386, sparc. If not set, the component will be built |
|
52 for both. |
|
53 * COMPONENT_SRC is where the archive is extracted; it has a default value of |
|
54 "$(COMPONENT_NAME)-$(COMPONENT_VERSION)". |
|
55 * COMPONENT_ARCHIVE is the base name of the archive to be downloaded; it has |
|
56 a default value of "$(COMPONENT_SRC).tar.gz". |
|
57 * COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat; it has |
|
58 a default value of "utility/$(COMPONENT_NAME)". |
|
59 * REQUIRED_PACKAGES is a list of packages required to build or run the |
|
60 component and its tests; it includes "system/library" by default. |
|
61 |
|
62 * GIT_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component |
|
63 source from the GIT repository referenced in the value. |
|
64 * GIT_REV is the tag or changeset that you wish to pull from GIT. |
|
65 |
|
66 * HG_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component |
|
67 source from the Mercurial repository referenced in the value. |
|
68 * HG_REV is the tag or changeset that you wish to pull from Mercurial. |
|
69 |
|
70 * SVN_REPO can be used in place of COMPONENT_ARCHIVE_URL to pull the component |
|
71 source from the Subversion repository referenced in the value. |
|
72 * SVN_REV is the tag or changeset that you wish to pull from Subversion. |
|
73 |
|
74 The following are basic variables that must be set before including common.mk |
|
75 if overriding the default: |
|
76 |
|
77 * BUILD_STYLE declares what type of build process this component uses; |
|
78 possible values are: ant, archive (extract and copy), attpackagemake, cmake, |
|
79 configure, gnu-component, justmake, pkg (publish only), and setup.py. See |
|
80 the corresponding file in make-rules for details. The default value is |
|
81 'configure'. |
|
82 |
|
83 Based on the value of BUILD_STYLE, other variables are affected as follows: |
|
84 |
|
85 - If BUILD_STYLE is configure, CONFIGURE_ENV will automatically include |
|
86 CFLAGS, CXXFLAGS, and LDFLAGS. |
|
87 - If BUILD_STYLE is justmake, COMPONENT_BUILD_ENV will automatically include |
|
88 CC, CXX, CFLAGS, CXXFLAGS, and LDFLAGS. |
|
89 |
|
90 * COMMON_TARGETS controls whether the standard build, configure, install, |
|
91 test, system-test targets are provided automatically. Possible values |
|
92 are 'yes' and 'no'. The default value is 'yes'. |
|
93 |
|
94 * BUILD_TARGET, INSTALL_TARGET, TEST_TARGET, SYSTEM_TEST_TARGET allow |
|
95 overriding the default targets provided by COMMON_TARGETS. If set to a |
|
96 non-empty value, they act as an override. If set to an empty value the |
|
97 target will not be defined by common.mk. Instead of overriding the standard |
|
98 targets, it is suggested that the appropriate COMPONENT_PRE_*_ACTION or |
|
99 COMPONENT_POST_*_ACTION variables be used instead. |
|
100 |
|
101 * BUILD_TARGET defaults to $(BUILD_$(BUILD_BITS)) |
|
102 |
|
103 * INSTALL_TARGET defaults to $(INSTALL_$(BUILD_BITS)) |
|
104 |
|
105 * TEST_TARGET defaults to $(TEST_$(BUILD_BITS)) |
|
106 |
|
107 * SYSTEM_TEST_TARGET default is determined by $(TEST_TARGET); if TEST_TARGET |
|
108 is not $(NO_TESTS) or $(SKIP_TEST), the default value is |
|
109 $(SYSTEM_TESTS_NOT_IMPLEMENTED) |
|
110 |
|
111 The following variables alter the compilation or build process for components: |
|
112 |
|
113 * ASLR_MODE controls the application of Address Space Layout Randomization to |
|
114 ELF binaries during the build. The possible values are: $(ASLR_ENABLE), |
|
115 $(ASLR_DISABLE), $(ASLR_NOT_APPLICABLE). If $(BUILD_BITS) is $(NO_ARCH), |
|
116 $(BUILD_STYLE) is 'ant', or $(COMPONENT_BUGDB) starts with 'library', |
|
117 $(ASLR_NOT_APPLICABLE) is the default. Otherwise, the default is |
|
118 $(ASLR_ENABLE). |
45 |
119 |
46 When using a source code management system as the canonical source for a |
120 When using a source code management system as the canonical source for a |
47 component, the build automatically generates a source archive for the |
121 component, the build automatically generates a source archive for the |
48 component by pulling the source from the SCM and creating a tarball from |
122 component by pulling the source from the SCM and creating a tarball from |
49 the pulled source. This allows us to automatically store a copy of the |
123 the pulled source. This allows us to automatically store a copy of the |
116 but your component Makefile might have to += some more for specific transforms |
190 but your component Makefile might have to += some more for specific transforms |
117 that need to be applied to the test output for just this component. |
191 that need to be applied to the test output for just this component. |
118 |
192 |
119 * SKIP_TEST_AT_TOP_LEVEL inclusion of this variable in a component Makefile |
193 * SKIP_TEST_AT_TOP_LEVEL inclusion of this variable in a component Makefile |
120 will cause that component's tests to be skipped when running "gmake test" |
194 will cause that component's tests to be skipped when running "gmake test" |
121 at the top level. It's often used for excluding long-running tests |
195 at the top level. It's often used for excluding long-running tests |
122 that may slow down comprehensive component testing. |
196 that may slow down comprehensive component testing. |
123 |
197 |
124 * COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked |
198 * COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked |
125 source directory before any patching has taken place. It should almost never |
199 source directory before any patching has taken place. It should almost never |
126 be used. |
200 be used. |
127 * COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched |
201 * COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched |
128 source. It should be used with care. |
202 source. It should be used with care. |
129 |
203 |
130 For components that have a configure target, the following macros are used to |
204 For components that have a configure target, the following macros are used to |
131 control the options and arguments passed: |
205 control the options and arguments passed: |
132 |
206 |
133 * If BITS is set before shared-macros.mk is included, the default directories |
207 * If BUILD_BITS is set before shared-macros.mk is included, the default directories |
134 used for various configure options as documented below will change. For |
208 used for various configure options as documented below will change. For |
135 example: |
209 example: |
136 |
210 |
137 if BITS=64 explicitly: |
211 if BUILD_BITS=64 or BUILD_BITS= 64_and_32 explicitly: |
138 32-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH32) |
212 32-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH32) |
139 32-bit libraries -> $(CONFIGURE_PREFIX)/lib |
213 32-bit libraries -> $(CONFIGURE_PREFIX)/lib |
140 64-bit binaries -> $(CONFIGURE_PREFIX)/bin |
214 64-bit binaries -> $(CONFIGURE_PREFIX)/bin |
141 64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64) |
215 64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64) |
142 |
216 |
143 if BITS=32 explicitly or BITS is unspecified: |
217 if BUILD_BITS=32 or BUILD_BITS=32_and_64 explicitly or BITS is unspecified: |
144 32-bit binaries -> $(CONFIGURE_PREFIX)/bin |
218 32-bit binaries -> $(CONFIGURE_PREFIX)/bin |
145 32-bit libraries -> $(CONFIGURE_PREFIX)/lib |
219 32-bit libraries -> $(CONFIGURE_PREFIX)/lib |
146 64-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH64) |
220 64-bit binaries -> $(CONFIGURE_PREFIX)/bin/$(MACH64) |
147 64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64) |
221 64-bit libraries -> $(CONFIGURE_PREFIX)/lib/$(MACH64) |
148 * CC_FOR_BUILD is included in CONFIGURE_ENV by default to ensure that 32-bit |
222 * CC_FOR_BUILD and CXX_FOR_BUILD is included in CONFIGURE_ENV by default to |
149 and 64-bit host detection works as expected for autoconf-based components by |
223 ensure that 32-bit and 64-bit host detection works as expected for |
150 specifying the exact compiler and relevant $(CC_BITS) for the current build. |
224 autoconf-based components by specifying the exact compiler and relevant |
151 It can be set to "" to omit it from CONFIGURE_ENV. |
225 $(CC_BITS) for the current build. It can be set to "" to omit it from |
|
226 CONFIGURE_ENV. |
152 * CONFIGURE_CPPFLAGS contains the default set of CPPFLAGS to be included in |
227 * CONFIGURE_CPPFLAGS contains the default set of CPPFLAGS to be included in |
153 CONFIGURE_ENV. It can be set to "" to omit it from CONFIGURE_ENV. |
228 CONFIGURE_ENV. It can be set to "" to omit it from CONFIGURE_ENV. |
154 * CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the |
229 * CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the |
155 default) will trigger the following being passed to CONFIGURE_OPTIONS as |
230 default) will trigger the following being passed to CONFIGURE_OPTIONS as |
156 parameters to corresponding options. |
231 parameters to corresponding options. |
157 * CONFIGURE_BINDIR.$(BITS) is the value for the --bindir= option. |
232 * CONFIGURE_BINDIR.$(BITS) is the value for the --bindir= option. |
158 * CONFIGURE_LIBDIR.$(BITS) is the value for the --libdir= option. |
233 * CONFIGURE_LIBDIR.$(BITS) is the value for the --libdir= option. |
159 * CONFIGURE_MANDIR.$(BITS) is the value for the --mandir= option. |
234 * CONFIGURE_MANDIR.$(BITS) is the value for the --mandir= option. |
160 * CONFIGURE_SBINDIR.$(BITS) is the value for the --sbindir= option. |
235 * CONFIGURE_SBINDIR.$(BITS) is the value for the --sbindir= option. |
161 * CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile |
236 * CONFIGURE_ENV is mainly used for passing Makefile variables to configure. |
162 variables to configure. When should this be used as opposed to |
237 When should this be used as opposed to CONFIGURE_OPTIONS and |
163 CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want |
238 COMPONENT_BUILD_{ARGS,ENV}? In general, you want to tell configure how to |
164 to tell configure how to build the software using CONFIGURE_OPTIONS. But |
239 build the software using CONFIGURE_OPTIONS. But sometimes you need to pass |
165 sometimes you need to pass values in via the calling environment. On rare |
240 values in via the calling environment. On rare occasions, you still need to |
166 occasions, you still need to do things like override MACRO settings in the |
241 do things like override MACRO settings in the generated Makefiles with |
167 generated Makefiles with COMPONENT_BUILD_ARGS. |
242 COMPONENT_BUILD_ARGS. |
168 * CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but |
243 * CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but |
169 rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS. |
244 rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS. |
170 * CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on" |
245 * CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on" |
171 variable, for passing various options to configure. These tend to vary per |
246 variable, for passing various options to configure. These tend to vary per |
172 component, but --enable-foo and --disable-foo for various values of foo are |
247 component, but --enable-foo and --disable-foo for various values of foo are |
180 components, the following macros are provided: |
255 components, the following macros are provided: |
181 |
256 |
182 * CFLAGS by default contains the preferred set of compilation flags for most |
257 * CFLAGS by default contains the preferred set of compilation flags for most |
183 components, which usually includes optimization flags, language mode, |
258 components, which usually includes optimization flags, language mode, |
184 alignment flags, and multi-threading flags for the current COMPILER. |
259 alignment flags, and multi-threading flags for the current COMPILER. |
185 CFLAGS.$(COMPILER) and CFLAGS.$(COMPILERS).$(BITS) versions are also |
260 CFLAGS.$(COMPILER), CFLAGS.$(COMPILERS).$(BITS), |
186 available for specifying additional flags or overriding the default. |
261 CFLAGS.$(COMPILERS).$(MACH), and CFLAGS.$(COMPILERS).$(MACH).$(BITS) |
|
262 versions are also available for specifying additional flags or overriding |
|
263 the default. |
187 * CXXFLAGS by default contains the preferred set of compilation flags for most |
264 * CXXFLAGS by default contains the preferred set of compilation flags for most |
188 C++ components, which usually includes optimization flags, language mode, |
265 C++ components, which usually includes optimization flags, language mode, |
189 alignment flags, and multi-threading flags for the current COMPILER. |
266 alignment flags, and multi-threading flags for the current COMPILER. |
190 CXXFLAGS.$(COMPILER) and CXXFLAGS.$(COMPILERS).$(BITS) versions are also |
267 CXXFLAGS.$(COMPILER), CXXFLAGS.$(COMPILERS).$(BITS), |
191 available for specifying additional flags or overriding the default. |
268 CXXFLAGS.$(COMPILERS).$(MACH), and CXXFLAGS.$(COMPILERS).$(MACH).$(BITS) |
|
269 versions are also available for specifying additional flags or overriding |
|
270 the default. |
192 * gcc_OPT has a default value of "-O3". Bugs in the optimizer have been found |
271 * gcc_OPT has a default value of "-O3". Bugs in the optimizer have been found |
193 which have required altering this to "-O2". |
272 which have required altering this to "-O2". |
194 * studio_OPT has a default value of "-xO4". Occasional bugs in the optimizer |
273 * studio_OPT has a default value of "-xO4". Occasional bugs in the optimizer |
195 have been found which have required altering this to "-xO3". |
274 have been found which have required altering this to "-xO3". |
196 * There are also gcc_OPT.$(MACH).$(BITS) and studio_OPT.$(MACH).$(BITS) |
275 * There are also gcc_OPT.$(MACH).$(BITS) and studio_OPT.$(MACH).$(BITS) |