Thêm một thiết bị mới

Sử dụng thông tin trên trang này để tạo tệp tạo tệp cho thiết bị và sản phẩm của bạn.

Mỗi mô-đun Android mới phải có tệp cấu hình để điều khiển hệ thống xây dựng bằng siêu dữ liệu mô-đun, các phần phụ thuộc tại thời điểm biên dịch và hướng dẫn đóng gói. Android sử dụng hệ thống xây dựng Soong . Xem Xây dựng Android để biết thêm thông tin về hệ thống xây dựng Android.

Hiểu các lớp xây dựng

Hệ thống phân cấp bản dựng bao gồm các lớp trừu tượng tương ứng với cấu trúc vật lý của thiết bị. Các lớp này được mô tả trong bảng dưới đây. Mỗi lớp liên quan đến lớp ở trên nó theo mối quan hệ một-nhiều. Ví dụ: một kiến ​​trúc có thể có nhiều bảng và mỗi bảng có thể có nhiều sản phẩm. Bạn có thể xác định một phần tử trong một lớp nhất định là sự chuyên biệt hóa của một phần tử trong cùng một lớp, điều này giúp loại bỏ việc sao chép và đơn giản hóa việc bảo trì.

Lớp Ví dụ Sự miêu tả
Sản phẩm myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk Lớp sản phẩm xác định đặc tả tính năng của sản phẩm vận chuyển chẳng hạn như mô-đun cần xây dựng, các ngôn ngữ được hỗ trợ và cấu hình cho các ngôn ngữ khác nhau. Nói cách khác, đây là tên của sản phẩm tổng thể. Các biến dành riêng cho sản phẩm được xác định trong tệp định nghĩa sản phẩm. Một sản phẩm có thể kế thừa từ các định nghĩa sản phẩm khác, giúp đơn giản hóa việc bảo trì. Một phương pháp phổ biến là tạo một sản phẩm cơ sở có chứa các tính năng áp dụng cho tất cả sản phẩm, sau đó tạo các biến thể sản phẩm dựa trên sản phẩm cơ sở đó. Ví dụ: hai sản phẩm chỉ khác nhau ở radio (CDMA so với GSM) có thể kế thừa từ cùng một sản phẩm cơ bản không xác định radio.
Bảng/thiết bị marlin, blueline, san hô Lớp bo mạch/thiết bị đại diện cho lớp nhựa vật lý trên thiết bị (nghĩa là kiểu dáng công nghiệp của thiết bị). Lớp này cũng đại diện cho sơ đồ trần của sản phẩm. Chúng bao gồm các thiết bị ngoại vi trên bo mạch và cấu hình của chúng. Tên được sử dụng chỉ đơn thuần là mã cho các cấu hình bo mạch/thiết bị khác nhau.
Vòm cánh tay, x86, cánh tay64, x86_64 Lớp kiến ​​trúc mô tả cấu hình bộ xử lý và giao diện nhị phân ứng dụng (ABI) đang chạy trên bo mạch.

Sử dụng các biến thể xây dựng

Khi xây dựng cho một sản phẩm cụ thể, việc có những thay đổi nhỏ trên bản phát hành cuối cùng sẽ rất hữu ích. Trong định nghĩa mô-đun, mô-đun có thể chỉ định các thẻ có LOCAL_MODULE_TAGS , có thể là một hoặc nhiều giá trị optional (mặc định), debugeng .

Nếu một mô-đun không chỉ định thẻ (theo LOCAL_MODULE_TAGS ), thẻ của nó sẽ mặc định là optional . Mô-đun tùy chọn chỉ được cài đặt nếu cấu hình sản phẩm có PRODUCT_PACKAGES yêu cầu.

Đây là các biến thể xây dựng hiện được xác định.

