From: Daan De Meyer Date: Sun, 2 Apr 2023 14:25:24 +0000 (+0200) Subject: Update outdated documentation X-Git-Tag: v15~268^2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a99b8c0ede352bd0d589765fbe429143cb4c4c1e;p=thirdparty%2Fmkosi.git Update outdated documentation Remove build phases docs as we only have a single phase these days and update the caching section docs to take the new build overlay approach into account. --- diff --git a/mkosi.md b/mkosi.md index 02ca1d28c..4e2b8cac9 100644 --- a/mkosi.md +++ b/mkosi.md @@ -1210,35 +1210,6 @@ during invocation via command line switches, and as settings in `mkosi.conf`, in case the default settings are not acceptable for a project. -# BUILD PHASES - -If no build script `mkosi.build` (see above) is used the build -consists of a single phase only: the final image is generated as the -combination of `mkosi.skeleton/` (see above), the unpacked -distribution packages and `mkosi.extra/`. - -If a build script `mkosi.build` is used the build consists of two -phases: in the the first `development` phase an image that includes -necessary build tools (i.e. the combination of `Packages=` and -`BuildPackages=` is installed) is generated (i.e. the combination of -`mkosi.skeleton/` and unpacked distribution packages). Into this image -the source tree is copied and `mkosi.build` executed. The artifacts -the `mkosi.build` generates are saved. Then, the second `final` phase -starts: an image that excludes the build tools (i.e. only `Packages=` -is installed, `BuildPackages=` is not) is generated. This time the -build artifacts saved from the first phase are copied in, and -`mkosi.extra` copied on top, thus generating the final image. - -The two-phased approach ensures that source tree is executed in a -clean and comprehensive environment, while at the same the final image -remains minimal and contains only those packages necessary at runtime, -but avoiding those necessary at build-time. - -Note that only the package cache `mkosi.cache/` is shared between the -two phases. The distribution package manager is executed exactly once -in each phase, always starting from a directory tree that is populated -with `mkosi.skeleton` but nothing else. - # CACHING `mkosi` supports three different caches for speeding up repetitive @@ -1251,15 +1222,14 @@ re-building of images. Specifically: (RPM, DEB, …) after they are downloaded, but before they are unpacked. -2. If an `mkosi.build` script is used, by enabling incremental build - mode with `--incremental`, a cached copy of the development and - final images can be made immediately before the build sources are - copied in (for the development image) or the artifacts generated by - `mkosi.build` are copied in (in case of the final image). This form - of caching allows bypassing the time-consuming package unpacking - step of the distribution package managers, but is only effective if - the list of packages to use remains stable, but the build sources - and its scripts change regularly. Note that this cache requires +2. If the incremental build mode is enabled with `--incremental`, cached + copies of the final image and build overlay are made immediately + before the build sources are copied in (for the build overlay) or the + artifacts generated by `mkosi.build` are copied in (in case of the + final image). This form of caching allows bypassing the time-consuming + package unpacking step of the distribution package managers, but is only + effective if the list of packages to use remains stable, but the build + sources and its scripts change regularly. Note that this cache requires manual flushing: whenever the package list is modified the cached images need to be explicitly removed before the next re-build, using the `-f` switch.