建構核心

本頁詳細說明為 Android 裝置建構自訂核心的程序。這些操作說明會引導您完成選取正確來源、建構核心，以及將結果嵌入由 Android 開放原始碼計畫 (AOSP) 建構的系統映像檔的程序。

您可以使用 Repo 取得較新的核心來源；只要從來源檢出的根目錄執行 build/build.sh，即可不必進一步設定就建構核心。

下載來源和建構工具

如要使用近期的核心，請使用 repo 下載來源、工具鍊和建構指令碼。某些核心 (例如 Pixel 3 核心) 需要來自多個 Git 存放區的來源，而其他核心 (例如一般核心) 則只需要單一來源。使用 repo 方法可確保正確的來源目錄設定。

下載適當分支的來源：

mkdir android-kernel && cd android-kernel
 
repo init -u https://android.googlesource.com/kernel/manifest -b BRANCH
 
repo sync

如需可搭配先前 `repo init` 指令使用的存放區分支 (BRANCH) 清單，請參閱 核心分支和其建構系統。

如要進一步瞭解如何下載及編譯 Pixel 裝置的核心，請參閱「 建構 Pixel 核心」。

建構核心

使用 Bazel 進行建構 (Kleaf)

Android 13 推出了使用 Bazel 建構核心的功能。

如要為 aarch64 架構建立 GKI 核心的發行版本，請檢查 Android 13 以上的 Android 通用核心分支，然後執行下列指令：

tools/bazel run //common:kernel_aarch64_dist [-- --destdir=$DIST_DIR]

之後，核心二進位檔、模組和對應的映像檔會位於 $DIST_DIR 目錄中。如果未指定 --destdir，請參閱指令的輸出內容，瞭解構件的位置。詳情請參閱 AOSP 說明文件。

使用 build.sh (舊版) 進行建構

針對 Android 12 以下版本的分支版本，或沒有 Kleaf 的分支版本：

build/build.sh

核心二進位檔、模組和對應的映像檔位於 out/BRANCH/dist 目錄中。

為虛擬裝置建構供應商模組

Android 13 引進了使用 Bazel (Kleaf) 建構核心的功能，取代 build.sh。

如要為 virtual_device 的模組建立發布版本，請執行：

tools/bazel run //common-modules/virtual-device:virtual_device_x86_64_dist [-- --destdir=$DIST_DIR]

如要進一步瞭解如何使用 Bazel 建構 Android 核心，請參閱Kleaf - 使用 Bazel 建構 Android 核心。

如要進一步瞭解 Kleaf 對個別架構的支援情形，請參閱「Kleaf 支援的裝置和核心」。

使用 build.sh (舊版) 為虛擬裝置建構供應商模組

在 Android 12 中，Cuttlefish 和 Goldfish 會合併，因此會共用相同的核心：virtual_device。如要建構該核心的模組，請使用以下建構設定：

BUILD_CONFIG=common-modules/virtual-device/build.config.virtual_device.x86_64 build/build.sh

Android 11 推出了 GKI，可將核心分離為由 Google 維護的核心映像檔，以及由供應商維護的模組，並分別建構。

以下範例顯示核心映像檔設定：

BUILD_CONFIG=common/build.config.gki.x86_64 build/build.sh

以下範例顯示模組設定 (Cuttlefish 和 Emulator)：

BUILD_CONFIG=common-modules/virtual-device/build.config.cuttlefish.x86_64 build/build.sh

執行核心

您可以透過多種方式執行自訂建構的核心。以下是適用於各種開發情境的已知方法。

嵌入 Android 映像檔建構作業

將 Image.lz4-dtb 複製至 AOSP 樹狀結構中的對應核心二進位位置，然後重新建構引導映像檔。

或者，您也可以在使用 make bootimage (或任何其他用於建構引導映像檔的 make 指令列) 時定義 TARGET_PREBUILT_KERNEL 變數。所有裝置都支援這個變數，因為它是透過 device/common/populate-new-device.sh 設定。例如：

export TARGET_PREBUILT_KERNEL=DIST_DIR/Image.lz4-dtb

使用 Fastboot 閃記及啟動核心

大多數新款裝置都提供系統啟動載入程式擴充功能，可簡化產生及啟動啟動映像檔的程序。

如要在不閃燈的情況下啟動核心，請按照下列步驟操作：

adb reboot bootloader
fastboot boot Image.lz4-dtb

使用這個方法時，核心並未實際閃燈，也不會在重新啟動時保留。

在 Cuttlefish 上執行核心

您可以在 Cuttlefish 裝置上，以所選架構執行核心。

如要使用特定的 核心構件組合啟動 Cuttlefish 裝置，請執行 cvd create 指令，並將目標核心構件做為參數。以下範例指令會使用 common-android14-6.1 核心資訊清單中 arm64 目標的核心構件。

cvd create \
    -kernel_path=/$PATH/$TO/common-android14-6.1/out/android14-6.1/dist/Image \
    -initramfs_path=/$PATH/$TO/common-android14-6.1/out/android14-6.1/dist/initramfs.img

詳情請參閱「在 Cuttlefish 上開發核心」。

自訂核心版本

如要自訂 Kleaf 建構的核心版本，請參閱 Kleaf 說明文件。

使用 build.sh (舊版) 自訂核心建構作業

對於 build/build.sh，版本建構程序和結果可能會受到環境變數的影響。其中大多數為選用項目，每個核心分支都應提供適當的預設設定。以下列出最常用的幾個。如需完整 (且最新) 清單，請參閱 build/build.sh。

