新增裝置

請使用本頁面的資訊，為裝置和產品建立 Makefile。

每個新的 Android 模組都必須有設定檔，才能使用模組中繼資料、編譯時間依附元件和封裝指示，引導建構系統。Android 使用 Soong 建構系統。如要進一步瞭解 Android 建構系統，請參閱「建構 Android」。

瞭解建構層

建構階層包含與裝置實體組成對應的抽象層。下表說明這些層。每個圖層都與上方的圖層存在一對多關係。舉例來說，一個架構可以有多個主機板，而每個主機板可以有多個產品。您可以在特定圖層中將元素定義為同一圖層中元素的特化，這樣就能避免複製，並簡化維護作業。

使用建構變化版本

為特定產品建構時，最終發布版本的小幅變化很有用。在模組定義中，模組可使用 LOCAL_MODULE_TAGS 指定標記，可以是 optional (預設)、debug 和 eng 的一或多個值。

如果模組未指定標記 (透過 LOCAL_MODULE_TAGS)，標記會預設為 optional。只有在產品設定需要時，才會安裝選用模組 (使用 PRODUCT_PACKAGES)。

這些是目前定義的建構變數。

userdebug 應用規範

在測試中執行 userdebug 建構版本，可協助裝置開發人員瞭解開發中版本的效能和電力。為確保使用者和 userdebug 版本之間的一致性，並在用於偵錯的版本中取得可靠的指標，裝置開發人員應遵守下列指南：

• userdebug 定義為已啟用 Root 存取權的使用者版本，但有以下例外情況：
  • 使用者隨選執行的 userdebug 專用應用程式
  • 僅在閒置維護期間 (充電/充飽電) 執行的作業，例如使用 dex2oatd 與 dex2oat 進行背景編譯
• 請勿加入根據建構類型預設啟用/停用的功能。 建議開發人員避免使用任何會影響電池續航力的記錄形式，例如偵錯記錄或堆積傾印。
• 使用者偵錯版本中預設啟用的所有偵錯功能，都應清楚定義並與專案的所有開發人員分享。您應只在問題解決前啟用偵錯功能。

使用資源疊加層自訂建構作業

Android 建構系統會使用資源疊加層，在建構時自訂產品。資源疊加層會指定要套用在預設值之上的資源檔案。如要使用資源疊加層，請修改專案建構檔案，將 PRODUCT_PACKAGE_OVERLAYS 設為相對於頂層目錄的路徑。建構系統搜尋資源時，該路徑會成為與目前根目錄一起搜尋的陰影根目錄。

最常自訂的設定位於 frameworks/base/core/res/res/values/config.xml 檔案中。

如要在這個檔案上設定資源疊加層，請使用下列任一方法，將疊加層目錄新增至專案建構檔案：

PRODUCT_PACKAGE_OVERLAYS := device/device-implementer/device-name/overlay

或

PRODUCT_PACKAGE_OVERLAYS := vendor/vendor-name/overlay

接著，將疊加層檔案新增至目錄，例如：

vendor/foobar/overlay/frameworks/base/core/res/res/values/config.xml

系統會將疊加層 config.xml 檔案中的所有字串或字串陣列，取代原始檔案中的字串或字串陣列。

打造產品

你可以透過多種方式整理裝置的來源檔案。以下簡要說明一種 Pixel 導入方式。

Pixel 實作時會使用名為 marlin 的主要裝置設定。系統會根據這項裝置設定建立產品，並使用產品定義 Makefile 宣告裝置的產品專屬資訊，例如名稱和型號。您可以查看 device/google/marlin 目錄，瞭解所有設定方式。

撰寫產品 Makefile

下列步驟說明如何設定產品 Makefile，方式與 Pixel 產品線類似：

1. 為產品建立 device/<company-name>/<device-name> 目錄。例如：device/google/marlin。這個目錄會包含裝置的原始碼，以及用於建構這些原始碼的 makefile。
2. 建立 device.mk makefile，宣告裝置所需的檔案和模組。如需範例，請參閱 device/google/marlin/device-marlin.mk。
3. 建立產品定義 Makefile，根據裝置建立特定產品。以下 makefile 是以 device/google/marlin/aosp_marlin.mk 為例。請注意，產品會透過 makefile 從 device/google/marlin/device-marlin.mk 和 vendor/google/marlin/device-vendor-marlin.mk 檔案繼承，同時也會宣告產品專屬資訊，例如名稱、品牌和型號。

   # Inherit from the common Open Source product configuration
   $(call inherit-product, $(SRC_TARGET_DIR)/product/core_64_bit.mk)
   $(call inherit-product, $(SRC_TARGET_DIR)/product/aosp_base_telephony.mk)
   
   PRODUCT_NAME := aosp_marlin
   PRODUCT_DEVICE := marlin
   PRODUCT_BRAND := Android
   PRODUCT_MODEL := AOSP on msm8996
   PRODUCT_MANUFACTURER := Google
   PRODUCT_RESTRICT_VENDOR_FILES := true
   
   PRODUCT_COPY_FILES += device/google/marlin/fstab.common:$(TARGET_COPY_OUT_VENDOR)/etc/fstab.marlin
   
   $(call inherit-product, device/google/marlin/device-marlin.mk)
   $(call inherit-product-if-exists, vendor/google_devices/marlin/device-vendor-marlin.mk)
   
   PRODUCT_PACKAGES += \
       Launcher3QuickStep \
       WallpaperPicker
   

   如需可新增至 Makefile 的其他產品專用變數，請參閱「設定產品定義變數」。

