הוספת מכשיר חדש

אפשר להשתמש במידע שבדף הזה כדי ליצור את קובצי ה-Makefile למכשיר המוצר.

כל מודול Android חדש צריך לכלול קובץ תצורה כדי לכוון את מערכת ה-build עם מטא-נתונים של המודול, יחסי תלות בזמן הידור והוראות אריזה. מערכת Android משתמשת ב מערכת build של Soong. למידע נוסף על Android, ראו יצירת Android של מערכת ה-build.

הסבר על שכבות build

היררכיית ה-build כוללת את שכבות ההפשטה שתואמות המבנה הפיזי של המכשיר. השכבות האלה מתוארות בטבלה שבהמשך. כל שכבה מתייחסת לזו שמעליה בקשר אחד לרבים. עבור ארכיטקטורה יכולה לכלול יותר מלוח אחד וכל לוח יכול להכיל יותר ממוצר אחד. אפשר להגדיר רכיב בשכבה נתונה כ של רכיב באותה שכבה, וכך מבטל העתקה מפשט את התחזוקה.

שכבה דוגמה תיאור
מוצר myProduct, myProduct_eu, myProduct_eu_fr, j2, sdk שכבת המוצרים מגדירה את מפרט התכונות של משלוח כמו המודולים ל-build, לוקאלים נתמכים את התצורה של השפות השונות. במילים אחרות, זה השם של המוצר כולו. משתנים ספציפיים למוצר מוגדרים כאן קובצי makefile של הגדרת מוצר. מוצר יכול לקבל בירושה הגדרות של מוצר מסוים, שמפשטות את התחזוקה שלהן. שיטה נפוצה הוא ליצור מוצר בסיס שכולל תכונות שרלוונטיות את כל המוצרים, ואז ליצור וריאציות מוצר על סמך הבסיס הזה המוצר. לדוגמה, שני מוצרים שההבדל היחיד ביניהם הוא מכשירי הרדיו (CDMA לעומת GSM) יכולים לרשת את אותו מוצר בסיסי לא מגדיר רדיו.
לוח/מכשיר מרלין, כחול, קורל שכבת הלוחות/מכשיר מייצגת את השכבה הפיזית של הפלסטיק המכשיר (כלומר, העיצוב התעשייתי של המכשיר). השכבה הזאת מייצגת גם של המוצר. הציוד הזה כולל את הציוד ההיקפי על הלוח הגדרה אישית. השמות בשימוש הם רק קודים של לוח/מכשיר שונים הגדרות אישיות.
קשת Arm, x86, arm64, x86_64 שכבת הארכיטקטורה מתארת את תצורת המעבד ממשק בינארי של אפליקציה (ABI) שפועל על הלוח.

שימוש בווריאציות build

כאשר אתם בונים מוצר מסוים, עדיף להוסיף ל-build של הגרסה הסופית. במודול המודול יכול לציין תגים עם LOCAL_MODULE_TAGS, שיכול להיות ערך אחד או יותר של optional (ברירת מחדל), debug ו-eng.

אם מודול לא מציין תג (על ידי LOCAL_MODULE_TAGS), ערך ברירת המחדל של התג הוא optional. מודול אופציונלי מותקן רק אם הוא נדרש על ידי הגדרת המוצר באמצעות PRODUCT_PACKAGES.

אלה גרסאות ה-build שמוגדרות כרגע.

וריאנט תיאור
eng זהו טעם ברירת המחדל.
  • התקנת מודולים שתויגו ב-eng או ב-debug.
  • התקנת מודולים בהתאם לקובצי הגדרות המוצר, בנוסף למודולים מתויגים.
  • ro.secure=0
  • ro.debuggable=1
  • ro.kernel.android.checkjni=1
  • כברירת מחדל, adb מופעל.
user הווריאנט נועד להיות הביטים האחרונים של הגרסה.
  • התקנת מודולים שתויגו ב-user.
  • התקנת מודולים בהתאם לקובצי הגדרות המוצר, בנוסף למודולים מתויגים.
  • ro.secure=1
  • ro.debuggable=0
  • כברירת מחדל, adb מושבת.