Khác nhau Sự miêu tả
eng Đây là hương vị mặc định.
  • Cài đặt các mô-đun được gắn thẻ eng hoặc debug .
  • Cài đặt các mô-đun theo tệp định nghĩa sản phẩm, ngoài các mô-đun được gắn thẻ.
  • ro.secure=0
  • ro.debuggable=1
  • ro.kernel.android.checkjni=1
  • adb được bật theo mặc định.
user Biến thể dự định là bit phát hành cuối cùng.
  • Cài đặt các mô-đun được gắn thẻ với user .
  • Cài đặt các mô-đun theo tệp định nghĩa sản phẩm, ngoài các mô-đun được gắn thẻ.
  • ro.secure=1
  • ro.debuggable=0
  • adb bị tắt theo mặc định.
userdebug Tương tự như user , với những ngoại lệ sau:
  • Đồng thời cài đặt các mô-đun được gắn thẻ debug .
  • ro.debuggable=1
  • adb được bật theo mặc định.

Hướng dẫn gỡ lỗi người dùng

Chạy các bản dựng userdebug trong quá trình thử nghiệm giúp các nhà phát triển thiết bị hiểu được hiệu suất và sức mạnh của các bản phát hành đang trong quá trình phát triển. Để duy trì tính nhất quán giữa các bản dựng người dùng và bản gỡ lỗi người dùng, đồng thời để đạt được số liệu đáng tin cậy trong các bản dựng dùng để gỡ lỗi, nhà phát triển thiết bị nên tuân theo các nguyên tắc sau:

  • userdebug được định nghĩa là bản dựng người dùng có bật quyền truy cập root, ngoại trừ:
    • Các ứng dụng chỉ gỡ lỗi người dùng chỉ được người dùng chạy theo yêu cầu
    • Các hoạt động chỉ chạy trong thời gian bảo trì không tải (trên bộ sạc/đã sạc đầy), chẳng hạn như sử dụng dex2oatd so với dex2oat để biên dịch nền
  • Không bao gồm các tính năng được bật/tắt theo mặc định dựa trên loại bản dựng. Các nhà phát triển không được khuyến khích sử dụng bất kỳ hình thức ghi nhật ký nào ảnh hưởng đến tuổi thọ pin, chẳng hạn như ghi nhật ký gỡ lỗi hoặc kết xuất vùng lưu trữ.
  • Mọi tính năng gỡ lỗi được bật theo mặc định trong userdebug phải được xác định rõ ràng và chia sẻ với tất cả các nhà phát triển làm việc trong dự án. Bạn chỉ nên bật các tính năng gỡ lỗi trong một khoảng thời gian giới hạn cho đến khi sự cố bạn đang cố gắng gỡ lỗi được giải quyết.

Tùy chỉnh bản dựng với lớp phủ tài nguyên

Hệ thống xây dựng Android sử dụng lớp phủ tài nguyên để tùy chỉnh sản phẩm tại thời điểm xây dựng. Lớp phủ tài nguyên chỉ định các tệp tài nguyên được áp dụng trên các giá trị mặc định. Để sử dụng lớp phủ tài nguyên, hãy sửa đổi tệp xây dựng dự án để đặt PRODUCT_PACKAGE_OVERLAYS thành đường dẫn tương ứng với thư mục cấp cao nhất của bạn. Đường dẫn đó trở thành gốc ẩn được tìm kiếm cùng với gốc hiện tại khi hệ thống xây dựng tìm kiếm tài nguyên.

Các cài đặt được tùy chỉnh phổ biến nhất được chứa trong tệp frameworks/base/core/res/res/values/config.xml .

Để thiết lập lớp phủ tài nguyên trên tệp này, hãy thêm thư mục lớp phủ vào tệp bản dựng dự án bằng một trong các cách sau:

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

hoặc

PRODUCT_PACKAGE_OVERLAYS := vendor/vendor-name/overlay

Sau đó, thêm tệp lớp phủ vào thư mục, ví dụ:

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

Bất kỳ chuỗi hoặc mảng chuỗi nào được tìm thấy trong tệp config.xml lớp phủ sẽ thay thế các chuỗi được tìm thấy trong tệp gốc.

