commit | author | age
|
487725
|
1 |
This is a guide to explain various useful variables in Userland component |
JB |
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). |
476679
|
17 |
* COMPONENT_SIG_URL is the URL where the PGP signature for $(COMPONENT_ARCHIVE) |
AŠ |
18 |
can be found. This can be used in addition to the hash in |
|
19 |
$(COMPONENT_ARCHIVE_HASH) to verify the correctness of the archive. If |
|
20 |
COMPONENT_SIG_URL is present, then COMPONENT_ARCHIVE_HASH needn't be, but its |
|
21 |
presence is strongly encouraged to ensure that the archive contents don't |
|
22 |
change silently. Note that when merging, because |
|
23 |
$WS/tools/.gnupg/pubring.gpg is a binary file, you will have to choose |
|
24 |
the correct version. To check if key is imported, run: |
|
25 |
gpg2 --homedir=$(git rev-parse --show-toplevel)/tools/.gnupg --list-keys |
|
26 |
before you 'git commit' your merge. |
487725
|
27 |
|
JB |
28 |
These two are both initialized in make-rules/shared-macros.mk rather than any |
|
29 |
component-level Makefile, but are frequently referenced from the latter. |
|
30 |
* COMPONENT_DIR is the top-level directory of the given component in question. |
|
31 |
* SOURCE_DIR is set to $(COMPONENT_DIR)/$(COMPONENT_SRC). |
|
32 |
|
|
33 |
Additional pre/post configure, build, or install actions can be specified in |
|
34 |
a component Makefile by setting them in one of the following macros. None of |
|
35 |
these have default values. These are mostly used for miscellaneous set-up or |
|
36 |
clean-up tweaks as their names suggest. |
|
37 |
* COMPONENT_PRE_CONFIGURE_ACTION is used by several components to clone a |
|
38 |
source directory. |
|
39 |
* COMPONENT_POST_CONFIGURE_ACTION |
|
40 |
* COMPONENT_PRE_BUILD_ACTION |
|
41 |
* COMPONENT_POST_BUILD_ACTION |
|
42 |
* COMPONENT_PRE_INSTALL_ACTION |
|
43 |
* COMPONENT_POST_INSTALL_ACTION |
|
44 |
* COMPONENT_PRE_TEST_ACTION |
|
45 |
* COMPONENT_POST_TEST_ACTION |
|
46 |
|
|
47 |
If component specific make targets need to be used for build or install or |
|
48 |
test, they can be specified via the following. |
|
49 |
* COMPONENT_BUILD_TARGETS is not usually set because the default target of most |
|
50 |
open source software is the equivalent of a 'build' target. This needs to be |
|
51 |
set when building the software requires a different target than the default. |
|
52 |
You should not override make macros here, but in COMPONENT_BUILD_ARGS. |
|
53 |
* COMPONENT_INSTALL_TARGETS has a default value of "install". Very few |
|
54 |
components need to alter this. |
|
55 |
* COMPONENT_TEST_TARGETS has a default value of "check". Several components |
|
56 |
need to set this to "test". |
|
57 |
|
|
58 |
* COMPONENT_BUILD_ARGS is probably the mostly useful variable here for solving |
|
59 |
subtle build issues. When you need to override a MACRO set in the native |
|
60 |
Makefile of a component, do so by adding something like: |
|
61 |
COMPONENT_BUILD_ARGS += MKDIR="$(MKDIR)" |
|
62 |
Quoting is often important because values with white-space can be split up, |
|
63 |
yielding the wrong results. |
|
64 |
* COMPONENT_BUILD_ENV is for when you just need to override things in the |
|
65 |
calling environment, like PATH. |
|
66 |
* COMPONENT_INSTALL_ARGS is mainly used for altering target directories. |
|
67 |
* COMPONENT_INSTALL_ENV is mainly used for altering target directories. |
|
68 |
* COMPONENT_TEST_ARGS is little used. |
|
69 |
* COMPONENT_TEST_ENV is mainly used for altering PATH and friends. |
|
70 |
|
8d70f8
|
71 |
If your component needs to do some kind of cleanup after a "gmake test" run, |
RB |
72 |
such as kill processes after doing a "gmake test" run, then this can be done |
|
73 |
by setting COMPONENT_TEST_CLEANUP. |
|
74 |
|
|
75 |
If you have created master test results file(s) for your component in the |
|
76 |
COMPONENT_TEST_RESULTS_DIR directory, then in order to successfully compare |
|
77 |
your test results against that master results file, you might need to |
|
78 |
normalize some of the test output lines. This is done via a set of regular |
|
79 |
expressions that are applied to the test results. There are some global |
|
80 |
default ones in the COMPONENT_TEST_TRANSFORMS definition in shared-macros.mk, |
|
81 |
but your component Makefile might have to += some more for specific transforms |
|
82 |
that need to be applied to the test output for just this component. |
|
83 |
|
487725
|
84 |
* COMPONENT_POST_UNPACK_ACTION is for making minor alterations to the unpacked |
JB |
85 |
source directory before any patching has taken place. It should almost never |
|
86 |
be used. |
|
87 |
* COMPONENT_PREP_ACTION is used to make alterations to the unpacked and patched |
|
88 |
source. It should be used with care. |
|
89 |
|
|
90 |
* CONFIGURE_DEFAULT_DIRS should be "yes" or "no". A value of "yes" (the |
|
91 |
default) will trigger the following being passed to CONFIGURE_OPTIONS as |
|
92 |
parameters to corresponding options. |
|
93 |
* CONFIGURE_BINDIR is the value for the --bindir= option. |
|
94 |
* CONFIGURE_LIBDIR is the value for the --libdir= option. |
|
95 |
* CONFIGURE_MANDIR is the value for the --mandir= option. |
|
96 |
* CONFIGURE_SBINDIR is the value for the --sbindir= option. |
|
97 |
* CONFIGURE_ENV is mainly used for passing CFLAGS and other common Makefile |
|
98 |
variables to configure. When should this be used as opposed to |
|
99 |
CONFIGURE_OPTIONS and COMPONENT_BUILD_{ARGS,ENV}? In general, you want |
|
100 |
to tell configure how to build the software using CONFIGURE_OPTIONS. But |
|
101 |
sometimes you need to pass values in via the calling environment. On rare |
|
102 |
occasions, you still need to do things like override MACRO settings in the |
|
103 |
generated Makefiles with COMPONENT_BUILD_ARGS. |
|
104 |
* CONFIGURE_LOCALEDIR is a cousin of the other *DIR variables above, but |
|
105 |
rarely used and hence not triggered by CONFIGURE_DEFAULT_DIRS. |
|
106 |
* CONFIGURE_OPTIONS is extremely useful, possibly our most used "add-on" |
|
107 |
variable, for passing various options to configure. These tend to vary per |
|
108 |
component, but --enable-foo and --disable-foo for various values of foo are |
|
109 |
quite common. |
|
110 |
* CONFIGURE_PREFIX is the prefix for the various *DIR variables above. Its |
|
111 |
default is "/usr"; set it if some other value (e.g., "/usr/gnu") is needed. |
|
112 |
* CONFIGURE_SCRIPT should be set if the default "$(SOURCE_DIR)/configure" is |
|
113 |
unsuitable for whatever reason. |
58b67e
|
114 |
|
bc9b99
|
115 |
* gcc_OPT has a default value of "-O3". Occasional bugs in the optimizer |
AP |
116 |
have been found which have required altering this to "-O2" or lower values. |
|
117 |
There are also gcc_OPT.$(MACH).$(BITS) versions of this available if |
|
118 |
greater specificity is needed. |
c5572a
|
119 |
|
e5ce0b
|
120 |
* Variable PYTHON3_SOABI selects between two library naming schemes of |
AP |
121 |
python3 extensions: *.cpython3Xm.so ("cpython") or *.abi3.so ("abi3"). |
|
122 |
Currently, only a few components use ABI3 compliant extensions, |
|
123 |
therefore, the default value is set to "cpython". |
|
124 |
|
c5572a
|
125 |
If you frequently rebuild the same code, such as when you maintain a build server |
JK |
126 |
or iterate recipes for the same component, you can benefit by caching the build |
|
127 |
products with "ccache" - so for repeated input conditions you'd get same output |
|
128 |
objects quickly. |
|
129 |
|
|
130 |
Being experimental, the "ccache" integration in OI-Userland build system is |
|
131 |
disabled by default. See below for hints how to enable and optionally configure it. |
|
132 |
|
|
133 |
* To enable the "ccache" integration in OI-Userland build system you must |
|
134 |
`export ENABLE_CCACHE=true` in the calling shell, or set the make-variable |
|
135 |
like this: `gmake ENABLE_CCACHE=true build` |
|
136 |
* The "ccache" program supports an inverted toggle CCACHE_DISABLE, which our |
|
137 |
shared-macros.mk Makefile also honours. By original project's intent, if you |
|
138 |
execute "ccache" then you want it to do its job. If you are debugging it or |
|
139 |
unsure if it causes problems, you can easily temporarily disable the "ccache" |
|
140 |
logic by `export CCACHE_DISABLE=true` so it quickly calls the real compiler. |
|
141 |
So to enable the caching feature you can also `export CCACHE_DISABLE=false`. |
|
142 |
* In case of conflicting environtment and/or makefile variables regarding this |
|
143 |
feature, any explicit request to disable use of "ccache" takes precedence. |
|
144 |
* With default settings (only `ENABLE_CCACHE=true` in place), the cache and |
|
145 |
non-volatile configuration will be kept in your `$HOME/.ccache` subdirectory. |
|
146 |
* To trace progress of "ccache" with your userland component build, you can |
|
147 |
instrument the compilation-wrapper scripts in `tools/ccache-wrap` directory |
|
148 |
(then `ccache -p` can be helpful to inspect actual parsing of configuration), |
|
149 |
and/or use `export CCACHE_LOGFILE=/tmp/ccache.log` to trace its activities. |
|
150 |
* You can dedicate a cache directory different from the default `$HOME/.ccache` |
|
151 |
for example with `export CCACHE_DIR=/tmp/ccache-dir; mkdir -p $CCACHE_DIR`. |
fcf34c
|
152 |
* Note: be wary of ccache's own CCACHE_DISABLE environment variable: any |
JK |
153 |
value (empty, "false" etc.) is considered a "true" setting for ccache |
|
154 |
booleans (and so CCACHE_DISABLE=false still disables the program, falling |
|
155 |
through to real compiler). This is according to the project's documentation |
|
156 |
and legacy (backwards compatibility), thus not accepted by upstream as a bug. |
|
157 |
To negate ccache boolean environment variable settings you can use their |
|
158 |
CCACHE_NO* counterparts, e.g. `export CCACHE_NODISABLE=anything`. |
c5572a
|
159 |
* Troubleshooting: If no files appear in the cache, verify permissions and disk |
JK |
160 |
space. Also enable the log file and/or inspect configuration with `ccache -p` |
|
161 |
(see above) to see details about wrapped compilations. In particular, |
|
162 |
"ccache" might not actually cache the build products if the file types are |
|
163 |
unsupported (see the `man ccache` page for options on extending the support), |
|
164 |
if files are detected to have dynamic contents (e.g. `__TIME__` and similar |
|
165 |
macros), or when a build product is comprised of several source files (like |
|
166 |
running `gcc -o binprog *.c`). |
|
167 |
* You can inspect caching statistics with `ccache -s` and wipe the cache with |
|
168 |
`ccache -C -z`. |
fcf34c
|
169 |
* For debugging or development of the ccache component itself, you can use a |
JK |
170 |
custom build for oi-userland compilation with `export CCACHE=/path/to/ccache` |
c5572a
|
171 |
* The cache directory can contain a configuration file for "ccache" program, |
JK |
172 |
which is the recommended way to provide tweaks to your setup. While exported |
|
173 |
environment variables (e.g. from shell profile) may work, our Makefiles do |
|
174 |
not make any guarantees about passing each and every possible variable into |
|
175 |
sub-processes. We do make a best effort to pass the variables listed above. |
|
176 |
* See `man ccache` for more details about the program and its configuration. |
|
177 |
|