From: Daan De Meyer Date: Tue, 10 Sep 2024 10:02:12 +0000 (+0200) Subject: Introduce new Build section and move various settings to it X-Git-Tag: v25~308^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ef5a79993e2af5d6b9feaa6103d84b19ce2100d3;p=thirdparty%2Fmkosi.git Introduce new Build section and move various settings to it --- diff --git a/mkosi/config.py b/mkosi/config.py index 32c78ef9a..a1e8ac762 100644 --- a/mkosi/config.py +++ b/mkosi/config.py @@ -1434,8 +1434,6 @@ class Config: repository_key_check: bool repository_key_fetch: bool repositories: list[str] - cacheonly: Cacheonly - sandbox_trees: list[ConfigTree] output_format: OutputFormat manifest_format: list[ManifestFormat] @@ -1443,18 +1441,12 @@ class Config: compress_output: Compression compress_level: int output_dir: Optional[Path] - workspace_dir: Optional[Path] - cache_dir: Optional[Path] - package_cache_dir: Optional[Path] - build_dir: Optional[Path] image_id: Optional[str] image_version: Optional[str] split_artifacts: bool repart_dirs: list[Path] sector_size: Optional[int] - repart_offline: bool overlay: bool - use_subvolumes: ConfigFeature seed: uuid.UUID packages: list[str] @@ -1537,25 +1529,34 @@ class Config: sign: bool key: Optional[str] + tools_tree: Optional[Path] + tools_tree_distribution: Optional[Distribution] + tools_tree_release: Optional[str] + tools_tree_mirror: Optional[str] + tools_tree_repositories: list[str] + tools_tree_sandbox_trees: list[ConfigTree] + tools_tree_packages: list[str] + tools_tree_certificates: bool + incremental: bool + cacheonly: Cacheonly + sandbox_trees: list[ConfigTree] + workspace_dir: Optional[Path] + cache_dir: Optional[Path] + package_cache_dir: Optional[Path] + build_dir: Optional[Path] + use_subvolumes: ConfigFeature + repart_offline: bool + proxy_url: Optional[str] proxy_exclude: list[str] proxy_peer_certificate: Optional[Path] proxy_client_certificate: Optional[Path] proxy_client_key: Optional[Path] - incremental: bool nspawn_settings: Optional[Path] extra_search_paths: list[Path] ephemeral: bool credentials: dict[str, str] kernel_command_line_extra: list[str] - tools_tree: Optional[Path] - tools_tree_distribution: Optional[Distribution] - tools_tree_release: Optional[str] - tools_tree_mirror: Optional[str] - tools_tree_repositories: list[str] - tools_tree_sandbox_trees: list[ConfigTree] - tools_tree_packages: list[str] - tools_tree_certificates: bool runtime_trees: list[ConfigTree] runtime_size: Optional[int] runtime_scratch: ConfigFeature @@ -2001,29 +2002,6 @@ SETTINGS = ( help="Repositories to use", scope=SettingScope.universal, ), - ConfigSetting( - dest="cacheonly", - long="--cache-only", - name="CacheOnly", - section="Distribution", - parse=config_make_enum_parser_with_boolean(Cacheonly, yes=Cacheonly.always, no=Cacheonly.auto), - default=Cacheonly.auto, - help="Only use the package cache when installing packages", - choices=Cacheonly.choices(), - scope=SettingScope.universal, - ), - ConfigSetting( - dest="sandbox_trees", - long="--sandbox-tree", - compat_names=("PackageManagerTrees",), - compat_longs=("--package-manager-tree",), - metavar="PATH", - section="Distribution", - parse=config_make_list_parser(delimiter=",", parse=make_tree_parser(required=True)), - help="Use a sandbox tree to configure the various tools that mkosi executes", - paths=("mkosi.sandbox", "mkosi.sandbox.tar", "mkosi.pkgmngr", "mkosi.pkgmngr.tar",), - scope=SettingScope.universal, - ), ConfigSetting( dest="output_format", @@ -2089,44 +2067,6 @@ SETTINGS = ( help="Output directory", scope=SettingScope.universal, ), - ConfigSetting( - dest="workspace_dir", - metavar="DIR", - name="WorkspaceDirectory", - section="Output", - parse=config_make_path_parser(required=False), - help="Workspace directory", - scope=SettingScope.universal, - ), - ConfigSetting( - dest="cache_dir", - metavar="PATH", - name="CacheDirectory", - section="Output", - parse=config_make_path_parser(required=False), - paths=("mkosi.cache",), - help="Incremental cache directory", - scope=SettingScope.universal, - ), - ConfigSetting( - dest="package_cache_dir", - metavar="PATH", - name="PackageCacheDirectory", - section="Output", - parse=config_make_path_parser(required=False), - help="Package cache directory", - scope=SettingScope.universal, - ), - ConfigSetting( - dest="build_dir", - metavar="PATH", - name="BuildDirectory", - section="Output", - parse=config_make_path_parser(required=False), - paths=("mkosi.builddir",), - help="Path to use as persistent build directory", - scope=SettingScope.universal, - ), ConfigSetting( dest="image_version", match=config_match_version, @@ -2170,14 +2110,6 @@ SETTINGS = ( help="Set the disk image sector size", scope=SettingScope.inherit, ), - ConfigSetting( - dest="repart_offline", - section="Output", - parse=config_parse_boolean, - help="Build disk images without using loopback devices", - default=True, - scope=SettingScope.universal, - ), ConfigSetting( dest="overlay", metavar="BOOL", @@ -2186,15 +2118,6 @@ SETTINGS = ( parse=config_parse_boolean, help="Only output the additions on top of the given base trees", ), - ConfigSetting( - dest="use_subvolumes", - metavar="FEATURE", - nargs="?", - section="Output", - parse=config_parse_feature, - help="Use btrfs subvolumes for faster directory operations where possible", - scope=SettingScope.universal, - ), ConfigSetting( dest="seed", metavar="UUID", @@ -2790,6 +2713,168 @@ SETTINGS = ( help="GPG key to use for signing", ), + ConfigSetting( + dest="tools_tree", + metavar="PATH", + section="Build", + parse=config_make_path_parser(constants=("default",)), + paths=("mkosi.tools",), + help="Look up programs to execute inside the given tree", + nargs="?", + const="default", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="tools_tree_distribution", + section="Build", + parse=config_make_enum_parser(Distribution), + match=config_make_enum_matcher(Distribution), + choices=Distribution.choices(), + default_factory_depends=("distribution",), + default_factory=config_default_tools_tree_distribution, + help="Set the distribution to use for the default tools tree", + ), + ConfigSetting( + dest="tools_tree_release", + metavar="RELEASE", + section="Build", + parse=config_parse_string, + default_factory_depends=("tools_tree_distribution",), + default_factory=lambda ns: d.default_release() if (d := ns.tools_tree_distribution) else None, + help="Set the release to use for the default tools tree", + ), + ConfigSetting( + dest="tools_tree_mirror", + metavar="MIRROR", + section="Build", + default_factory_depends=("distribution", "mirror", "tools_tree_distribution"), + default_factory=lambda ns: ns.mirror if ns.mirror and ns.distribution == ns.tools_tree_distribution else None, + help="Set the mirror to use for the default tools tree", + ), + ConfigSetting( + dest="tools_tree_repositories", + long="--tools-tree-repository", + metavar="REPOS", + section="Build", + parse=config_make_list_parser(delimiter=","), + help="Repositories to use for the default tools tree", + ), + ConfigSetting( + dest="tools_tree_sandbox_trees", + long="--tools-tree-sandbox-tree", + compat_names=("ToolsTreePackageManagerTrees",), + compat_longs=("--tools-tree-package-manager-tree",), + metavar="PATH", + section="Build", + parse=config_make_list_parser(delimiter=",", parse=make_tree_parser(required=True)), + help="Sandbox trees for the default tools tree", + ), + ConfigSetting( + dest="tools_tree_packages", + long="--tools-tree-package", + metavar="PACKAGE", + section="Build", + parse=config_make_list_parser(delimiter=","), + help="Add additional packages to the default tools tree", + ), + ConfigSetting( + dest="tools_tree_certificates", + metavar="BOOL", + section="Build", + parse=config_parse_boolean, + help="Use certificates from the tools tree", + default=True, + scope=SettingScope.universal, + ), + ConfigSetting( + dest="incremental", + short="-i", + metavar="BOOL", + nargs="?", + section="Build", + parse=config_parse_boolean, + help="Make use of and generate intermediary cache images", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="cacheonly", + long="--cache-only", + name="CacheOnly", + section="Build", + parse=config_make_enum_parser_with_boolean(Cacheonly, yes=Cacheonly.always, no=Cacheonly.auto), + default=Cacheonly.auto, + help="Only use the package cache when installing packages", + choices=Cacheonly.choices(), + scope=SettingScope.universal, + ), + ConfigSetting( + dest="sandbox_trees", + long="--sandbox-tree", + compat_names=("PackageManagerTrees",), + compat_longs=("--package-manager-tree",), + metavar="PATH", + section="Build", + parse=config_make_list_parser(delimiter=",", parse=make_tree_parser(required=True)), + help="Use a sandbox tree to configure the various tools that mkosi executes", + paths=("mkosi.sandbox", "mkosi.sandbox.tar", "mkosi.pkgmngr", "mkosi.pkgmngr.tar",), + scope=SettingScope.universal, + ), + ConfigSetting( + dest="workspace_dir", + metavar="DIR", + name="WorkspaceDirectory", + section="Build", + parse=config_make_path_parser(required=False), + help="Workspace directory", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="cache_dir", + metavar="PATH", + name="CacheDirectory", + section="Build", + parse=config_make_path_parser(required=False), + paths=("mkosi.cache",), + help="Incremental cache directory", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="package_cache_dir", + metavar="PATH", + name="PackageCacheDirectory", + section="Build", + parse=config_make_path_parser(required=False), + help="Package cache directory", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="build_dir", + metavar="PATH", + name="BuildDirectory", + section="Build", + parse=config_make_path_parser(required=False), + paths=("mkosi.builddir",), + help="Path to use as persistent build directory", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="use_subvolumes", + metavar="FEATURE", + nargs="?", + section="Build", + parse=config_parse_feature, + help="Use btrfs subvolumes for faster directory operations where possible", + scope=SettingScope.universal, + ), + ConfigSetting( + dest="repart_offline", + section="Build", + parse=config_parse_boolean, + help="Build disk images without using loopback devices", + default=True, + scope=SettingScope.universal, + ), + ConfigSetting( dest="proxy_url", section="Host", @@ -2834,16 +2919,6 @@ SETTINGS = ( help="Set the proxy client key", scope=SettingScope.universal, ), - ConfigSetting( - dest="incremental", - short="-i", - metavar="BOOL", - nargs="?", - section="Host", - parse=config_parse_boolean, - help="Make use of and generate intermediary cache images", - scope=SettingScope.universal, - ), ConfigSetting( dest="nspawn_settings", name="NSpawnSettings", @@ -2888,79 +2963,6 @@ SETTINGS = ( parse=config_make_list_parser(delimiter=" "), help="Append extra entries to the kernel command line when booting the image", ), - ConfigSetting( - dest="tools_tree", - metavar="PATH", - section="Host", - parse=config_make_path_parser(constants=("default",)), - paths=("mkosi.tools",), - help="Look up programs to execute inside the given tree", - nargs="?", - const="default", - scope=SettingScope.universal, - ), - ConfigSetting( - dest="tools_tree_distribution", - section="Host", - parse=config_make_enum_parser(Distribution), - match=config_make_enum_matcher(Distribution), - choices=Distribution.choices(), - default_factory_depends=("distribution",), - default_factory=config_default_tools_tree_distribution, - help="Set the distribution to use for the default tools tree", - ), - ConfigSetting( - dest="tools_tree_release", - metavar="RELEASE", - section="Host", - parse=config_parse_string, - default_factory_depends=("tools_tree_distribution",), - default_factory=lambda ns: d.default_release() if (d := ns.tools_tree_distribution) else None, - help="Set the release to use for the default tools tree", - ), - ConfigSetting( - dest="tools_tree_mirror", - metavar="MIRROR", - section="Host", - default_factory_depends=("distribution", "mirror", "tools_tree_distribution"), - default_factory=lambda ns: ns.mirror if ns.mirror and ns.distribution == ns.tools_tree_distribution else None, - help="Set the mirror to use for the default tools tree", - ), - ConfigSetting( - dest="tools_tree_repositories", - long="--tools-tree-repository", - metavar="REPOS", - section="Host", - parse=config_make_list_parser(delimiter=","), - help="Repositories to use for the default tools tree", - ), - ConfigSetting( - dest="tools_tree_sandbox_trees", - long="--tools-tree-sandbox-tree", - compat_names=("ToolsTreePackageManagerTrees",), - compat_longs=("--tools-tree-package-manager-tree",), - metavar="PATH", - section="Host", - parse=config_make_list_parser(delimiter=",", parse=make_tree_parser(required=True)), - help="Sandbox trees for the default tools tree", - ), - ConfigSetting( - dest="tools_tree_packages", - long="--tools-tree-package", - metavar="PACKAGE", - section="Host", - parse=config_make_list_parser(delimiter=","), - help="Add additional packages to the default tools tree", - ), - ConfigSetting( - dest="tools_tree_certificates", - metavar="BOOL", - section="Host", - parse=config_parse_boolean, - help="Use certificates from the tools tree", - default=True, - scope=SettingScope.universal, - ), ConfigSetting( dest="runtime_trees", long="--runtime-tree", @@ -4167,8 +4169,6 @@ def summary(config: Config) -> str: Repo Signature/Key check: {yes_no(config.repository_key_check)} Fetch Repository Keys: {yes_no(config.repository_key_fetch)} Repositories: {line_join_list(config.repositories)} - Use Only Package Cache: {config.cacheonly} - Sandbox Trees: {line_join_list(config.sandbox_trees)} {bold("OUTPUT")}: Output Format: {config.output_format} @@ -4177,18 +4177,12 @@ def summary(config: Config) -> str: Compression: {config.compress_output} Compression Level: {config.compress_level} Output Directory: {config.output_dir_or_cwd()} - Workspace Directory: {config.workspace_dir_or_default()} - Cache Directory: {none_to_none(config.cache_dir)} - Package Cache Directory: {none_to_default(config.package_cache_dir)} - Build Directory: {none_to_none(config.build_dir)} Image ID: {config.image_id} Image Version: {config.image_version} Split Artifacts: {yes_no(config.split_artifacts)} Repart Directories: {line_join_list(config.repart_dirs)} Sector Size: {none_to_default(config.sector_size)} - Repart Offline: {yes_no(config.repart_offline)} Overlay: {yes_no(config.overlay)} - Use Subvolumes: {config.use_subvolumes} Seed: {none_to_random(config.seed)} Clean Scripts: {line_join_list(config.clean_scripts)} @@ -4281,25 +4275,36 @@ def summary(config: Config) -> str: summary += f"""\ + {bold("BUILD CONFIGURATION")}: + Tools Tree: {config.tools_tree} + Tools Tree Distribution: {none_to_none(config.tools_tree_distribution)} + Tools Tree Release: {none_to_none(config.tools_tree_release)} + Tools Tree Mirror: {none_to_default(config.tools_tree_mirror)} + Tools Tree Repositories: {line_join_list(config.tools_tree_repositories)} + Tools Tree Sandbox Trees: {line_join_list(config.tools_tree_sandbox_trees)} + Tools Tree Packages: {line_join_list(config.tools_tree_packages)} + Tools Tree Certificates: {yes_no(config.tools_tree_certificates)} + + Incremental: {yes_no(config.incremental)} + Use Only Package Cache: {config.cacheonly} + Sandbox Trees: {line_join_list(config.sandbox_trees)} + Workspace Directory: {config.workspace_dir_or_default()} + Cache Directory: {none_to_none(config.cache_dir)} + Package Cache Directory: {none_to_default(config.package_cache_dir)} + Build Directory: {none_to_none(config.build_dir)} + Use Subvolumes: {config.use_subvolumes} + Repart Offline: {yes_no(config.repart_offline)} + {bold("HOST CONFIGURATION")}: Proxy URL: {none_to_none(config.proxy_url)} Proxy Peer Certificate: {none_to_none(config.proxy_peer_certificate)} Proxy Client Certificate: {none_to_none(config.proxy_client_certificate)} Proxy Client Key: {none_to_none(config.proxy_client_key)} - Incremental: {yes_no(config.incremental)} NSpawn Settings: {none_to_none(config.nspawn_settings)} Extra Search Paths: {line_join_list(config.extra_search_paths)} Ephemeral: {config.ephemeral} Credentials: {line_join_list(config.credentials.keys())} Extra Kernel Command Line: {line_join_list(config.kernel_command_line_extra)} - Tools Tree: {config.tools_tree} - Tools Tree Distribution: {none_to_none(config.tools_tree_distribution)} - Tools Tree Release: {none_to_none(config.tools_tree_release)} - Tools Tree Mirror: {none_to_default(config.tools_tree_mirror)} - Tools Tree Repositories: {line_join_list(config.tools_tree_repositories)} - Tools Tree Sandbox Trees: {line_join_list(config.tools_tree_sandbox_trees)} - Tools Tree Packages: {line_join_list(config.tools_tree_packages)} - Tools Tree Certificates: {yes_no(config.tools_tree_certificates)} Runtime Trees: {line_join_list(config.runtime_trees)} Runtime Size: {format_bytes_or_none(config.runtime_size)} Runtime Scratch: {config.runtime_scratch} diff --git a/mkosi/resources/man/mkosi.md b/mkosi/resources/man/mkosi.md index 269cdaa68..c4aa54db3 100644 --- a/mkosi/resources/man/mkosi.md +++ b/mkosi/resources/man/mkosi.md @@ -485,32 +485,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, : Enable package repositories that are disabled by default. This can be used to enable the EPEL repos for CentOS or different components of the Debian/Kali/Ubuntu repositories. -`CacheOnly=`, `--cache-only=` -: Takes one of `auto`, `metadata`, `always` or `never`. Defaults to - `auto`. If `always`, the package manager is instructed not to contact - the network. This provides a minimal level of reproducibility, as long - as the package cache is already fully populated. If set to `metadata`, - the package manager can still download packages, but we won't sync the - repository metadata. If set to `auto`, the repository metadata is - synced unless we have a cached image (see `Incremental=`) and packages - can be downloaded during the build. If set to `never`, repository - metadata is always synced and and packages can be downloaded during - the build. - -`SandboxTrees=`, `--sandbox-tree=` -: Takes a comma separated list of colon separated path pairs. The first - path of each pair refers to a directory to copy into the mkosi - sandbox before executing a tool. If the `mkosi.sandbox/` directory - is found in the local directory it is used for this purpose with the - root directory as target (also see the **Files** section below). - - `mkosi` will look for the package manager configuration and related - files in the configured sandbox trees. Unless specified otherwise, - it will use the configuration files from their canonical locations - in `/usr` or `/etc` in the sandbox trees. For example, it will look - for `/etc/dnf/dnf.conf` in the sandbox trees if `dnf` is used to - install packages. - ### [Output] Section `Format=`, `--format=`, `-t` @@ -579,43 +553,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, not specified and the directory `mkosi.output/` exists in the local directory, it is automatically used for this purpose. -`WorkspaceDirectory=`, `--workspace-dir=` -: Path to a directory where to store data required temporarily while - building the image. This directory should have enough space to store - the full OS image, though in most modes the actually used disk space - is smaller. If not specified, a subdirectory of `$XDG_CACHE_HOME` (if - set), `$HOME/.cache` (if set) or `/var/tmp` is used. - - The data in this directory is removed automatically after each - build. It's safe to manually remove the contents of this directory - should an `mkosi` invocation be aborted abnormally (for example, due - to reboot/power failure). - -`CacheDirectory=`, `--cache-dir=` -: Takes a path to a directory to use as the incremental cache directory - for the incremental images produced when the `Incremental=` option is - enabled. If this option is not used, but a `mkosi.cache/` directory is - found in the local directory it is automatically used for this - purpose. - -`PackageCacheDirectory=`, `--package-cache-dir` -: Takes a path to a directory to use as the package cache directory for - the distribution package manager used. If unset, a suitable directory - in the user's home directory or system is used. - -`BuildDirectory=`, `--build-dir=` -: Takes a path to a directory to use as the build directory for build - systems that support out-of-tree builds (such as Meson). The directory - used this way is shared between repeated builds, and allows the build - system to reuse artifacts (such as object files, executable, …) - generated on previous invocations. The build scripts can find the path - to this directory in the `$BUILDDIR` environment variable. This - directory is mounted into the image's root directory when - `mkosi-chroot` is invoked during execution of the build scripts. If - this option is not specified, but a directory `mkosi.builddir/` exists - in the local directory it is automatically used for this purpose (also - see the **Files** section below). - `ImageVersion=`, `--image-version=` : Configure the image version. This accepts any string, but it is recommended to specify a series of dot separated components. The @@ -659,25 +596,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, : Override the default sector size that systemd-repart uses when building a disk image. -`RepartOffline=`, `--repart-offline=` -: Specifies whether to build disk images using loopback devices. Enabled - by default. When enabled, `systemd-repart` will not use loopback - devices to build disk images. When disabled, `systemd-repart` will - always use loopback devices to build disk images. - - Note that when using `RepartOffline=no` mkosi cannot run unprivileged and - the image build has to be done as the root user outside of any - containers and with loopback devices available on the host system. - - There are currently two known scenarios where `RepartOffline=no` has to be - used. The first is when using `Subvolumes=` in a repart partition - definition file, as subvolumes cannot be created without using - loopback devices. The second is when creating a system with SELinux - and an XFS root partition. Because `mkfs.xfs` does not support - populating an XFS filesystem with extended attributes, loopback - devices have to be used to ensure the SELinux extended attributes end - up in the generated XFS filesystem. - `Overlay=`, `--overlay` : When used together with `BaseTrees=`, the output will consist only out of changes to the specified base trees. Each base tree is attached as a lower @@ -688,15 +606,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, This option may be used to create [systemd *system extensions* or *portable services*](https://uapi-group.org/specifications/specs/extension_image). -`UseSubvolumes=`, `--use-subvolumes=` -: Takes a boolean or `auto`. Enables or disables use of btrfs subvolumes for - directory tree outputs. If enabled, mkosi will create the root directory as - a btrfs subvolume and use btrfs subvolume snapshots where possible to copy - base or cached trees which is much faster than doing a recursive copy. If - explicitly enabled and `btrfs` is not installed or subvolumes cannot be - created, an error is raised. If `auto`, missing `btrfs` or failures to - create subvolumes are ignored. - `Seed=`, `--seed=` : Takes a UUID as argument or the special value `random`. Overrides the seed that [`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html) @@ -1255,6 +1164,227 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, : Select the `gpg` key to use for signing `SHA256SUMS`. This key must be already present in the `gpg` keyring. +### [Build] Section + +`ToolsTree=`, `--tools-tree=` +: If specified, programs executed by mkosi to build and boot an image + are looked up inside the given tree instead of in the host system. Use + this option to make image builds more reproducible by always using the + same versions of programs to build the final image instead of whatever + version is installed on the host system. If this option is not used, + but the `mkosi.tools/` directory is found in the local directory it is + automatically used for this purpose with the root directory as target. + + Note if a binary is found in any of the paths configured with + `ExtraSearchPaths=`, the binary will be executed on the host. + + If set to `default`, mkosi will automatically add an extra tools tree + image and use it as the tools tree. + + Note that mkosi will only build a single default tools tree per build, + even if multiple images are defined in `mkosi.images` with + `ToolsTree=default`. The settings of the "last" image will apply to + the default tools tree (usually the image defined last in + mkosi.images and without any dependencies on other images). + + The following table shows for which distributions default tools tree + packages are defined and which packages are included in those default + tools trees: + + | | Fedora | CentOS | Debian | Kali | Ubuntu | Arch | openSUSE | + |-------------------------|:------:|:------:|:------:|:----:|:------:|:----:|:--------:| + | `acl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `apt` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `archlinux-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `attr` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `bash` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `btrfs-progs` | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | + | `bubblewrap` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `ca-certificates` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `coreutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `cpio` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `curl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `debian-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `diffutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `distribution-gpg-keys` | ✓ | ✓ | | | | ✓ | ✓ | + | `dnf` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `dnf-plugins-core` | ✓ | ✓ | | | | | ✓ | + | `dnf5` | ✓ | | | | | | | + | `dnf5-plugins` | ✓ | | | | | | | + | `dosfstools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `e2fsprogs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `edk2-ovmf` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `erofs-utils` | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | + | `findutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `git` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `grep` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `grub-tools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `jq` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `kali-archive-keyring` | | | | ✓ | | | | + | `kmod` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `less` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `mtools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `nano` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `openssh` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `openssl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `sed` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `pacman` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `pesign` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `policycoreutils` | ✓ | ✓ | ✓ | ✓ | ✓ | | ✓ | + | `qemu` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `sbsigntools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `socat` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `squashfs-tools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `strace` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `swtpm` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `systemd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `ukify` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `tar` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `ubuntu-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | + | `util-linux` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `virtiofsd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `virt-firmware` | ✓ | ✓ | | | | ✓ | | + | `xfsprogs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `xz` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `zstd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | + | `zypper` | ✓ | | ✓ | ✓ | ✓ | ✓ | | + +`ToolsTreeDistribution=`, `--tools-tree-distribution=` +: Set the distribution to use for the default tools tree. By default, + the same distribution as the image that's being built is used, except + for CentOS and Ubuntu images, in which case Fedora and Debian are used + respectively. + +`ToolsTreeRelease=`, `--tools-tree-release=` +: Set the distribution release to use for the default tools tree. By + default, the hardcoded default release in mkosi for the distribution + is used. + +`ToolsTreeMirror=`, `--tools-tree-mirror=` +: Set the mirror to use for the default tools tree. By default, the + default mirror for the tools tree distribution is used. + +`ToolsTreeRepositories=`, `--tools-tree-repository` +: Same as `Repositories=` but for the default tools tree. + +`ToolsTreeSandboxTrees=`, `--tools-tree-sandbox-tree` +: Same as `SandboxTrees=` but for the default tools tree. + +`ToolsTreePackages=`, `--tools-tree-packages=` +: Extra packages to install into the default tools tree. Takes a comma + separated list of package specifications. This option may be used + multiple times in which case the specified package lists are combined. + +`ToolsTreeCertificates=`, `--tools-tree-certificates=` +: Specify whether to use certificates and keys from the tools tree. If + enabled, `/usr/share/keyrings`, `/usr/share/distribution-gpg-keys`, + `/etc/pki`, `/etc/ssl`, `/etc/ca-certificates`, `/etc/pacman.d/gnupg` + and `/var/lib/ca-certificates` from the tools tree are used. + Otherwise, these directories are picked up from the host. + +`Incremental=`, `--incremental=`, `-i` +: Enable incremental build mode. In this mode, a copy of the OS image is + created immediately after all OS packages are installed and the + prepare scripts have executed but before the `mkosi.build` scripts are + invoked (or anything that happens after it). On subsequent invocations + of `mkosi` with the `-i` switch this cached image may be used to skip + the OS package installation, thus drastically speeding up repetitive + build times. Note that while there is some rudimentary cache + invalidation, it is definitely not perfect. In order to force + rebuilding of the cached image, combine `-i` with `-ff` to ensure the + cached image is first removed and then re-created. + +`CacheOnly=`, `--cache-only=` +: Takes one of `auto`, `metadata`, `always` or `never`. Defaults to + `auto`. If `always`, the package manager is instructed not to contact + the network. This provides a minimal level of reproducibility, as long + as the package cache is already fully populated. If set to `metadata`, + the package manager can still download packages, but we won't sync the + repository metadata. If set to `auto`, the repository metadata is + synced unless we have a cached image (see `Incremental=`) and packages + can be downloaded during the build. If set to `never`, repository + metadata is always synced and and packages can be downloaded during + the build. + +`SandboxTrees=`, `--sandbox-tree=` +: Takes a comma separated list of colon separated path pairs. The first + path of each pair refers to a directory to copy into the mkosi + sandbox before executing a tool. If the `mkosi.sandbox/` directory + is found in the local directory it is used for this purpose with the + root directory as target (also see the **Files** section below). + + `mkosi` will look for the package manager configuration and related + files in the configured sandbox trees. Unless specified otherwise, + it will use the configuration files from their canonical locations + in `/usr` or `/etc` in the sandbox trees. For example, it will look + for `/etc/dnf/dnf.conf` in the sandbox trees if `dnf` is used to + install packages. + +`WorkspaceDirectory=`, `--workspace-dir=` +: Path to a directory where to store data required temporarily while + building the image. This directory should have enough space to store + the full OS image, though in most modes the actually used disk space + is smaller. If not specified, a subdirectory of `$XDG_CACHE_HOME` (if + set), `$HOME/.cache` (if set) or `/var/tmp` is used. + + The data in this directory is removed automatically after each + build. It's safe to manually remove the contents of this directory + should an `mkosi` invocation be aborted abnormally (for example, due + to reboot/power failure). + +`CacheDirectory=`, `--cache-dir=` +: Takes a path to a directory to use as the incremental cache directory + for the incremental images produced when the `Incremental=` option is + enabled. If this option is not used, but a `mkosi.cache/` directory is + found in the local directory it is automatically used for this + purpose. + +`PackageCacheDirectory=`, `--package-cache-dir` +: Takes a path to a directory to use as the package cache directory for + the distribution package manager used. If unset, a suitable directory + in the user's home directory or system is used. + +`BuildDirectory=`, `--build-dir=` +: Takes a path to a directory to use as the build directory for build + systems that support out-of-tree builds (such as Meson). The directory + used this way is shared between repeated builds, and allows the build + system to reuse artifacts (such as object files, executable, …) + generated on previous invocations. The build scripts can find the path + to this directory in the `$BUILDDIR` environment variable. This + directory is mounted into the image's root directory when + `mkosi-chroot` is invoked during execution of the build scripts. If + this option is not specified, but a directory `mkosi.builddir/` exists + in the local directory it is automatically used for this purpose (also + see the **Files** section below). + +`UseSubvolumes=`, `--use-subvolumes=` +: Takes a boolean or `auto`. Enables or disables use of btrfs subvolumes for + directory tree outputs. If enabled, mkosi will create the root directory as + a btrfs subvolume and use btrfs subvolume snapshots where possible to copy + base or cached trees which is much faster than doing a recursive copy. If + explicitly enabled and `btrfs` is not installed or subvolumes cannot be + created, an error is raised. If `auto`, missing `btrfs` or failures to + create subvolumes are ignored. + +`RepartOffline=`, `--repart-offline=` +: Specifies whether to build disk images using loopback devices. Enabled + by default. When enabled, `systemd-repart` will not use loopback + devices to build disk images. When disabled, `systemd-repart` will + always use loopback devices to build disk images. + + Note that when using `RepartOffline=no` mkosi cannot run unprivileged and + the image build has to be done as the root user outside of any + containers and with loopback devices available on the host system. + + There are currently two known scenarios where `RepartOffline=no` has to be + used. The first is when using `Subvolumes=` in a repart partition + definition file, as subvolumes cannot be created without using + loopback devices. The second is when creating a system with SELinux + and an XFS root partition. Because `mkfs.xfs` does not support + populating an XFS filesystem with extended attributes, loopback + devices have to be used to ensure the SELinux extended attributes end + up in the generated XFS filesystem. + ### [Host] Section `ProxyUrl=`, `--proxy-url=` @@ -1290,18 +1420,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, Currently, setting a proxy client key is only supported when `dnf` or `dnf5` is used to build the image. -`Incremental=`, `--incremental=`, `-i` -: Enable incremental build mode. In this mode, a copy of the OS image is - created immediately after all OS packages are installed and the - prepare scripts have executed but before the `mkosi.build` scripts are - invoked (or anything that happens after it). On subsequent invocations - of `mkosi` with the `-i` switch this cached image may be used to skip - the OS package installation, thus drastically speeding up repetitive - build times. Note that while there is some rudimentary cache - invalidation, it is definitely not perfect. In order to force - rebuilding of the cached image, combine `-i` with `-ff` to ensure the - cached image is first removed and then re-created. - `NSpawnSettings=`, `--settings=` : Specifies a `.nspawn` settings file for `systemd-nspawn` to use in the `boot` and `shell` verbs, and to place next to the generated @@ -1467,122 +1585,6 @@ boolean argument: either `1`, `yes`, or `true` to enable, or `0`, `no`, OEM string. This will only be picked up by systemd-boot/systemd-stub versions newer than or equal to v254. -`ToolsTree=`, `--tools-tree=` -: If specified, programs executed by mkosi to build and boot an image - are looked up inside the given tree instead of in the host system. Use - this option to make image builds more reproducible by always using the - same versions of programs to build the final image instead of whatever - version is installed on the host system. If this option is not used, - but the `mkosi.tools/` directory is found in the local directory it is - automatically used for this purpose with the root directory as target. - - Note if a binary is found in any of the paths configured with - `ExtraSearchPaths=`, the binary will be executed on the host. - - If set to `default`, mkosi will automatically add an extra tools tree - image and use it as the tools tree. - - Note that mkosi will only build a single default tools tree per build, - even if multiple images are defined in `mkosi.images` with - `ToolsTree=default`. The settings of the "last" image will apply to - the default tools tree (usually the image defined last in - mkosi.images and without any dependencies on other images). - - The following table shows for which distributions default tools tree - packages are defined and which packages are included in those default - tools trees: - - | | Fedora | CentOS | Debian | Kali | Ubuntu | Arch | openSUSE | - |-------------------------|:------:|:------:|:------:|:----:|:------:|:----:|:--------:| - | `acl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `apt` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `archlinux-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `attr` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `bash` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `btrfs-progs` | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | - | `bubblewrap` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `ca-certificates` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `coreutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `cpio` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `curl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `debian-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `diffutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `distribution-gpg-keys` | ✓ | ✓ | | | | ✓ | ✓ | - | `dnf` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `dnf-plugins-core` | ✓ | ✓ | | | | | ✓ | - | `dnf5` | ✓ | | | | | | | - | `dnf5-plugins` | ✓ | | | | | | | - | `dosfstools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `e2fsprogs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `edk2-ovmf` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `erofs-utils` | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | - | `findutils` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `git` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `grep` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `grub-tools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `jq` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `kali-archive-keyring` | | | | ✓ | | | | - | `kmod` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `less` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `mtools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `nano` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `openssh` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `openssl` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `sed` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `pacman` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `pesign` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `policycoreutils` | ✓ | ✓ | ✓ | ✓ | ✓ | | ✓ | - | `qemu` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `sbsigntools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `socat` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `squashfs-tools` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `strace` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `swtpm` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `systemd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `ukify` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `tar` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `ubuntu-keyring` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | - | `util-linux` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `virtiofsd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `virt-firmware` | ✓ | ✓ | | | | ✓ | | - | `xfsprogs` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `xz` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `zstd` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | `zypper` | ✓ | | ✓ | ✓ | ✓ | ✓ | | - -`ToolsTreeDistribution=`, `--tools-tree-distribution=` -: Set the distribution to use for the default tools tree. By default, - the same distribution as the image that's being built is used, except - for CentOS and Ubuntu images, in which case Fedora and Debian are used - respectively. - -`ToolsTreeRelease=`, `--tools-tree-release=` -: Set the distribution release to use for the default tools tree. By - default, the hardcoded default release in mkosi for the distribution - is used. - -`ToolsTreeMirror=`, `--tools-tree-mirror=` -: Set the mirror to use for the default tools tree. By default, the - default mirror for the tools tree distribution is used. - -`ToolsTreeRepositories=`, `--tools-tree-repository` -: Same as `Repositories=` but for the default tools tree. - -`ToolsTreeSandboxTrees=`, `--tools-tree-sandbox-tree` -: Same as `SandboxTrees=` but for the default tools tree. - -`ToolsTreePackages=`, `--tools-tree-packages=` -: Extra packages to install into the default tools tree. Takes a comma - separated list of package specifications. This option may be used - multiple times in which case the specified package lists are combined. - -`ToolsTreeCertificates=`, `--tools-tree-certificates=` -: Specify whether to use certificates and keys from the tools tree. If - enabled, `/usr/share/keyrings`, `/usr/share/distribution-gpg-keys`, - `/etc/pki`, `/etc/ssl`, `/etc/ca-certificates`, `/etc/pacman.d/gnupg` - and `/var/lib/ca-certificates` from the tools tree are used. - Otherwise, these directories are picked up from the host. - `RuntimeTrees=`, `--runtime-tree=` : Takes a colon separated pair of paths. The first path refers to a directory to mount into any machine (container or VM) started by