ckms.ini(5)
ckms.ini - package configuration files of CKMS
CKMS reads two kinds of configuration files. This is the configuration file for the package, which describes its metadata and a build recipe. There is also the global configuration file, which may additionally influence builds.
Typically this is ckms.ini located in the package's kernel module source tree. It can also be supplied externally, however, during the add step.
Both types of configuration use ini files, with syntax as defined by Python's ConfigParser, with the default configuration. Value interpolation can be used as specified by Python, with %(foo) referring to either another field in the same section, or a field of the general section.
Package config files have multiple sections.
general This describes the metadata of the package. This is the default section, which means interpolation of fields from this section will work in every other section, alongside the own values of the section.
hooks Hooks are simple shell snippets that are invoked during different phases of the module build.
module.NAME Module sections describe individual kernel modules that are the result of the build.
There are several metadata fields that can be set in the general section.
name (string) This is the mandatory package name. An example would be zfs.
version (string) This is the mandatory package version. An example would be 2.0.5.
strip (bool) Whether to have CKMS strip the modules. Optional and yes by default.
make (string) The make command to use when building the module. Exposed into the build environment as the MAKE variable. Optional, with the default being gmake. This value is special, because if gmake does not exist in the system and make is determined to be GNU make, it will be used instead. This means you can use gmake and have it portably default to GNU make, regardless of whether it's called gmake or just make in the system.
initramfs (bool) Whether this module is to be a part of initramfs. Optional and defaults to no. If set to yes, it will result in the initramfs hook being called upon (un)installation.
There are multiple hooks which describe a build recipe. They are just simple shell snippets (executed with the system /bin/sh). Return codes other than 0 in any hook will result in an error. Most hooks are optional, but build must always be present.
Hook output is logged to a log file, and may be printed to standard output as well unless the invocation is quiet.
configure This hook is used to configure the package for build. For example in packages with an Autotools-based build system, this would typically run the configure script.
pre_build Run before the actual build.
build This is the mandatory hook that will build the module(s).
post_build Run after the build.
Each resulting kernel module will have its own section. There are some mandatory fields as well as some optional ones. The section name must be the string module.MODNAME where MODNAME is the module name without any extension.
path (string) This is the path in the build directory which contains the built module. That means the built module is in BUILD_DIR/path/MODNAME.ko. Mandatory.
dest (string) This is the path in the kernel's modules directory where the module will be installed. To make an example, the final module may end up in /lib/modules/dest/MODNAME.ko.
strip (bool) This can be used to control stripping in a fine-grained way. All modules that do not explicitly say will follow the global package setting. Modules that do set it will have their own behavior.
The general section has some implicit fields that are set by CKMS, and those can be referenced from other fields using the standard interpolation.
ckms_statedir The state directory of CKMS (i.e. /var/lib/ckms).
ckms_destdir The destination directory of CKMS (i.e. /lib/modules).
kernel_hdrdir The path to kernel headers for the given kernel.
kernel_machine The kernel architecture, i.e. uname -m.
kernel_arch The kernel source tree architecture, i.e. what you would pass as ARCH. Not the same as machine, e.g. for ppc64le this is powerpc.
kernel_version The kernel version.
Hooks are executed with a specific shell environment. The environment may be additionally overridden by the global configuration file of CKMS, which needs to be used with care.
PATH The system PATH, passed through from the CKMS invocation.
MAKE The make implementation, typically gmake or make, as decided by CKMS.
SHELL This is always /bin/sh.
CKMS_PACKAGE_NAME The package name from the metadata.
CKMS_PACKAGE_VERSION The package version from the metadata.
CKMS_JOBS The number of build jobs to use.
CKMS_STATEDIR The state directory of CKMS (i.e. /var/lib/ckms).
CKMS_DESTDIR The destination directory of CKMS (i.e. /lib/modules).
CKMS_DEPMOD If running depmod is enabled, this is set to 1.
CKMS_KERNEL_HDRDIR The path to kernel headers for the given kernel.
CKMS_KERNEL_VERSION The kernel version.
CKMS_KERNEL_MACHINE The kernel architecture, i.e. uname -m.
CKMS_KERNEL_ARCH The kernel source tree architecture, i.e. what you would pass as ARCH. Not the same as machine, e.g. for ppc64le this is powerpc.
CKMS_MAKE_ARGS The arguments to pass to MAKE. This is a mixture of implicit make arguments constructed by CKMS, followed by global arguments that are specified in the CKMS global configuration file.
LLVM This is set to 1 if a kernel config file is located and the system infers that it was built with Clang. Otherwise, it will be unset.
LLVM_IAS If a kernel config file is located and the system infers that GNU assembler was used to link, this is set to 0. Otherwise, if Clang was used (i.e. LLVM is set to 1), this will also be set to 1. In any other case, this will be unset.
LD If a config file for the kernel is located, this is set to the linker used for the kernel, with ld.lld and ld.bfd being currently supported. Not set if an unknown linker was used.
CKMS will usually try to construct some implicit make arguments. This will be done particularly when a kernel configuration file for the given kernel can be found.
These arguments are currently constructed.
LLVM=1 Added if Clang was used to build the kernel.
LLVM_IAS=0 Set if GNU assembler was used for the kernel.
LLVM_IAS=1 Set if Clang's integrated assembler was used for the kernel.
LD=ld.bfd Added if the BFD linker was used for the kernel.
LD=ld.lld Added if the LLD linker was used for the kernel.
ckms-config.ini(5), ckms(8)