環境變數 說明 範例
BUILD_CONFIG 建構設定檔，可用於初始化建構環境。 位置必須相對於 Repo 根目錄定義。預設值為 build.config。
適用於常見核心的必要項目。 		BUILD_CONFIG=common/build.config.gki.aarch64
CC 覆寫要使用的編譯器。改用 build.config 定義的預設編譯器。 CC=clang
DIST_DIR 核心分發作業的基礎輸出目錄。 DIST_DIR=/path/to/my/dist
OUT_DIR 核心建構作業的基本輸出目錄。 OUT_DIR=/path/to/my/out
SKIP_DEFCONFIG 略過 make defconfig SKIP_DEFCONFIG=1
SKIP_MRPROPER 略過 make mrproper SKIP_MRPROPER=1

本機版本的自訂核心設定

在 Android 14 以上版本中，您可以使用 defconfig 片段自訂核心設定。請參閱 Kleaf 說明文件中的 defconfig 片段。

針對本機建構作業使用建構設定的自訂核心設定 (舊版)

在 Android 13 以下版本中，請參閱以下說明。

如果您需要定期切換核心設定選項 (例如在處理某項功能時)，或是需要設定開發用選項，可以透過維持本機修改或複製版本設定來實現此彈性。

將變數 POST_DEFCONFIG_CMDS 設為在完成一般 make defconfig 步驟後立即評估的陳述式。由於 build.config 檔案會匯入建構環境，因此可在後定義設定指令中呼叫 build.config 中定義的函式。

常見的例子是在開發期間，為交叉網格核心停用連結時間最佳化 (LTO)。雖然 LTO 對已發布的核心有益，但在建構期間的額外負擔可能會相當可觀。以下程式碼片段會新增至本機 build.config，在使用 build/build.sh 時會持續停用 LTO。

POST_DEFCONFIG_CMDS="check_defconfig && update_debug_config"
function update_debug_config() {
    ${KERNEL_DIR}/scripts/config --file ${OUT_DIR}/.config \
         -d LTO \
         -d LTO_CLANG \
         -d CFI \
         -d CFI_PERMISSIVE \
         -d CFI_CLANG
    (cd ${OUT_DIR} && \
     make O=${OUT_DIR} $archsubarch CC=${CC} CROSS_COMPILE=${CROSS_COMPILE} olddefconfig)
}

找出核心版本

您可以從兩個來源找出要建構的正確版本：AOSP 樹狀結構和系統映像檔。

來自 AOSP 樹狀結構的核心版本

Android 開放原始碼計畫樹狀結構包含預先建構的核心版本。Git 記錄會在修訂版本訊息中顯示正確的版本：

cd $AOSP/device/VENDOR/NAME
git log --max-count=1

如果 git 記錄中未列出核心版本，請從系統映像檔取得，如下所述。

系統映像檔的核心版本

如要判斷系統映像檔中使用的核心版本，請對核心檔案執行下列指令：

file kernel

針對 Image.lz4-dtb 檔案，請執行：

grep -a 'Linux version' Image.lz4-dtb

建構開機映像檔

您可以使用核心建構環境建構開機映像檔。

為使用 init_boot 的裝置建構開機映像檔

對於具有init_boot 分區的裝置，開機映像檔會與核心一併建構。系統未在啟動映像檔中嵌入 initramfs 映像檔。

舉例來說，您可以使用 Kleaf 建構 GKI 開機映像檔，方法如下：

tools/bazel run //common:kernel_aarch64_dist [-- --destdir=$DIST_DIR]

使用 build/build.sh (舊版) 時，您可以使用以下方式建構 GKI 開機映像檔：

BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh

GKI 開機映像檔位於 $DIST_DIR 中。

為沒有 init_boot 的裝置建構開機映像檔 (舊版)

如果裝置沒有init_boot 分割區，您需要使用 RAM 磁碟二進位檔，您可以下載 GKI 開機映像檔並解壓縮來取得。任何來自相關 Android 版本的 GKI 開機映像檔都適用。

tools/mkbootimg/unpack_bootimg.py --boot_img=boot-5.4-gz.img
mv $KERNEL_ROOT/out/ramdisk gki-ramdisk.lz4

目標資料夾是核心樹狀圖的頂層目錄 (目前的工作目錄)。

如果您使用的是最新的 AOSP 發布分支，可以改為從 ci.android.com 的 aosp_arm64 版本下載 ramdisk-recovery.img 建構成果物，並將其用於 RAM 磁碟二進位檔。

當您取得 RAMDISK 二進位檔並將其複製至核心版本的根目錄 gki-ramdisk.lz4 後，您可以執行以下指令產生開機映像檔：

BUILD_BOOT_IMG=1 SKIP_VENDOR_BOOT=1 KERNEL_BINARY=Image GKI_RAMDISK_PREBUILT_BINARY=gki-ramdisk.lz4 BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh

如果您使用以 x86 為基礎的架構，請將 Image 替換為 bzImage，並將 aarch64 替換為 x86_64：

BUILD_BOOT_IMG=1 SKIP_VENDOR_BOOT=1 KERNEL_BINARY=bzImage GKI_RAMDISK_PREBUILT_BINARY=gki-ramdisk.lz4 BUILD_CONFIG=common/build.config.gki.x86_64 build/build.sh

該檔案位於 $KERNEL_ROOT/out/$KERNEL_VERSION/dist 的構件目錄中。

啟動映像檔位於 out/<kernel branch>/dist/boot.img。