Skip to content

Tutorial

Jump to bottom
TheWildJames edited this page Feb 10, 2026 · 5 revisions

Comprehensive Linux Kernel Build Tutorial for Beginners

This tutorial will guide you through the process of building a Generic Kernel Image (GKI) with KernelSU and SUSFS support, mirroring the automated workflow used in this repository.

Table of Contents

  1. Prerequisites
  2. Workspace Setup
  3. Source Code Management
  4. Applying Patches (KernelSU & SUSFS)
  5. Kernel Configuration
  6. Building the Kernel
  7. Packaging
  8. Troubleshooting

1. Prerequisites

Before starting, ensure you are running a Linux environment.

Install System Dependencies

Dependencies can vary significantly depending on your Linux distribution or build environment. You may already have everything you need installed!

As you proceed through this tutorial, if you encounter any "command not found" errors, simply use your system's package manager to install the missing tool. Common tools you might need include git, curl, python3, zip, and unzip.

Install the repo Tool

Android kernel sources are managed by Google's repo tool.

# Create a bin directory for user scripts
mkdir -p ~/bin

# Download repo
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo

# Make it executable
chmod a+x ~/bin/repo

# Add to your PATH
export PATH=~/bin:$PATH

Tip: Add export PATH=~/bin:$PATH to your ~/.bashrc to make it permanent.

2. Workspace Setup

Create a dedicated directory for your kernel build. This keeps your system organized.

mkdir -p ~/android-kernel
cd ~/android-kernel

Kernel version vs Android version

Please note: Kernel version and Android version aren't necessarily the same!

If you find that your kernel version is android12-5.10.101, but your Android system version is Android 13 or other, don't be surprised, because the version number of the Android system isn't necessarily the same as the version number of the Linux kernel. The version number of the Linux kernel is generally correspondent to the version of the Android system that comes with the device when it is shipped. If the Android system is upgraded later, the kernel version will generally not change. So, before flashing anything, always refer to the kernel version!

Define some environment variables to make commands easier to copy-paste. Adjust these versions based on your target device (e.g., Android 14, Kernel 6.1).

# Choose your kernel from the chart below.

# Example for Android 14, Kernel 6.1
export ANDROID_VERSION="android14"
export KERNEL_VERSION="6.1"
export RELEASE_DATE="2024-09"

Kernel Configuration Charts

Refer to the individual charts below to select the exact ANDROID_VERSION, KERNEL_VERSION, SUB_LEVEL, and RELEASE_DATE for your specific device.

3. Source Code Management

We will now download the Android kernel source code.

Initialize the Repository

This command tells repo which manifest to use. We use the "common" kernel manifest.

# Format the branch name
export REPO_BRANCH="common-${ANDROID_VERSION}-${KERNEL_VERSION}-${RELEASE_DATE}"

# Initialize repo
repo init -u https://android.googlesource.com/kernel/manifest -b "${REPO_BRANCH}" --depth=1

Sync the Source

This downloads the actual code. It may take a while depending on your internet speed.

repo sync -c -j$(nproc --all) --fail-fast --no-tags --no-clone-bundle
  • j$(nproc --all): Uses all available CPU cores for faster download.

4. Applying Patches (KernelSU & SUSFS)

Now we will modify the standard kernel to add features like KernelSU (root access) and SUSFS (hiding root).

Clone Helper Repositories

We need some external scripts and patches.

# Clone AnyKernel3 (for flashing)
git clone https://github.com/WildKernels/AnyKernel3.git -b gki-2.0

# Clone Kernel Patches
git clone https://github.com/WildKernels/kernel_patches.git

4.1 Install Wild KernelSU (WKSU)

This script sets up KernelSU in the kernel source tree.

# Download and run the setup script
# Replace 'canary' with a specific commit hash if needed
curl -LSs "https://raw.githubusercontent.com/WildKernels/Wild_KSU/wild/kernel/setup.sh" | bash -s canary

4.2 Install SUSFS (Simple Untrusted Storage Filesystem)

SUSFS helps hide root modification traces.

# Clone SUSFS source
git clone https://gitlab.com/simonpunk/susfs4ksu.git -b "gki-${ANDROID_VERSION}-${KERNEL_VERSION}"

