English | 简体中文

This toolkit aims to speed up kernel module development, but it does not guarantee that modules will be fully compatible with the corresponding kernel version.

If you need full compatibility, please download the complete kernel source and compile it yourself; see relevant documentation for details.

If you prefer not to download Clang, you can use NDK Clang to build, but this may lead to different struct offsets in the compiled artifacts.

Prebuilts tarball in submodule is very large, do not clone submodules if unnecessary.

Kernel module development template:

Github

CNB

Scenario	Recommended Mode
Linux native development	Host Mode (Recommended)
macOS / Windows development	DevContainer Mode (Recommended)
CI / automated builds	Docker Mode

---

• git-lfs (required to pull large files from the submodule — must be installed and initialized before cloning)
• zstd (for extracting .tar.zst archives)
• jq (for the VSCode configuration script)

Install and enable Git LFS:

# Debian/Ubuntu
sudo apt install git-lfs
# Arch
sudo pacman -S git-lfs

git lfs install

git clone --recurse-submodules https://github.com/Ylarod/ddk.git
cd ddk

If you already cloned without initializing submodules:

git submodule update --init --recursive

bash host/install.sh

The script extracts kernel sources (src), build headers (kdir), and the Clang toolchain (clang) from prebuilts/ into /opt/ddk:

/opt/ddk/
├── src/          # Kernel sources for each Android version
│   ├── android12-5.10/
│   ├── android13-5.10/
│   └── ...
├── kdir/         # Build headers for each Android version
└── clang/        # Clang toolchain

First ensure ~/.ddk/mapping.json exists (copy from the repo root):

mkdir -p ~/.ddk
cp mapping.json ~/.ddk/mapping.json

Then run the configuration script:

bash host/vscode_clangd_configure.sh

The script will:

• Read ~/.ddk/mapping.json to get the mapping between Android versions and Clang versions
• Copy the host/.vscode template (file filters, editor settings, compile_commands.json generator, etc.) into each /opt/ddk/src/<android-version>/ directory
• Set clangd.path in each directory's .vscode/settings.json to point to the corresponding Clang binary

Use --dry-run to preview actions without making changes:

bash host/vscode_clangd_configure.sh --dry-run

Open the desired kernel source directory in VSCode and install the clangd extension to get code completion, jump-to-definition, and reference search:

code /opt/ddk/src/android16-6.12

---

DevContainer provides a consistent, platform-independent development environment via containers, and is the recommended approach for macOS or Windows users who cannot use Host mode directly.

Place the following content in .devcontainer/devcontainer.json.

You can modify the features to assemble the image you need. Available versions: ddk image versions

References:

• ddk-toolchain
• ddk-src

For M1 Mac + OrbStack users, refer to the .devcontainer configuration in ddk-module-template and pull the image in advance:

docker run --platform linux/amd64 --rm -it docker.cnb.cool/ylarod/ddk/ddk-builder:latest

For x86_64 users:

{
  "name": "ddk-module-dev",
  "image": "docker.cnb.cool/ylarod/ddk/ddk-builder:latest",
  "features": {
    "ghcr.io/ylarod/ddk/features/ddk-toolchain:latest": {
      "androidVer": "android12-5.10",
      "setDefault": true
    },
    "ghcr.io/ylarod/ddk/features/ddk-src:latest": {
      "androidVer": "android12-5.10",
      "withKdir": true,
      "setDefault": true
    }
  },
  "remoteUser": "root",
  "postCreateCommand": "echo Devcontainer ready",
  "customizations": {
    "vscode": {
      "extensions": [
        "github.copilot",
        "github.copilot-chat",
        "github.vscode-github-actions",
        "llvm-vs-code-extensions.vscode-clangd",
        "ms-azuretools.vscode-containers",
        "ms-azuretools.vscode-docker",
        "ms-ceintl.vscode-language-pack-zh-hans"
      ]
    }
  }
}

Place the following content in .devcontainer/devcontainer.json.

You can modify the image value to pick the desired version for development. Available versions: ddk image versions

{
  "name": "ddk-module-dev",
  "image": "ghcr.io/ylarod/ddk:android16-6.12",
  "remoteUser": "root",
  "postCreateCommand": "echo Devcontainer ready",
  "customizations": {
    "vscode": {
      "extensions": [
        "github.copilot",
        "github.copilot-chat",
        "github.vscode-github-actions",
        "llvm-vs-code-extensions.vscode-clangd",
        "ms-azuretools.vscode-containers",
        "ms-azuretools.vscode-docker",
        "ms-ceintl.vscode-language-pack-zh-hans"
      ]
    }
  }
}

---

It is recommended to install the convenience script ddk first (wraps common docker commands, enforces --platform linux/amd64, and mounts the current directory to /build in the container).

Install (macOS/Linux):

# Install ddk to /usr/local/bin and make it executable
sudo curl -fsSL https://raw.githubusercontent.com/Ylarod/ddk/main/scripts/ddk -o /usr/local/bin/ddk
sudo chmod +x /usr/local/bin/ddk

Usage examples:

# Pull image
ddk pull android12-5.10

# Enter project directory
cd /path/to/source

# Build
ddk build --target android12-5.10

# Pass make arguments
ddk build --target android12-5.10 -- CFLAGS=-O2

# Clean
ddk clean --target android12-5.10

# Interactive shell
ddk shell --target android12-5.10

If you don't want to pass --target every time, set the DDK_TARGET environment variable:

export DDK_TARGET=android12-5.10
ddk build   # Will use DDK_TARGET

Refer to the following workflow files to build:

• Generic Matrix build template: ddk-lkm.yml
• Module Template build: module.yml

---

• Thanks to cnb.cool for providing computing resources