Xây dựng một sản phẩm

Bạn có thể sắp xếp các tệp nguồn cho thiết bị của mình theo nhiều cách khác nhau. Dưới đây là mô tả ngắn gọn về một cách tổ chức triển khai Pixel.

Pixel được triển khai với cấu hình thiết bị chính có tên marlin . Từ cấu hình thiết bị này, một sản phẩm được tạo bằng tệp định nghĩa sản phẩm để khai báo thông tin dành riêng cho sản phẩm về thiết bị như tên và kiểu máy. Bạn có thể xem thư mục device/google/marlin để xem tất cả những thứ này được thiết lập như thế nào.

Viết makefiles sản phẩm

Các bước sau đây mô tả cách thiết lập tệp tạo tệp sản phẩm theo cách tương tự như cách của dòng sản phẩm Pixel:

  1. Tạo thư mục device/ <company-name> / <device-name> cho sản phẩm của bạn. Ví dụ: device/google/marlin . Thư mục này sẽ chứa mã nguồn cho thiết bị của bạn cùng với các tệp tạo tệp để xây dựng chúng.
  2. Tạo một tệp thực hiện device.mk để khai báo các tệp và mô-đun cần thiết cho thiết bị. Để biết ví dụ, hãy xem device/google/marlin/device-marlin.mk .
  3. Tạo tệp định nghĩa sản phẩm để tạo một sản phẩm cụ thể dựa trên thiết bị. Tệp makefile sau được lấy từ device/google/marlin/aosp_marlin.mk làm ví dụ. Lưu ý rằng sản phẩm kế thừa từ các tệp device/google/marlin/device-marlin.mkvendor/google/marlin/device-vendor-marlin.mk thông qua tệp thực hiện đồng thời khai báo thông tin dành riêng cho sản phẩm như tên, nhãn hiệu, và mô hình.
    # 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
    

    Xem Đặt biến định nghĩa sản phẩm để biết thêm các biến dành riêng cho sản phẩm mà bạn có thể thêm vào tệp tạo tệp của mình.

  4. Tạo tệp AndroidProducts.mk trỏ đến tệp tạo tệp của sản phẩm. Trong ví dụ này, chỉ cần có tệp định nghĩa sản phẩm. Ví dụ bên dưới là từ device/google/marlin/AndroidProducts.mk (chứa cả marlin, Pixel và Sailfish, Pixel XL, có chung hầu hết cấu hình):
    PRODUCT_MAKEFILES := \
    	$(LOCAL_DIR)/aosp_marlin.mk \
    	$(LOCAL_DIR)/aosp_sailfish.mk
    
    COMMON_LUNCH_CHOICES := \
    	aosp_marlin-userdebug \
    	aosp_sailfish-userdebug
    
  5. Tạo tệp thực hiện BoardConfig.mk có chứa các cấu hình dành riêng cho bảng. Để biết ví dụ, hãy xem device/google/marlin/BoardConfig.mk .
  6. Chỉ dành cho Android 9 trở xuống , hãy tạo tệp vendorsetup.sh để thêm sản phẩm của bạn ("kết hợp bữa trưa") vào bản dựng cùng với một biến thể bản dựng được phân tách bằng dấu gạch ngang. Ví dụ:
    add_lunch_combo <product-name>-userdebug
    
  7. Tại thời điểm này, bạn có thể tạo nhiều biến thể sản phẩm hơn trên cùng một thiết bị.

Đặt biến định nghĩa sản phẩm

Các biến dành riêng cho sản phẩm được xác định trong tệp thực hiện của sản phẩm. Bảng hiển thị một số biến được duy trì trong tệp định nghĩa sản phẩm.

