Skip to content

Instantly share code, notes, and snippets.

@al-swaiti

al-swaiti/guide.md

Last active August 24, 2025 20:06
Show Gist options
  • Save al-swaiti/1ed08d99b956364d1052c61e576c265c to your computer and use it in GitHub Desktop.
Save al-swaiti/1ed08d99b956364d1052c61e576c265c to your computer and use it in GitHub Desktop.
Download ZIP
TKG-kerenl
Raw
guide.md

The Ultimate Guide to Building a High-Performance Linux Kernel with TKG

This guide provides a comprehensive, expert-level walkthrough for compiling a custom Linux kernel using the linux-tkg project. It is intended for enthusiasts and power users who want to move beyond generic distribution kernels to unlock the maximum performance, responsiveness, and low-latency potential of their hardware, particularly for desktop and gaming workloads.

The Philosophy: Why Build a Custom Kernel?

The kernel shipped by your Linux distribution is a masterpiece of compatibility, designed to run on everything from ancient laptops to multi-socket servers. This "one-size-fits-all" approach means it's not specifically optimized for your hardware or your use case.

By building a custom kernel, you are making a deliberate trade-off: sacrificing universal compatibility for specialized performance. You are creating a kernel that is explicitly engineered for your CPU, your hardware, and your workloads.

Step 1: Prerequisites

Before you begin, you need to set up the build environment.

  1. Install Build Tools & Git:

    # For Arch Linux and derivatives
sudo pacman -S --needed base-devel git

  2. Clone the linux-tkg Project: This command clones the project and its necessary submodules.

    git clone https://github.com/Frogging-Family/linux-tkg.git --recurse-submodules
cd linux-tkg

  3. Install and Populate modprobed-db: This tool is the key to creating a lean, optimized kernel. It scans your system for currently used hardware drivers.

    # Install the tool
sudo pacman -S modprobed-db

# Populate the database (do this on a fully booted, running system)
sudo modprobed-db store

Step 2: The High-Performance Configuration (customization.cfg)

This is the heart of the process. Edit a file named customization.cfg inside the linux-tkg directory and follow the following template . The comments explain the reasoning behind each choice. (u can add ur device information and do some talk with any ai !)

# linux-TkG Configuration: A General High-Performance Guide
#
# This configuration serves as a universal template for building a high-performance, general-purpose desktop kernel.
# The focus is on maximizing responsiveness, gaming performance, and leveraging modern hardware.

# Best Practice: Leave empty to be prompted. The script is excellent at auto-detection.
_distro=""

# Best Practice: Use the "-latest" suffix (e.g., "6.16-latest") to get the most recent stable point release.
_version="6.16-latest"

# Best Practice: Set to "true" to save disk space.
_NUKR="true"

# Best Practice: Set to "true" to ensure the fastest possible compile times.
_force_all_threads="true"

# Best Practice: THIS IS THE SINGLE MOST IMPORTANT OPTIMIZATION. Set to "true".
# It creates a lean kernel tailored to your specific hardware.
# Prerequisite: You must have run `sudo modprobed-db store`.
_modprobeddb="true"

# Best Practice: Leave this disabled ("") for most builds.
# Use it ("1" for menuconfig) only when you need to fix a specific issue.
_menunconfig=""

# Best Practice: Set to "running-kernel". This uses your current, working kernel
# config as a safe starting point before `modprobed` trims it down.
_configfile="running-kernel"

# Best Practice: Set to "true". Kernel debugging incurs a noticeable performance overhead.
_debugdisable="true"

# Best Practice: Set to "true". This significantly reduces the size of the installed kernel.
_STRIP="true"

# Best Practice: Set to "bore" (Burst-Oriented Response Enhancer).
# This scheduler is explicitly designed for desktop and gaming workloads, prioritizing low latency.
_cpusched="bore"

# WARNING: Set to "false". Disabling NUMA can break CUDA/NVENC for NVIDIA users.
# The risks far outweigh the negligible performance gain.
_numadisable="false"

# Best Practice: Set to "true". This is a curated collection of performance patches.
_glitched_base="true"

# Best Practice: Set to "true". Adds further gaming-specific optimizations.
_zenify="true"

# Best Practice: Set to "2" for `-O2`. This is the sweet spot for performance and stability.
_compileroptlevel="2"

# Best Practice: Set this to "native". The compiler will auto-detect your CPU
# and use all its available instruction sets for optimal performance.
_processor_opt="native"

# Best Practice: Set to "true". Modern CPUs have high-quality hardware random number generators.
_random_trust_cpu="true"

# Best Practice: Set to "1000". A 1000Hz tick rate improves responsiveness and reduces input latency.
_timer_freq="1000"

# Best Practice: Set to "performance". This forces the CPU to always run at its maximum
# frequency, eliminating scaling latency. Ideal for desktops.
_default_cpu_gov="performance"

# Best Practice: Set to "bbr". Google's BBR algorithm can result in higher throughput
# and lower latency on modern internet connections.
_tcp_cong_alg="bbr"

# Best Practice: Set to "true". The Clear Linux project is known for aggressive performance optimizations.
_clear_patches="true"

# Best Practice: Set to "true" if you use OpenRGB for RGB lighting control.
_openrgb="true"

# Best Practice: Use a descriptive name like "linux-tkg-custom".
# This makes it easy to identify your custom kernel in the bootloader menu.
_custom_pkgbase="linux-tkg-custom"

# Best Practice: Set this to "$(nproc)". This automatically sets the value
# to the number of logical cores on your system, slightly reducing kernel overhead.
_NR_CPUS_value="$(nproc)"

Step 3: Build and Install the Kernel

With your configuration saved, the build process is a single command.

# From inside the linux-tkg directory
# -s installs dependencies
# -r removes build-time dependencies after completion
# -i installs the finished package
makepkg -sri

The build will take a significant amount of time, depending on your CPU.

Step 4: Post-Installation

  1. Update Your Bootloader: Your bootloader needs to be made aware of the new kernel.

    # For GRUB users
sudo grub-mkconfig -o /boot/grub/grub.cfg

# systemd-boot users usually have this handled automatically by systemd hooks.

  2. Reboot and Verify: Reboot your system. In your bootloader menu, select the new kernel (e.g., linux-tkg-custom). Once booted, you can verify it's running with:

    uname -r

    The output should match the custom kernel name you configured.

Troubleshooting & Common Issues

  • "My system doesn't boot" or "My Ethernet/Wi-Fi doesn't work!"
    • Problem: This is the most common issue. modprobed-db only detects drivers that are currently in use. Some drivers (especially for networking or encrypted disks) are loaded in the initramfs (early boot stage) and may not be present when you run the scan.
    • Solution:
      1. Boot back into your old, working kernel.
      2. Edit customization.cfg and set _menunconfig="1".
      3. Run makepkg -sri again. The build will pause and open a terminal UI.
      4. Use the / key to search for the missing driver (e.g., search for your network card's driver like r8169, or dm_integrity for encrypted disks).
      5. Enable the driver with the y key (to build it in) or m key (to build as a module).
      6. Exit, save the new configuration, and let the build complete.
      7. Re-install and reboot. Your hardware should now work.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment