Kernel Configuration

Forest OS uses a Kconfig-inspired, text-file-driven configuration system for the Fern kernel. Every subsystem — from memory management and filesystems to graphics drivers and networking protocols — can be independently enabled or disabled at build time.

The configuration system lives in fern/ and revolves around three key files:

How the System Works

The configuration flow is simple:

.forestos_config  --(conf.sh --generate)--> build-config.mk
build-config.mk   --(Make includes)------> Make variables (ENABLE_*, ARCH, etc.)
build/features/*.mk                       Source-file gating (EXCLUDED_CSOURCES)

You never edit build-config.mk by hand. It is always regenerated from .forestos_config by conf.sh --generate. The Make system includes build/config.mk first, which loads build-config.mk and guarantees every boolean option has a yes or no value. Then build/features/*.mk fragments use these values to include or exclude source files from the kernel build.

conf.sh -- The Configuration Tool

conf.sh is the main entry point for all configuration. It supports both interactive (TUI) and batch (non-interactive) modes.

Modes at a Glance

Typical Workflow

./conf.sh --defconfig       # sane defaults
./conf.sh --menuconfig      # tweak interactively
./conf.sh --generate        # regenerate build-config.mk
make                        # build

Or via Makefile shortcuts: make defconfig, make menuconfig, make oldconfig, make configcheck.

How Each Mode Works

--defconfig: Loads defaults from CONFIG_DB, enforces required-on options, resolves dependency chains, saves .forestos_config, generates build-config.mk.

--menuconfig: Loads defaults + existing config, presents a dialog TUI with 20+ categories and sub-menus. Dependencies enforced live.

--generate: Reads .forestos_config as-is, validates all values (choices, ints, bools), enforces dependencies, produces build-config.mk with core choices, feature/process booleans, numeric tunables, FEATURE_FLAGS, and derived build flags.

The .forestos_config File Format

.forestos_config is a plain text file with CONFIG_NAME=value lines. Comments start with #.

# Target Architecture
BUILD_ARCH=32

# Virtual Memory Paging
ENABLE_PAGING=y

# Default framebuffer width
DISPLAY_DEFAULT_WIDTH=1024

Key points:

• Keys are prefixed with CONFIG_ in the file (stripped internally).
• Boolean values: y or n.
• Choice values: strings like 32, 64, bios, uefi, debug.
• Integer values: non-negative numbers.

Feature Classes

Options in conf.sh have a class (6th field in CONFIG_DB):

• feature (default): Emitted as NAME := yes/no AND -DNAME in FEATURE_FLAGS. C code uses #ifdef ENABLE_FOO.
• process: Emitted as NAME := yes/no only. No -D define. Controls build behavior (e.g., VERBOSE, WERROR).

Complete Feature Flag Reference

Core Choices

Architecture and Boot

Memory Management

Filesystems

Graphics and Display

Networking (all off by default)

Audio (all off by default)

Security

USB (off by default)

Storage

Input Devices

IPC

Timers

Interrupts

Scheduler

Hardware

Debugging

Compatibility

Build System

Numeric Tunables

How Configuration Affects the Build

Source Gating

The build/features/*.mk fragments control compilation via EXCLUDED_CSOURCES:

1. build/kernel-sources.mk defines CSOURCES as all .c files in src/.
2. Each feature fragment appends to EXCLUDED_CSOURCES when its feature is no.
3. CSOURCES is computed as $(filter-out $(EXCLUDED_CSOURCES), $(wildcard ...)).

Parent-child relationships are transitive: disabling ENABLE_VFS=no disables all filesystem children.

Feature Flags in C Code

When a feature-class option is yes, FEATURE_FLAGS includes -DENABLE_FOO. C code uses conditional compilation:

#ifdef ENABLE_EXT2
    // ext2 mount support
#endif

Default vs Custom Configuration

Running ./conf.sh --defconfig writes .forestos_config with sensible defaults:

• On: Paging, SLAB, protection, guard pages, VFS, EXT2/FAT32/exFAT, full graphics stack, ATA/AHCI/NVMe, all security features, all debug features.
• Off: ASLR, COW, swap, networking, audio, USB, SCSI, floppy, HPET, MSI.

Required-On Options

These cannot be turned off, even with --allnoconfig: ENABLE_PAGING, ENABLE_A20, ENABLE_TTY.

Dependency System

Features have parent dependencies (3rd field in CONFIG_DB). Disabling a parent forces all children to n transitively. This prevents impossible configurations like EXT2 without VFS.

Configuration Presets (makeconfigs/)

The fern/makeconfigs/ directory mirrors build/ with its own config.mk, dirs.mk, flags.mk, and features/ subdirectory. It can serve as a reference implementation, alternative configuration base, or starting point for custom builds.

Configuration Validation

• conf.sh: Validates choices against allowed values, ints non-negative, bools y/n. Invalid values reset to defaults.
• build/config.mk: Validates ARCH (32 64 arm aarch64 riscv64), BOOT_MODE (bios uefi), BUILD_TYPE (debug release optimize). Any undefined boolean forced to no.
• configcheck: make configcheck prints effective config and counts enabled features.

Tips for Optimal Configuration

Development: BUILD_TYPE=debug + ENABLE_DEBUG_SYMBOLS + ENABLE_SERIAL_DEBUG + VERBOSE=yes.

Minimal embedded: --allnoconfig, then enable only paging, VFS, console.

Desktop: --defconfig, then enable networking, audio, USB, OpenGL.

Production: Disable debug features, use BUILD_TYPE=optimize, reduce heap sizes for constrained hardware.