Biến đổi Sự miêu tả Ví dụ
PRODUCT_AAPT_CONFIG cấu hình aapt để sử dụng khi tạo gói.
PRODUCT_BRAND Thương hiệu (ví dụ: nhà cung cấp dịch vụ) mà phần mềm được tùy chỉnh.
PRODUCT_CHARACTERISTICS đặc điểm aapt để cho phép thêm tài nguyên dành riêng cho biến thể vào gói. tablet , nosdcard
PRODUCT_COPY_FILES Danh sách các từ như source_path:destination_path . Tệp ở đường dẫn nguồn phải được sao chép sang đường dẫn đích khi xây dựng sản phẩm này. Quy tắc cho các bước sao chép được xác định trong config/makefile .
PRODUCT_DEVICE Tên kiểu dáng công nghiệp. Đây cũng là tên bảng và hệ thống xây dựng sử dụng nó để định vị BoardConfig.mk . tuna
PRODUCT_LOCALES Danh sách mã ngôn ngữ gồm hai chữ cái được phân tách bằng dấu cách, các cặp mã quốc gia gồm hai chữ cái mô tả một số cài đặt cho người dùng, chẳng hạn như ngôn ngữ giao diện người dùng và định dạng thời gian, ngày tháng và tiền tệ. Ngôn ngữ đầu tiên được liệt kê trong PRODUCT_LOCALES được sử dụng làm ngôn ngữ mặc định của sản phẩm. en_GB , de_DE , es_ES , fr_CA
PRODUCT_MANUFACTURER Tên của nhà sản xuất. acme
PRODUCT_MODEL Tên hiển thị của người dùng cuối cho sản phẩm cuối cùng.
PRODUCT_NAME Tên mà người dùng cuối có thể nhìn thấy đối với sản phẩm tổng thể. Xuất hiện trong màn hình Cài đặt > Giới thiệu .
PRODUCT_OTA_PUBLIC_KEYS Danh sách khóa công khai qua mạng (OTA) cho sản phẩm.
PRODUCT_PACKAGES Danh sách các APK và mô-đun cần cài đặt. Danh bạ trên lịch
PRODUCT_PACKAGE_OVERLAYS Cho biết nên sử dụng tài nguyên mặc định hay thêm bất kỳ lớp phủ cụ thể nào của sản phẩm. vendor/acme/overlay
PRODUCT_SYSTEM_PROPERTIES Danh sách các phép gán thuộc tính hệ thống ở định dạng "key=value" cho phân vùng hệ thống. Thuộc tính hệ thống cho các phân vùng khác có thể được đặt thông qua PRODUCT_<PARTITION>_PROPERTIES như trong PRODUCT_VENDOR_PROPERTIES cho phân vùng nhà cung cấp. Tên phân vùng được hỗ trợ: SYSTEM , VENDOR , ODM , SYSTEM_EXTPRODUCT .

Định cấu hình ngôn ngữ hệ thống mặc định và bộ lọc ngôn ngữ

Sử dụng thông tin này để định cấu hình ngôn ngữ mặc định và bộ lọc ngôn ngữ hệ thống, sau đó bật bộ lọc ngôn ngữ cho loại thiết bị mới.

Của cải

Định cấu hình cả ngôn ngữ mặc định và bộ lọc ngôn ngữ hệ thống bằng các thuộc tính hệ thống chuyên dụng:

  • ro.product.locale : để đặt ngôn ngữ mặc định. Điều này ban đầu được đặt thành ngôn ngữ đầu tiên trong biến PRODUCT_LOCALES ; bạn có thể ghi đè giá trị đó. (Để biết thêm thông tin, hãy xem bảng Cài đặt các biến định nghĩa sản phẩm .)
  • ro.localization.locale_filter : để đặt bộ lọc ngôn ngữ, sử dụng biểu thức chính quy được áp dụng cho tên ngôn ngữ. Ví dụ:
    • Bộ lọc bao gồm: ^(de-AT|de-DE|en|uk).* - chỉ cho phép tiếng Đức (các biến thể Áo và Đức), tất cả các biến thể tiếng Anh của tiếng Anh và tiếng Ukraina
    • Bộ lọc độc quyền: ^(?!de-IT|es).* - không bao gồm tiếng Đức (biến thể ở Ý) và tất cả các biến thể của tiếng Tây Ban Nha.

