author | John Beck <John.Beck@Oracle.COM> |
Fri, 12 Jul 2013 09:55:54 -0700 | |
changeset 1393 | 300d3de848bb |
parent 1258 | 43768f8c79d5 |
child 1907 | 446472de62e9 |
permissions | -rw-r--r-- |
1245
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
1 |
This is a guide to explain various useful variables in Userland component |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
2 |
Makefiles. To distinguish these from the Makefile(s) that are part of each |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
3 |
component distribution, the latter will be referred to as native Makefiles. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
4 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
5 |
The following are the basics that just about every Makefile should have. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
6 |
* COMPONENT_NAME is typically a short name (e.g., vim). |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
7 |
* COMPONENT_VERSION is typically numbers separated by dots (e.g. 7.3). |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
8 |
* COMPONENT_SRC is where the archive is extracted. A common value for this is |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
9 |
"$(COMPONENT_NAME)-$(COMPONENT_VERSION)". |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
10 |
* COMPONENT_PROJECT_URL is the general web site for the component. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
11 |
* COMPONENT_ARCHIVE is the base name of the archive to be downloaded. A common |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
12 |
value for this is "$(COMPONENT_SRC).tar.gz". |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
13 |
* COMPONENT_ARCHIVE_HASH is typically "sha256:" followed by the first output |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
14 |
field of `sha256sum $(COMPONENT_ARCHIVE)`. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
15 |
* COMPONENT_ARCHIVE_URL is where the archive can be downloaded from. This is |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
16 |
typically constructed from $(COMPONENT_PROJECT_URL) and $(COMPONENT_ARCHIVE). |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
17 |
* COMPONENT_BUGDB is the lower-case rendering of the BugDB cat/subcat. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
18 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
19 |
These two are both initialized in make-rules/shared-macros.mk rather than any |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
20 |
component-level Makefile, but are frequently referenced from the latter. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
21 |
* COMPONENT_DIR is the top-level directory of the given component in question. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
22 |
* SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC). |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
23 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
24 |
Additional pre/post configure, build, or install actions can be specified in |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
25 |
a component Makefile by setting them in one of the following macros. None of |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
26 |
these have default values. These are mostly used for miscellaneous set-up or |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
27 |
clean-up tweaks as their names suggest. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
28 |
* COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
29 |
source directory. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
30 |
* COMPONENT_POST_CONFIGURE_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
31 |
* COMPONENT_PRE_BUILD_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
32 |
* COMPONENT_POST_BUILD_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
33 |
* COMPONENT_PRE_INSTALL_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
34 |
* COMPONENT_POST_INSTALL_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
35 |
* COMPONENT_PRE_TEST_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
36 |
* COMPONENT_POST_TEST_ACTION |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
37 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
38 |
If component specific make targets need to be used for build or install or |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
39 |
test, they can be specified via the following. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
40 |
* COMPONENT_BUILD_TARGETS is not usually set because the default target of most |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
41 |
open source software is the equivalent of a 'build' target. This needs to be |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
42 |
set when building the software requires a different target than the default. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
43 |
You should not override make macros here, but in COMPONENT_BUILD_ARGS. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
44 |
* COMPONENT_INSTALL_TARGETS has a default value of "install". Very few |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
45 |
components need to alter this. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
46 |
* COMPONENT_TEST_TARGETS has a default value of "check". Several components |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
47 |
need to set this to "test". |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
48 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
49 |
* COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
50 |
subtle build issues. When you need to override a MACRO set in the native |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
51 |
Makefile of a component, do so by adding something like: |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
52 |
COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)" |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
53 |
Quoting is often important because values with white-space can be split up, |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
54 |
yielding the wrong results. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
55 |
* COMPONENT_BUILD_ENV is for when you just need to override things in the |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
56 |
calling environment, like PATH. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
57 |
* COMPONENT_INSTALL_ARGS is mainly used for altering target directories. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
58 |
* COMPONENT_INSTALL_ENV is mainly used for altering target directories. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
59 |
* COMPONENT_TEST_ARGS is little used. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
60 |
* COMPONENT_TEST_ENV is mainly used for altering PATH and friends. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
61 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
62 |
* COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
63 |
source directory before any patching has taken place. It should almost never |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
64 |
be used. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
65 |
* COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
66 |
source. It should be used with care. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
67 |
|
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
68 |
* CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
69 |
default) will trigger the following being passed to CONFIGURE_OPTIONS as |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
70 |
parameters to corresponding options. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
71 |
* CONFIGURE_BINDIR is the value for the --bindir= option. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
72 |
* CONFIGURE_LIBDIR is the value for the --libdir= option. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
73 |
* CONFIGURE_MANDIR is the value for the --mandir= option. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
74 |
* CONFIGURE_SBINDIR is the value for the --sbindir= option. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
75 |
* CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
76 |
variables to configure. When should this be used as opposed to |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
77 |
CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
78 |
to tell configure how to build the software using CONFIGURE_OPTIONS. But |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
79 |
sometimes you need to pass values in via the calling environment. On rare |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
80 |
occasions, you still need to do things like override MACRO settings in the |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
81 |
generated Makefiles with COMPONENT_BUILD_ARGS. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
82 |
* CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
83 |
rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
84 |
* CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on" |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
85 |
variable, for passing various options to configure. These tend to vary per |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
86 |
component, but --enable-foo and --disable-foo for various values of foo are |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
87 |
quite common. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
88 |
* CONFIGURE_PREFIX is the prefix for the various *DIR variables above. Its |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
89 |
default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed. |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
90 |
* CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is |
b95e96615c0c
16577372 Userland Makefile variables should be less magical
John Beck <John.Beck@Oracle.COM>
parents:
diff
changeset
|
91 |
unsuitable for whatever reason. |
1258
43768f8c79d5
16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents:
1245
diff
changeset
|
92 |
|
43768f8c79d5
16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents:
1245
diff
changeset
|
93 |
* studio_OPT has a default value of "-xO4". Occasional bugs in the optimizer |
43768f8c79d5
16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents:
1245
diff
changeset
|
94 |
have been found which have required altering this to "-xO3". There are also |
43768f8c79d5
16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents:
1245
diff
changeset
|
95 |
studio_OPT.$(MACH).$(BITS) versions of this available if greater specificity |
43768f8c79d5
16624973 document studio_OPT in doc/makefile-variables.txt
John Beck <John.Beck@Oracle.COM>
parents:
1245
diff
changeset
|
96 |
is needed. |