userdebug זהה ל-user, למעט החריגים הבאים:
  • מתקין גם מודולים שתויגו ב-debug.
  • ro.debuggable=1
  • כברירת מחדל, adb מופעל.

הנחיות לניפוי באגים אצל משתמשים

הרצת גרסאות build של ניפוי באגים על ידי משתמשים לצורך בדיקות עוזרת למפתחי מכשירים להבין את הביצועים והעוצמה של גרסאות פיתוח. כדי לשמור על עקביות בין גרסאות build של משתמשים לבין גרסאות build לניפוי באגים, וכדי להשיג מדדים אמינים בגרסאות build לניפוי באגים, מפתחי מכשירים צריכים לפעול בהתאם להנחיות הבאות:

  • userdebug מוגדר כ-build של משתמש שהופעלה בו גישה לרמה הבסיסית (root), למעט:
    • אפליקציות לניפוי באגים בלבד שמופעלות על פי דרישה בלבד על ידי המשתמש
    • פעולות שפועלות רק במהלך תחזוקה ללא פעילות (במטען/באופן מלא) חויב), למשל, באמצעות dex2oatd לעומת dex2oat להדרות ברקע
  • אסור לכלול תכונות שמופעלות או מושבתות כברירת מחדל בהתאם לסוג ה-build. מומלץ למפתחים לא להשתמש באף סוג של רישום ביומן שמשפיע על חיי הסוללה, כמו רישום ביומן של ניפוי באגים או תמונת מצב של הזיכרון.
  • צריך להגדיר בבירור את כל התכונות לניפוי באגים שמופעלות כברירת מחדל בניפוי באגים ברמת המשתמש והוא משותף עם כל המפתחים שעובדים על הפרויקט. צריך להפעיל את התכונות לניפוי באגים רק לזמן מוגבל, עד לפתרון הבעיה שניסיתם לנפות באגים.

התאמה אישית של ה-build באמצעות שכבות-על של משאבים

מערכת ה-build של Android משתמשת בשכבות-על של משאבים כדי להתאים אישית מוצר בזמן ה-build. שכבות-על של משאבים מציינות משאב שקיימים בנוסף לברירות המחדל. כדי להשתמש בשכבות-על של משאבים, צריך לשנות את הפרויקט buildfile כדי להגדיר את PRODUCT_PACKAGE_OVERLAYS יחסית לספרייה ברמה העליונה. הנתיב הופך לשורש של הצל שמופיע בחיפוש יחד עם הרמה הבסיסית (root) הנוכחית, כשמערכת ה-build תחפש משאבים.

ההגדרות שהכי הרבה פעמים מותאמות אישית נמצאות בקובץ frameworks/base/core/res/res/values/config.xml.

כדי להגדיר שכבת-על של משאבים בקובץ הזה, צריך להוסיף את ספריית שכבת-העל buildfile של פרויקט באמצעות אחת מהאפשרויות הבאות:

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 כדי לראות איך כל זה מוגדר.

כתיבת קובצי cookie של מוצרים