Kích hoạt bộ lọc ngôn ngữ

Để bật bộ lọc, hãy đặt giá trị chuỗi thuộc tính hệ thống ro.localization.locale_filter .

Bằng cách đặt giá trị thuộc tính bộ lọc và ngôn ngữ mặc định thông qua oem/oem.prop trong quá trình hiệu chỉnh tại nhà máy, bạn có thể định cấu hình các hạn chế mà không cần đưa bộ lọc vào hình ảnh hệ thống. Bạn đảm bảo rằng các thuộc tính này được chọn từ phân vùng OEM bằng cách thêm chúng vào biến PRODUCT_OEM_PROPERTIES như được chỉ ra bên dưới:

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

Sau đó, trong quá trình sản xuất, các giá trị thực tế được ghi vào oem/oem.prop để phản ánh các yêu cầu mục tiêu. Với phương pháp này, các giá trị mặc định được giữ lại trong quá trình khôi phục cài đặt gốc, do đó, cài đặt ban đầu trông giống hệt như cài đặt đầu tiên đối với người dùng.

Đặt ADB_VENDOR_KEYS để kết nối qua USB

Biến môi trường ADB_VENDOR_KEYS cho phép nhà sản xuất thiết bị truy cập vào các bản dựng có thể gỡ lỗi (-userdebug và -eng, nhưng không phải -user) qua adb mà không cần ủy quyền thủ công. Thông thường, adb tạo khóa xác thực RSA duy nhất cho mỗi máy khách. Khóa này sẽ gửi đến bất kỳ thiết bị được kết nối nào. Đây là khóa RSA được hiển thị trong hộp thoại ủy quyền adb. Để thay thế, bạn có thể tạo các khóa đã biết vào hình ảnh hệ thống và chia sẻ chúng với ứng dụng khách adb. Điều này hữu ích cho việc phát triển hệ điều hành và đặc biệt là cho việc thử nghiệm vì nó tránh được việc phải tương tác thủ công với hộp thoại ủy quyền adb.

Để tạo khóa của nhà cung cấp, một người (thường là người quản lý phát hành) nên:

  1. Tạo cặp khóa bằng adb keygen . Đối với các thiết bị của Google, Google tạo cặp khóa mới cho mỗi phiên bản hệ điều hành mới.
  2. Kiểm tra các cặp khóa ở đâu đó trong cây nguồn. Ví dụ: Google lưu trữ chúng trong vendor/google/security/adb/ .
  3. Đặt biến bản dựng PRODUCT_ADB_KEYS để trỏ tới thư mục chính của bạn. Google thực hiện điều này bằng cách thêm tệp Android.mk vào thư mục khóa có nội dung PRODUCT_ADB_KEYS := $(LOCAL_PATH)/$(PLATFORM_VERSION).adb_key.pub , giúp đảm bảo rằng chúng tôi nhớ tạo cặp khóa mới cho mỗi phiên bản hệ điều hành.

Đây là tệp tạo tệp mà Google sử dụng trong thư mục nơi chúng tôi lưu trữ các cặp khóa đã đăng ký cho mỗi bản phát hành:

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

Để sử dụng các khóa của nhà cung cấp này, kỹ sư chỉ cần đặt biến môi trường ADB_VENDOR_KEYS để trỏ đến thư mục lưu trữ các cặp khóa. Điều này yêu cầu adb thử các khóa chuẩn này trước khi quay lại khóa máy chủ đã tạo yêu cầu ủy quyền thủ công. Khi adb không thể kết nối với thiết bị trái phép, thông báo lỗi sẽ đề xuất bạn đặt ADB_VENDOR_KEYS nếu thiết bị này chưa được đặt.