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