4. 建立指向產品 Makefile 的 AndroidProducts.mk 檔案。在本範例中，只需要產品定義 Makefile。以下範例來自 device/google/marlin/AndroidProducts.mk (其中包含 Pixel (marlin) 和 Pixel XL (sailfish)，兩者共用大部分設定)：

   PRODUCT_MAKEFILES := \
   	$(LOCAL_DIR)/aosp_marlin.mk \
   	$(LOCAL_DIR)/aosp_sailfish.mk
   
   COMMON_LUNCH_CHOICES := \
   	aosp_marlin-userdebug \
   	aosp_sailfish-userdebug
   

5. 建立包含板子專屬設定的 BoardConfig.mk makefile。如需範例，請參閱 device/google/marlin/BoardConfig.mk。
6. 僅適用於 Android 9 以下版本：建立 vendorsetup.sh 檔案，將產品 (「午餐套餐」) 新增至建構作業，並以破折號分隔建構變數。例如：

   add_lunch_combo <product-name>-userdebug
   

7. 此時，您可以根據同一部裝置建立更多產品子類。

設定產品定義變數

產品專屬變數定義在產品的 Makefile 中。下表顯示產品定義檔案中維護的部分變數。

設定預設系統語言和語言代碼篩選器

使用這項資訊設定預設語言和系統地區設定篩選器，然後為新的裝置類型啟用地區設定篩選器。

屬性

使用專屬系統屬性設定預設語言和系統語言代碼篩選器：

• ro.product.locale：用於設定預設語言代碼。這項設定一開始會設為 PRODUCT_LOCALES 變數中的第一個語言代碼，您可以覆寫該值。(詳情請參閱「設定產品定義變數」表格)。
• ro.localization.locale_filter：設定地區設定篩選器，方法是使用套用至地區設定名稱的規則運算式。例如：
  • 包含性篩選器：^(de-AT|de-DE|en|uk).* - 僅允許德文 (奧地利和德國變體)、所有英文變體，以及烏克蘭文
  • 排除篩選器：^(?!de-IT|es).* - 排除德文 (義大利變種版本) 和所有西班牙文變種版本。

啟用語言代碼篩選器

如要啟用篩選器，請設定 ro.localization.locale_filter 系統屬性字串值。

在工廠校準期間，透過 oem/oem.prop 設定篩選器屬性值和預設語言，即可設定限制，不必將篩選器烘焙至系統映像檔。您可將這些屬性新增至 PRODUCT_OEM_PROPERTIES 變數，確保這些屬性是從 OEM 分區中挑選，如下所示：

# Delegation for OEM customization
PRODUCT_OEM_PROPERTIES += \
    ro.product.locale \
    ro.localization.locale_filter

然後在正式版中，實際值會寫入 oem/oem.prop，以反映目標需求。採用這種做法時，恢復原廠設定後會保留預設值，因此使用者看到的初始設定與首次設定完全相同。

設定 ADB_VENDOR_KEYS，透過 USB 連線

裝置製造商可透過 ADB_VENDOR_KEYS 環境變數，透過 adb 存取可偵錯的建構版本 (-userdebug 和 -eng，但不是 -user)，而不需手動授權。一般來說，adb 會為每部用戶端電腦產生專屬的 RSA 驗證金鑰，並傳送至任何已連線的裝置。這是 adb 授權對話方塊中顯示的 RSA 金鑰。或者，您也可以將已知金鑰建構到系統映像檔中，並與 adb 用戶端共用。這項功能有助於 OS 開發，特別是測試，因為這樣就不必手動與 adb 授權對話方塊互動。

如要建立供應商金鑰，請由一人 (通常是發布管理員) 執行下列操作：

1. 使用 adb keygen 產生金鑰組。如果是 Google 裝置，Google 會為每個新版作業系統產生新的金鑰組。
2. 在來源樹狀結構的某處簽入金鑰組。Google 會將這些資料儲存在 vendor/google/security/adb/ 等位置。
3. 將建構變數 PRODUCT_ADB_KEYS 設為指向金鑰目錄。 Google 會在金鑰目錄中新增 Android.mk 檔案，並在其中加入 PRODUCT_ADB_KEYS := $(LOCAL_PATH)/$(PLATFORM_VERSION).adb_key.pub，確保我們記得為每個 OS 版本產生新的金鑰組。

以下是 Google 在目錄中使用的 Makefile，我們會在該目錄中儲存每個版本的已簽入金鑰組：

PRODUCT_ADB_KEYS := $(LOCAL_PATH)/$(PLATFORM_VERSION).adb_key.pub

ifeq ($(wildcard $(PRODUCT_ADB_KEYS)),)
  $(warning ========================)
  $(warning The adb key for this release)
  $(warning )
  $(warning   $(PRODUCT_ADB_KEYS))
  $(warning )
  $(warning does not exist. Most likely PLATFORM_VERSION in build/core/version_defaults.mk)
  $(warning has changed and a new adb key needs to be generated.)
  $(warning )
  $(warning Please run the following commands to create a new key:)
  $(warning )
  $(warning   make -j8 adb)
  $(warning   LOGNAME=android-eng HOSTNAME=google.com adb keygen $(patsubst %.pub,%,$(PRODUCT_ADB_KEYS)))
  $(warning )
  $(warning and upload/review/submit the changes)
  $(warning ========================)
  $(error done)
endif

如要使用這些供應商金鑰，工程師只需設定 ADB_VENDOR_KEYS 環境變數，指向儲存金鑰配對的目錄即可。這會告知 adb 先嘗試使用這些標準金鑰，再回頭使用需要手動授權的產生主機金鑰。如果 adb 無法連線至未經授權的裝置，錯誤訊息會建議你設定 ADB_VENDOR_KEYS (如果尚未設定)。