A complete embedded Linux SDK for macOS. Build kernels, cross-compile with native toolchains, develop kernel modules and userspace apps—all without Docker or VMs. ELMOS provides an integrated development environment with interactive TUI, automatic toolchain management (crosstool-ng), and seamless QEMU integration. Targeting RISC-V, ARM64, ARM, and more, with full support for Linux v6.18+.
Inspired by Seiya's tutorial (which fixed older kernels like v6.17), we extended it for v6.18's new challenges, like the copy_file_range() incompatibility.
- Cross-Compiler Toolchain Management: Build and manage crosstool-ng toolchains for ARM64, ARM, and RISC-V
- Interactive TUI: Rich terminal interface with real-time command output
- Environment Doctor: Comprehensive dependency and toolchain health checks
- Kernel Build Automation: Configure, build, and test Linux kernels with integrated toolchain support
- Module & App Development: Build kernel modules and userspace apps with automatic cross-compilation
- Visual Architecture: PlantUML diagrams for system design and workflows
- QEMU Integration: Boot and debug kernels with built-in GDB support
Comprehensive documentation is hosted on GitHub Pages:
- User Guide: Usage, kernel building, toolchains.
- Developer Guide: Architecture, APIs, code patterns.
- Diagrams: Component, Sequence, and Class diagrams.
brew install llvm lld gnu-sed make libelf git qemu fakeroot e2fsprogs coreutils go-task wget
xcode-select --install # For SDK headersgit clone https://github.com/NguyenTrongPhuc552003/elmos.git
cd elmos
task build # Build to build/elmos
./build/elmos init # Create workspace (sparseimage + config)
./build/elmos doctor # Verify environment./build/elmos toolchains install # Install crosstool-ng
./build/elmos toolchains list # List available targets
./build/elmos arch riscv # Select arch (auto-selects toolchain)
./build/elmos toolchains build # Build the toolchain (~30-60 min)
./build/elmos toolchains status # Verify installation./build/elmos kernel clone # Clone kernel source
./build/elmos kernel config defconfig # Or: menuconfig
./build/elmos kernel build # Build with detected toolchain./build/elmos rootfs create # Debian rootfs (debootstrap)
./build/elmos qemu run # Boot in QEMU
./build/elmos qemu debug # With GDB stub (port 1234)Launch with ./build/elmos tui for a rich interactive interface:
ELMOS integrates crosstool-ng for building native cross-compilers:
| Command | Description |
|---|---|
elmos toolchains install |
Clone & build crosstool-ng |
elmos toolchains list |
List available target configurations |
elmos toolchains <target> |
Select a target (e.g., riscv64-unknown-linux-gnu) |
elmos toolchains build |
Build selected toolchain |
elmos toolchains status |
Show installed toolchains |
elmos toolchains env |
Display environment variables |
elmos toolchains menuconfig |
Interactive toolchain configuration |
elmos toolchains clean |
Clean toolchain build artifacts |
Pre-configured targets with optimized settings:
aarch64-unknown-linux-gnu(ARM64)arm-cortex_a15-linux-gnueabihf(ARM 32-bit)riscv64-unknown-linux-gnu(RISC-V 64-bit)
Uses Task with namespaced commands:
task --list # Show all targets
# Core
task build # Build elmos binary → build/elmos
task clean # Clean all artifacts
# Development
task dev:check # Run fmt, lint, test (pre-commit style)
task dev:setup # Full setup (deps + build + init)
task test # Run tests
task test:cover # Tests with coverage report
# elmos CLI Wrappers
task elmos:init # Initialize workspace
task elmos:doctor # Run environment check
task elmos:status # Show workspace status
task elmos:tui # Launch interactive TUI
# Release
task release:darwin # Build for macOS (arm64 + amd64)
task release:all # Full release with completions.
├── assets/ # Embedded templates
│ └── templates/ # Config, module, app templates
├── build/ # Build output (elmos, elmos.yaml, img.sparseimage)
├── core/ # Core domain logic
│ ├── app/ # CLI application & command wiring
│ ├── config/ # Configuration management
│ ├── domain/ # Business logic (builder, toolchain, doctor)
│ └── ui/ # User Interface (TUI)
├── libraries/ # Shims: byteswap.h, elf.h, asm/
├── modules/ # Kernel modules
├── patches/ # Versioned kernel patches
├── tools/
│ └── toolchains/ # crosstool-ng & custom configs
├── Taskfile.yml # Build automation
└── main.go # Entry point- Issue: v6.18 uses Linux-only syscall in
gen_init_cpio - Fix: Patch replaces with
copyfile(COPYFILE_DATA)on macOS - Apply:
./build/elmos patch apply patches/v6.18/0001-usr-gen_init_cpio-Replace-linux-kernel-syscall-with-.patch
- Kernel, module, and app builds auto-detect installed toolchains
CROSS_COMPILEandPATHset automatically for the target architecture- Falls back to Homebrew LLVM if no toolchain installed
The CLI sets these automatically:
-I${MACOS_HEADERS}: Custom shims (elf.h,byteswap.h)-I${LIBELF_INCLUDE}: libelf for ELF parsing-D_UUID_T -D__GETHOSTUUID_H: Suppress uuid_t conflicts-D_DARWIN_C_SOURCE: macOS 10.15+ APIs
| Issue | Solution |
|---|---|
| "gmake not found" | brew install make → use gmake |
| UUID conflicts | Ensure patch applied |
| Toolchain build fails | Check elmos doctor for missing deps |
| TUI shows help text | Rebuild with task build |
- Original Tutorial: Building Linux on macOS Natively by Seiya Suzuki
- Upstream: Clang Built Linux for LLVM guidance
- Author: Phuc Nguyen (@NguyenTrongPhuc552003)
MIT — fork, extend, build freely.