Diffstat (limited to 'README.md')
1 files changed, 49 insertions, 16 deletions
@@ -112,16 +112,18 @@ following *OS*es.
In theory, any distribution may be used on the host for
building images containing any other distribution, as long as
the necessary tools are available. Specifically, any distro
that packages `debootstrap` may be used to build *Debian* or
*Ubuntu* images. Any distro that packages `dnf` may be used to
-build *Fedora* images. Any distro that packages `pacstrap` may
-be used to build *Arch Linux* images. Any distro that packages
-`zypper` may be used to build *openSUSE* images.
+build *Fedora* or *Mageia* images. Any distro that packages
+`pacstrap` may be used to build *Arch Linux* images. Any distro
+that packages `zypper` may be used to build *openSUSE* images.
-Currently, *Fedora* packages the first three tools.
+Currently, *Fedora* packages all four tools as of Fedora 26.
@@ -133,18 +135,18 @@ they exist in the local directory:
* `mkosi.default` may be used to configure mkosi's image
building process. For example, you may configure the
- distribution to use (`fedora`, `ubuntu`, `debian`, `archlinux`) for
- the image, or additional distribution packages to
- install. Note that all options encoded in this configuration
- file may also be set on the command line, and this file is
- hence little more than a way to make sure simply typing
- `mkosi` without further parameters in your *source* tree is
+ distribution to use (`fedora`, `ubuntu`, `debian`, `archlinux`,
+ `opensuse`, `mageia`) for the image, or additional
+ distribution packages to install. Note that all options encoded
+ in this configuration file may also be set on the command line,
+ and this file is hence little more than a way to make sure simply
+ typing `mkosi` without further parameters in your *source* tree is
enough to get the right image of your choice set up.
Additionally if a `mkosi.default.d` directory exists, each file in it
is loaded in the same manner adding/overriding the values specified in
-* `mkosi.extra` may be a directory. If this exists all files
+* `mkosi.extra/` may be a directory. If this exists all files
contained in it are copied over the directory tree of the
image after the *OS* was installed. This may be used to add in
additional files to an image, on top of what the
@@ -187,9 +189,24 @@ they exist in the local directory:
next to image files it boots, for additional container
-* `mkosi.cache` may be a directory. If so, it is automatically used as
+* `mkosi.cache/` may be a directory. If so, it is automatically used as
package download cache, in order to speed repeated runs of the tool.
+* `mkosi.builddir/` may be a directory. If so, it is automatically
+ used as out-of-tree build directory, if the build commands in the
+ `mkosi.build` script support it. Specifically, this directory will
+ be mounted into the build countainer, and the `$BUILDDIR`
+ environment variable will be set to it when the build script is
+ invoked. The build script may then use this directory as build
+ directory, for automake-style or ninja-style out-of-tree
+ builds. This speeds up builds considerably, in particular when
+ `mkosi` is used in incremental mode (`-i`): not only the disk images
+ but also the build tree is reused between subsequent
+ invocations. Note that if this directory does not exist the
+ `$BUILDDIR` environment variable is not set, and it is up to build
+ script to decide whether to do in in-tree or an out-of-tree build,
+ and which build directory to use.
* `mkosi.passphrase` may be a passphrase file to use when LUKS
encryption is selected. It should contain the passphrase literally,
and not end in a newline character (i.e. in the same format as
@@ -233,11 +250,11 @@ Create and run a *Fedora* image into a plain directory:
# systemd-nspawn -b -D quux
-Create a compressed tar ball `image.raw.xz` and add a checksum
-file, and install *SSH* into it:
+Create a compressed image `image.raw.xz` and add a checksum file, and
+install *SSH* into it:
-# mkosi -d fedora -t tar --checksum --compress --package=openssh-clients
+# mkosi -d fedora -t raw_squashfs --checksum --xz --package=openssh-clients
Inside the source directory of an `automake`-based project,
@@ -272,16 +289,32 @@ EOF
# systemd-nspawn -bi image.raw
+To create a *Fedora* image with hostname:
+# mkosi -d fedora --hostname image
+Also you could set hostname in configuration file:
+# cat mkosi.default
mkosi is packaged for various distributions: Debian, Ubuntu, Arch (in AUR), Fedora.
It is usually easiest to use the distribution package.
+The current version requires systemd 233 (or actually, systemd-nspawn of it).
When not using distribution packages make sure to install the
necessary dependencies. For example, on *Fedora* you need:
-dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf squashfs-tools gnupg python3 tar veritysetup xz
+dnf install arch-install-scripts btrfs-progs debootstrap dosfstools edk2-ovmf squashfs-tools gnupg python3 tar veritysetup xz zypper
Note that the minimum required Python version is 3.5.