Triển khai API giản đồ tệp cấu hình

Nền tảng Android chứa nhiều tệp XML để lưu trữ dữ liệu cấu hình (ví dụ: cấu hình âm thanh). Nhiều tệp XML nằm trong phân vùng vendor, nhưng chúng được đọc trong phân vùng system. Trong trường hợp này, giản đồ của tệp XML đóng vai trò là giao diện trên hai phân vùng. Do đó, bạn phải chỉ định rõ ràng giản đồ và giản đồ phải phát triển theo cách tương thích ngược.

Trước Android 10, nền tảng này không cung cấp các cơ chế để yêu cầu chỉ định và sử dụng giản đồ XML, hoặc để ngăn các thay đổi không tương thích trong giản đồ. Android 10 cung cấp cơ chế này, được gọi là Config File Schema API. Cơ chế này bao gồm một công cụ có tên là xsdc và một quy tắc xây dựng có tên là xsd_config.

Công cụ xsdc là trình biên dịch Tài liệu giản đồ XML (XSD). Công cụ này phân tích cú pháp một tệp XSD mô tả lược đồ của một tệp XML và tạo mã Java và C++. Mã được tạo sẽ phân tích cú pháp các tệp XML tuân thủ giản đồ XSD thành một cây đối tượng, mỗi đối tượng mô hình hoá một thẻ XML. Các thuộc tính XML được mô hình hoá dưới dạng các trường của đối tượng.

Quy tắc bản dựng xsd_config tích hợp công cụ xsdc vào hệ thống bản dựng. Đối với một tệp đầu vào XSD nhất định, quy tắc bản dựng sẽ tạo các thư viện Java và C++. Bạn có thể liên kết các thư viện với những mô-đun nơi các tệp XML tuân thủ XSD được đọc và sử dụng. Bạn có thể sử dụng quy tắc bản dựng cho các tệp XML của riêng mình được dùng trên các phân vùng system và vendor.

Build Config File Schema API

Phần này mô tả cách tạo API Giản đồ tệp cấu hình.

Định cấu hình quy tắc bản dựng xsd_config trong Android.bp

Quy tắc xây dựng xsd_config tạo mã trình phân tích cú pháp bằng công cụ xsdc. Thuộc tính package_name của quy tắc xây dựng xsd_config xác định tên gói của mã Java đã tạo.

Ví dụ về quy tắc tạo xsd_config trong Android.bp:

xsd_config {
    name: "hal_manifest",
    srcs: ["hal_manifest.xsd"],
    package_name: "hal.manifest",
}

Cấu trúc thư mục mẫu:

├── Android.bp
├── api
│   ├── current.txt
│   ├── last_current.txt
│   ├── last_removed.txt
│   └── removed.txt
└── hal_manifest.xsd

Hệ thống xây dựng tạo một danh sách API bằng mã Java đã tạo và kiểm tra API dựa trên danh sách đó. Chế độ kiểm tra API này được thêm vào DroidCore và thực thi tại m -j.

Tạo tệp danh sách API

Các quy trình kiểm tra API yêu cầu các tệp danh sách API trong mã nguồn.

Các tệp danh sách API bao gồm:

  • current.txt và removed.txt kiểm tra xem các API có bị thay đổi hay không bằng cách so sánh với các tệp API được tạo tại thời điểm xây dựng.
  • last_current.txt và last_removed.txt kiểm tra xem các API có tương thích ngược hay không bằng cách so sánh với các tệp API.

Cách tạo tệp danh sách API:

  1. Tạo tệp danh sách trống.
  2. Chạy lệnh make update-api.

Dùng mã trình phân tích cú pháp đã tạo

Để sử dụng mã Java đã tạo, hãy thêm : làm tiền tố cho tên mô-đun xsd_config trong thuộc tính srcs của Java. Gói mã Java được tạo giống với thuộc tính package_name.

java_library {
    name: "vintf_test_java",
    srcs: [
        "srcs/**/*.java"
        ":hal_manifest"
    ],
}

