|
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 |
|
3 component distribution, the latter will be referred to as native Makefiles. |
|
4 |
|
5 The following are the basics that just about every Makefile should have. |
|
6 * COMPONENT_NAME is typically a short name (e.g., vim). |
|
7 * 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 |
|
9 "$(COMPONENT_NAME)-$(COMPONENT_VERSION)". |
|
10 * 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 |
|
12 value for this is "$(COMPONENT_SRC).tar.gz". |
|
13 * COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output |
|
14 field of `sha256sum $(COMPONENT_ARCHIVE)`. |
|
15 * COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is |
|
16 typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE). |
|
17 * COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat. |
|
18 |
|
19 These two are both initialized in make-rules/shared-macros.mk rather than any |
|
20 component-level Makefile, but are frequently referenced from the latter. |
|
21 * COMPONENT_DIR is the top-level directory of the given component in question. |
|
22 * SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC). |
|
23 |
|
24 Additional pre/post configure, build, or install actions can be specified in |
|
25 a component Makefile by setting them in one of the following macros. None of |
|
26 these have default values. These are mostly used for miscellaneous set-up or |
|
27 clean-up tweaks as their names suggest. |
|
28 * COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a |
|
29 source directory. |
|
30 * COMPONENT_POST_CONFIGURE_ACTION |
|
31 * COMPONENT_PRE_BUILD_ACTION |
|
32 * COMPONENT_POST_BUILD_ACTION |
|
33 * COMPONENT_PRE_INSTALL_ACTION |
|
34 * COMPONENT_POST_INSTALL_ACTION |
|
35 * COMPONENT_PRE_TEST_ACTION |
|
36 * COMPONENT_POST_TEST_ACTION |
|
37 |
|
38 If component specific make targets need to be used for build or install or |
|
39 test, they can be specified via the following. |
|
40 * COMPONENT_BUILD_TARGETS is not usually set because the default target of most |
|
41 open source software is the equivalent of a 'build' target. This needs to be |
|
42 set when building the software requires a different target than the default. |
|
43 You should not override make macros here, but in COMPONENT_BUILD_ARGS. |
|
44 * COMPONENT_INSTALL_TARGETS has a default value of "install". Very few |
|
45 components need to alter this. |
|
46 * COMPONENT_TEST_TARGETS has a default value of "check". Several components |
|
47 need to set this to "test". |
|
48 |
|
49 * COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving |
|
50 subtle build issues. When you need to override a MACRO set in the native |
|
51 Makefile of a component, do so by adding something like: |
|
52 COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)" |
|
53 Quoting is often important because values with white-space can be split up, |
|
54 yielding the wrong results. |
|
55 * COMPONENT_BUILD_ENV is for when you just need to override things in the |
|
56 calling environment, like PATH. |
|
57 * COMPONENT_INSTALL_ARGS is mainly used for altering target directories. |
|
58 * COMPONENT_INSTALL_ENV is mainly used for altering target directories. |
|
59 * COMPONENT_PUBLISH_ENV is so far only used to work around Python issues when |
|
60 used by "pkgdepend generate", though the variable may be extended in the |
|
61 future for general "gmake publish" usage. |
|
62 * COMPONENT_TEST_ARGS is little used. |
|
63 * COMPONENT_TEST_ENV is mainly used for altering PATH and friends. |
|
64 |
|
65 * COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked |
|
66 source directory before any patching has taken place. It should almost never |
|
67 be used. |
|
68 * COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched |
|
69 source. It should be used with care. |
|
70 |
|
71 * CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the |
|
72 default) will trigger the following being passed to CONFIGURE_OPTIONS as |
|
73 parameters to corresponding options. |
|
74 * CONFIGURE_BINDIR is the value for the --bindir= option. |
|
75 * CONFIGURE_LIBDIR is the value for the --libdir= option. |
|
76 * CONFIGURE_MANDIR is the value for the --mandir= option. |
|
77 * CONFIGURE_SBINDIR is the value for the --sbindir= option. |
|
78 * CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile |
|
79 variables to configure. When should this be used as opposed to |
|
80 CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want |
|
81 to tell configure how to build the software using CONFIGURE_OPTIONS. But |
|
82 sometimes you need to pass values in via the calling environment. On rare |
|
83 occasions, you still need to do things like override MACRO settings in the |
|
84 generated Makefiles with COMPONENT_BUILD_ARGS. |
|
85 * CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but |
|
86 rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS. |
|
87 * CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on" |
|
88 variable, for passing various options to configure. These tend to vary per |
|
89 component, but --enable-foo and --disable-foo for various values of foo are |
|
90 quite common. |
|
91 * CONFIGURE_PREFIX is the prefix for the various *DIR variables above. Its |
|
92 default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed. |
|
93 * CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is |
|
94 unsuitable for whatever reason. |
|
95 |
|
96 * studio_OPT has a default value of "-xO4". Occasional bugs in the optimizer |
|
97 have been found which have required altering this to "-xO3". There are also |
|
98 studio_OPT.$(MACH).$(BITS) versions of this available if greater specificity |
|
99 is needed. |
|
100 |
|
101 * TPNO is the Third Party number (i.e., a numeric value): the License |
|
102 Technology from the Product Lifecycle Suite tool. This should be used |
|
103 in the common case when there is just one TPNO for a component. We |
|
104 recommend that this be near the top of any Makefile, just below the |
|
105 various COMPONENT_foo definitions. |
|
106 * TPNO_foo is for the rare case (~3% of components) when a component has |
|
107 more than one TPNO. Each one should have a separate short but descriptive |
|
108 name substituted for "foo". This likewise should be near the top of any |
|
109 Makefile, just below the various COMPONENT_foo definitions, and it must |
|
110 also be before the inclusion of ips.mk . |
|
111 |
|
112 --- |
|
113 |
|
114 Now switching from explaining the function of specific variables to a more |
|
115 general discussion about how to use them to solve problems. One method that |
|
116 has served time and again is adding a level of indirection. For example, |
|
117 when Python 3 came along, we decided to build it 64-bit only, which meant |
|
118 its various modules also needed to be built 64-bit only. But many of them |
|
119 had BUILD_32_and_64 in their native Makefile. So how to tweak that macro |
|
120 to do one thing for Python 2.x but another for 3.x? JBeck spent an entire |
|
121 day trying various combinations that seemed right, but none of them worked. |
|
122 Then Norm pointed out that changing PYTHON_VERSIONS from "3.4 2.7 2.6" to |
|
123 $(PYTHON3_VERSIONS) and $(PYTHON2_VERSIONS) which in turn were "3.4" and |
|
124 "2.7 2.6" would do the trick. I.e., adding a level of indirection solved |
|
125 the problem, as it allowed $(PYTHON_VERSIONS) to be used to specify 64-bit |
|
126 macros but $(PYTHON2_VERSIONS) to specify 32-bit macros. There are many |
|
127 other places where constructs like this are used. |