בשלבים הבאים מוסבר איך להגדיר קובצי cookie של מוצרים באופן דומה לזה של קו המוצרים של Pixel:

  1. יצירת device/<company-name>/<device-name> ספרייה עבור המוצר. לדוגמה: device/google/marlin. הספרייה הזו תכיל את קוד המקור עבור המכשיר, ביחד עם קובצי ה-Makefile כדי לבנות אותם.
  2. יוצרים קובץ createfile device.mk שמצהיר על הקבצים והמודולים הנדרשים בשביל במכשיר. לדוגמה, אפשר להיכנס אל device/google/marlin/device-marlin.mk.
  3. אפשר ליצור קובץ makefile של הגדרת מוצר כדי ליצור מוצר ספציפי בהתאם למכשיר. examplefile שכאן, נלקחת מ-device/google/marlin/aosp_marlin.mk כדוגמה. שימו לב שהמוצר יורש device/google/marlin/device-marlin.mk והקבוצה vendor/google/marlin/device-vendor-marlin.mk קבצים דרך קובץ makefile בזמן גם להצהיר על מידע ספציפי למוצר, כמו שם, מותג ודגם. 
    # 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. יוצרים קובץ AndroidProducts.mk שמפנה לקובצי ה-Mac של המוצר. לחשבון בדוגמה הזו, יש צורך רק בקובץ getfile של הגדרת המוצר. הדוגמה הבאה היא device/google/marlin/AndroidProducts.mk (שמכיל גם את marlin וגם את Pixel, ו-sailfish, ה-Pixel XL ששיתף את רוב ההגדרות): 
    PRODUCT_MAKEFILES := \
	$(LOCAL_DIR)/aosp_marlin.mk \
	$(LOCAL_DIR)/aosp_sailfish.mk

COMMON_LUNCH_CHOICES := \
	aosp_marlin-userdebug \
	aosp_sailfish-userdebug
  5. יוצרים קובץ makefile BoardConfig.mk שמכיל הגדרות ספציפיות ללוח. לדוגמה, אפשר להיכנס אל device/google/marlin/BoardConfig.mk.
  6. ב-Android 9 ומטה רק, יוצרים קובץ vendorsetup.sh שצריך להוסיף אליו את המוצר ('שילוב ארוחת צהריים') את ה-build וגם וריאנט build שמופרדות במקף. מוצרים לדוגמה: 
    add_lunch_combo <product-name>-userdebug
  7. בשלב הזה תוכלו ליצור עוד וריאציות של המוצר לפי אותו מכשיר.

הגדרת משתנים של הגדרת מוצרים

משתנים ספציפיים למוצר מוגדרים בקובץ makefile של המוצר. בטבלה מוצגים חלק של המשתנים בקובץ הגדרת המוצרים.

משתנה תיאור דוגמה
PRODUCT_AAPT_CONFIG הגדרות של aapt לשימוש כשיוצרים חבילות.
PRODUCT_BRAND המותג (לדוגמה, הספק) שהתוכנה מותאמת לו.
PRODUCT_CHARACTERISTICS aapt מאפיינים שמאפשרים להוסיף לחבילה משאבים ספציפיים לווריאנט. tablet, nosdcard
PRODUCT_COPY_FILES רשימה של מילים כמו source_path:destination_path. הקובץ בנתיב המקור צריך להעתיק את הנתיב לנתיב היעד במהלך בניית המוצר. כללים לגבי ההעתקה השלבים מוגדרים ב-config/makefile.
PRODUCT_DEVICE שם העיצוב התעשייתי. זה גם שם ה-board, ומערכת ה-build משתמשת בו. כדי לאתר את BoardConfig.mk. tuna
PRODUCT_LOCALES רשימה מופרדת ברווחים של קודי שפה בני שתי אותיות, צמדי קודי מדינות בני שתי אותיות שמתארות כמה הגדרות עבור המשתמש, כמו השפה והשעה של ממשק המשתמש, תאריך, פורמט המטבע. הלוקאל הראשון שרשום ב-PRODUCT_LOCALES משמש כ- לוקאל ברירת המחדל של המוצר. en_GB, de_DE, es_ES, fr_CA
PRODUCT_MANUFACTURER שם היצרן. acme
PRODUCT_MODEL שם של מוצר הקצה שגלוי למשתמש הקצה.
PRODUCT_NAME שם של המוצר הכולל שמוצג למשתמש הקצה. מופיע בקטע הגדרות > מידע כללי.
PRODUCT_OTA_PUBLIC_KEYS רשימה של מפתחות ציבוריים אלחוטיים (OTA) למוצר.
PRODUCT_PACKAGES רשימה של חבילות ה-APK והמודולים להתקנה. אנשי קשר ביומן
PRODUCT_PACKAGE_OVERLAYS מציין אם להשתמש במשאבים שמוגדרים כברירת מחדל או להוסיף שכבות-על ספציפיות למוצר. vendor/acme/overlay
PRODUCT_SYSTEM_PROPERTIES רשימה של ההקצאות של מאפייני המערכת בפורמט "key=value" עבור על מחיצת המערכת. ניתן להגדיר מאפייני מערכת למחיצות אחרות דרך PRODUCT_<PARTITION>_PROPERTIES כמו ב- PRODUCT_VENDOR_PROPERTIES של קטגוריית הספק. מחיצה נתמכת שמות: SYSTEM, VENDOR, ODM, SYSTEM_EXT ו-PRODUCT.