Để sử dụng mã C++ đã tạo, hãy thêm tên mô-đun xsd_config vào các thuộc tính generated_sources và generated_headers. Và thêm libxml2 vào static_libs hoặc shared_libs, vì libxml2 là bắt buộc trong mã trình phân tích cú pháp đã tạo. Không gian tên của mã C++ đã tạo giống với thuộc tính package_name. Ví dụ: nếu tên mô-đun xsd_config là hal.manifest, thì không gian tên sẽ là hal::manifest.

cc_library{
    name: "vintf_test_cpp",
    srcs: ["main.cpp"],
    generated_sources: ["hal_manifest"],
    generated_headers: ["hal_manifest"],
    shared_libs: ["libxml2"],
}

Sử dụng trình phân tích cú pháp

Để sử dụng mã trình phân tích cú pháp Java, hãy dùng phương thức XmlParser#read hoặc read{class-name} để trả về lớp của phần tử gốc. Quá trình phân tích cú pháp diễn ra vào thời điểm này.

import hal.manifest.*;

…

class HalInfo {
    public String name;
    public String format;
    public String optional;
    …
}

void readHalManifestFromXml(File file) {
    …
    try (InputStream str = new BufferedInputStream(new FileInputStream(file))) {
        Manifest manifest = XmlParser.read(str);
        for (Hal hal : manifest.getHal()) {
            HalInfo halinfo;
            HalInfo.name = hal.getName();
            HalInfo.format = hal.getFormat();
            HalInfo.optional = hal.getOptional();
            …
        }
    }
    …
}

Để sử dụng mã trình phân tích cú pháp C++, trước tiên, hãy thêm tệp tiêu đề. Tên của tệp tiêu đề là tên gói có dấu chấm (.) được chuyển đổi thành dấu gạch dưới (_). Sau đó, hãy sử dụng phương thức read hoặc read{class-name} để trả về lớp của phần tử gốc. Quá trình phân tích cú pháp diễn ra vào thời điểm này. Giá trị trả về là std::optional<>.

include "hal_manifest.h"

…
using namespace hal::manifest

struct HalInfo {
    public std::string name;
    public std::string format;
    public std::string optional;
    …
};

void readHalManifestFromXml(std::string file_name) {
    …
    Manifest manifest = *read(file_name.c_str());
    for (Hal hal : manifest.getHal()) {
        struct HalInfo halinfo;
        HalInfo.name = hal.getName();
        HalInfo.format = hal.getFormat();
        HalInfo.optional = hal.getOptional();
        …
    }
    …
}

Tất cả các API được cung cấp để sử dụng trình phân tích cú pháp đều nằm trong api/current.txt. Để đảm bảo tính đồng nhất, tất cả tên phần tử và thuộc tính đều được chuyển đổi thành quy tắc viết hoa Camel (ví dụ: ElementName) và được dùng làm tên biến, phương thức và lớp tương ứng. Bạn có thể lấy lớp của phần tử gốc được phân tích cú pháp bằng cách sử dụng hàm read{class-name}. Nếu chỉ có một phần tử gốc, thì tên hàm là read. Bạn có thể lấy giá trị của một thuộc tính hoặc phần tử con được phân tích cú pháp bằng cách sử dụng hàm get{variable-name}.

Tạo mã trình phân tích cú pháp

Trong hầu hết các trường hợp, bạn không cần chạy trực tiếp xsdc. Thay vào đó, hãy sử dụng quy tắc bản dựng xsd_config như mô tả trong phần Định cấu hình quy tắc bản dựng xsd_config trong Android.bp. Phần này giải thích giao diện dòng lệnh xsdc, chỉ để cho đầy đủ. Điều này có thể hữu ích khi gỡ lỗi.

Bạn phải cung cấp cho công cụ xsdc đường dẫn đến tệp XSD và một gói. Gói này là tên gói trong mã Java và là không gian tên trong mã C++. Các lựa chọn để xác định xem mã được tạo là Java hay C lần lượt là -j hoặc -c. Tuỳ chọn -o là đường dẫn của thư mục đầu ra.

usage: xsdc path/to/xsd_file.xsd [-c] [-j] [-o <arg>] [-p]
 -c,--cpp           Generate C++ code.
 -j,--java          Generate Java code.
 -o,--outDir <arg>  Out Directory
 -p,--package       Package name of the generated java file. file name of
                    generated C++ file and header

Ví dụ về lệnh:

$ xsdc audio_policy_configuration.xsd -p audio.policy -j