OpenIndiana Userland
view | history | commit | commitdiff
Marcel Telka
2024-04-06 c028ccd8bf35334f2185c77b3d42e6cd4e78af1f
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