הגדרת מסנן ברירת המחדל של שפת המערכת והלוקאל

צריך להשתמש במידע הזה כדי להגדיר את מסנן ברירת המחדל של השפה והלוקאל של המערכת, ולאחר מכן להפעיל מסנן הלוקאלים לסוג מכשיר חדש.

מאפיינים

מגדירים את שפת ברירת המחדל ואת מסנן הלוקאלים של המערכת באמצעות מערכת ייעודית נכסים:

  • 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 במהלך כיול להגדרות המקוריות אפשר להגדיר הגבלות בלי להוסיף את הפילטר לתמונת המערכת. כדי לוודא שהמאפיינים האלה נאספים ממחיצת ה-OEM, אתם צריכים להוסיף אותם אל משתנה PRODUCT_OEM_PROPERTIES כפי שמצוין בהמשך:

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

בשלב הייצור, הערכים בפועל נכתבים אל oem/oem.prop כדי לשקף את היעד. בדרישות שלנו. בגישה הזו, ערכי ברירת המחדל נשמרים במהלך האיפוס להגדרות המקוריות, כך ההגדרות הראשוניות נראות בדיוק כמו הגדרה ראשונה למשתמש.

הגדרת ADB_VENDOR_KEYS לחיבור באמצעות USB

משתנה הסביבה ADB_VENDOR_KEYS מאפשר ליצרני המכשירים לגשת גרסאות build שניתן לנפות בהן באגים (-userdebug and -eng, אבל לא -user) ב-adb ללא הרשאה ידנית. בדרך כלל, adb יוצר מפתח אימות RSA ייחודי לכל מחשב לקוח, והוא שולח אותו לכל מכשיר מחובר. זהו מפתח ה-RSA שמוצג בתיבת הדו-שיח להרשאה של adb. בתור אפשר גם ליצור מפתחות ידועים בתמונת המערכת ולשתף אותם עם לקוח ה-adb. האפשרות הזו שימושית לפיתוח של מערכת הפעלה ובמיוחד לבדיקות, כי היא מונעת את הצורך לקיים אינטראקציה עם תיבת הדו-שיח לאישור adb.

כדי ליצור מפתחות ספק, אדם אחד (בדרך כלל מנהל גרסאות) צריך:

  1. יצירת זוג מפתחות באמצעות adb keygen. עבור מכשירי Google, Google יוצרת זוג מפתחות לכל גרסה חדשה של מערכת הפעלה.
  2. בודקים את זוגות המפתחות, במקום כלשהו בעץ המקור. Google שומרת אותם ב- למשל vendor/google/security/adb/.
  3. מגדירים את משתנה ה-build PRODUCT_ADB_KEYS כדי שיצביע על ספריית המפתחות שלכם. כדי לעשות זאת, Google מוסיפה קובץ Android.mk לספריית המפתחות, PRODUCT_ADB_KEYS := $(LOCAL_PATH)/$(PLATFORM_VERSION).adb_key.pub, עוזרת להבטיח שאנחנו זוכרים ליצור זוג מפתחות חדש לכל גרסה של מערכת ההפעלה.

זהו קובץ ה-Makefile ש-Google משתמשת בו בספרייה שבה אנחנו מאחסנים את זוגות המפתחות ששימשו לצ'ק-אין עבור כל אחד מהם גרסה:

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 אם לא כבר מוגדר.