Documentation menu
Welcome/ The Handbook/ Contributing/ How to build a rootfs

How to build a rootfs

Use krep rootfs to build a Kreato Linux root filesystem. krep replaces the standalone Kreastrap tool. Profiles are declarative Kongue .kg files; the old INI .conf profiles are no longer supported.

Requirements

Rootfs builds require Linux and root privileges. Use a disposable Kreato Linux build environment with kpkg, configured package repositories, and the native build dependencies. You also need Git, a C toolchain, Nim with Nimble, and Make. The full krep build needs native libraries including OpenSSL and libarchive. make deps installs the Nim dependencies, not the host libraries.

Rootfs builds can install host packages and use chroots and mounts. Do not run them on a host you cannot safely change. A container needs the permissions needed for these operations; an unprivileged container is not sufficient for every build.

Build krep

git clone https://github.com/kreatolinux/src
cd src
make deps
make krep
./out/krep rootfs --help

The build stages resources in out/share/krep. To install both the executable and resources, use sudo make install_krep (default prefix: /usr/local). Building krep on macOS does not make the Linux image tasks work there.

Select a profile and output directory

Profiles live in krep/data/rootfs/arch/ARCHITECTURE/configs/. The defaults are --arch=amd64 and --buildType=builder. Check which profiles exist for your architecture before selecting one. An architecture option alone does not provide a cross-compilation environment.

Copy a profile and review it before building:

cp krep/data/rootfs/arch/amd64/configs/builder.kg ./rootfs.kg
# Edit rootfs.kg, especially build_directory, before continuing.
sudo ./out/krep rootfs --arch=amd64 --buildType=builder --configPath="$PWD/rootfs.kg"

The bundled builder.kg profile looks like this:

kongue 
schema_version: "1"
build_directory: "/out"
package_mode: "binary"
use_overlay: "true"

arch: "x86_64"
os: "linux"
libc: "glibc"
compiler: "gcc"
coreutils: "busybox"
init: "jumpstart"
tls_library: "openssl"

extra_packages:
  - "gmake"
  - "nim"
  - "gtar"

build_directory selects the rootfs output directory. Bundled profiles use /out; this is not the source tree’s ./out binary directory. Relative output paths are resolved against the directory where you invoke krep. package_mode: "build" builds packages from source; package_mode: "binary" installs binaries from the configured repository. Availability depends on that repository.

libc, compiler, coreutils, tls_library, and init select the core components; systemd profiles require GNU coreutils. extra_packages adds packages. The loader accepts only literal scalar and list fields, so functions, commands, interpolation, and unknown fields are rejected. See kreastrap.kg(5) for every field. Do not use the output rootfs directory for unrelated files.

Resources and sandboxing

  • --dataDir=/path/assets/rootfs selects a command-specific resource directory.
  • --configPath=/path/profile.kg overrides the selected profile.
  • --overlayPath=/path/overlay overrides the overlay directory. The configuration’s use_overlay setting still controls whether it is used.
  • KREP_DATA_DIR=/path/assets selects a unified data root with rootfs/ and iso/ children. Pass it explicitly through sudo env if needed.
  • --useCacheIfPossible defaults to true.
  • --noSandbox defaults to false. It disables kpkg’s source-build sandbox; only use it inside an appropriate external isolation boundary.

Use the result

The command writes a rootfs directory, including /etc/kreato-release. It does not itself produce a rootfs tarball. Review the result and its login policy before using it. Use the installation guide for an installed system, or prepare its kernel, indexed modules, init, and services for krep iso.