# Copy patches to the common kernel directory
cp susfs4ksu/kernel_patches/fs/* common/fs/
cp susfs4ksu/kernel_patches/include/linux/* common/include/linux/

# Apply the main SUSFS patch
cd common
# Find the correct patch version. The name format might vary slightly.
# Example: 50_add_susfs_in_gki-android14-6.1.patch
patch -p1 < "../susfs4ksu/kernel_patches/50_add_susfs_in_gki-${ANDROID_VERSION}-${KERNEL_VERSION}.patch"

4.3 Apply Fixes (Important!)

Depending on your specific kernel sub-version, you may need extra patches. For example, if you are on Android 14 Kernel 6.1:

# Example fix for specific sub-versions (check build.yml logic for details)
# cp ../kernel_patches/wild/susfs_fix_patches/v2.0.0/a14-6.1/base.c.patch ./
# patch -p1 < base.c.patch

4.4 Module Check Bypass (Optional but Recommended)

Some devices refuse to load modules if the version string doesn't match perfectly. This "bypass" forces the kernel to load them anyway.

For Kernel 6.1+: Edit kernel/module/version.c:

// Search for "bad_version" label
// Change "return 0;" to "return 1;"

Automation:

sed -i '/bad_version:/{:a;n;/return 0;/{s/return 0;/return 1;/;b};ba}' kernel/module/version.c

5. Kernel Configuration

We need to tell the build system to enable our new features.

Create a Config Fragment

Instead of editing the huge default config, we append a "fragment".

cat <<EOF > arch/arm64/configs/wild_gki.fragment
# KernelSU Configuration
CONFIG_KSU=y
CONFIG_KSU_SUSFS=y

# KPatch Support
CONFIG_KALLSYMS=y
CONFIG_KALLSYMS_ALL=y

# Filesystem Support
CONFIG_TMPFS_XATTR=y
CONFIG_TMPFS_POSIX_ACL=y
EOF

Set Local Version

To identify your kernel, add a custom suffix.

# In common/scripts/setlocalversion
# Locate the line echoing the version and append your string
# Or use this command:
sed -i 's/-dirty//' scripts/setlocalversion # Remove "dirty" tag

6. Building the Kernel

Modern Android kernels use Bazel for building.

# Go back to the root of your workspace (parent of common/)
cd ..

# Run the build
# --config=fast: Speeds up build
# --lto=thin: Link Time Optimization (faster build than full LTO)
tools/bazel build --config=fast --lto=thin --defconfig_fragment=//common:arch/arm64/configs/wild_gki.fragment //common:kernel_aarch64_dist

Note: The first build will take a long time (20-60 minutes) as it downloads toolchains and compiles everything. Subsequent builds will be much faster.

7. Packaging

Once built, you need to package the kernel into a zip file that can be flashed (e.g., via TWRP or Kernel Flasher).

Locate the Image

The built kernel image is usually located at: bazel-bin/common/kernel_aarch64/Image

Create AnyKernel3 Zip

# Copy the Image to AnyKernel3 folder
cp bazel-bin/common/kernel_aarch64/Image AnyKernel3/Image

# Enter directory
cd AnyKernel3

# Zip it up
zip -r9 ../My-Custom-Kernel.zip *

Congratulations! You now have a My-Custom-Kernel.zip ready to flash.

8. Troubleshooting

Common Errors

  1. "repo: command not found"

    • Fix: Ensure ~/bin is in your PATH. Run export PATH=~/bin:$PATH.

  2. "fatal: not a git repository"

    • Fix: Make sure you run commands inside the correct directory (usually common/ for git operations, root for repo sync).

  3. Build fails with "glibc" errors

    • Fix: Your host system's glibc might be too old or too new. The repository includes fixes in build.yml (e.g., patching resolve_btfids).
    • Workaround: Use Ubuntu 22.04 or a Docker container.

  4. "Permission denied"

    • Fix: Check if execution permissions are set (chmod +x script.sh).

  5. Patches fail to apply

    • Fix: The source code might have changed. Open the .patch file and the target file, and manually apply the changes using a text editor.

Verification

To verify your build was successful:

  1. Check that My-Custom-Kernel.zip is roughly 10-30MB.
  2. Unzip it and ensure it contains an Image file.

Disclaimer: Use these tutorials at your own risk. Always backup your device!

General

Build Tutorial

Clone this wiki locally