Khai báo cờ aconfig

Bạn có thể sử dụng các cờ aconfig trong mã Java, C, C++ và Rust. Hệ thống xây dựng AOSP khởi chạy một công cụ có tên là aconfig dùng để tạo thư viện phương thức dành riêng cho ngôn ngữ mà bạn có thể dùng để truy cập vào giá trị của từng cờ. Trước khi có thể tạo thư viện, bạn phải khai báo cờ và thêm cờ vào bản dựng.

Khai báo cờ aconfig cho Java

Cách khai báo cờ aconfig cho Java:

  1. Trong một thư mục có mã mới, hãy tạo một tệp có đuôi .aconfig, ví dụ: my_new_aconfig_flag_declarations.aconfig. Tệp aconfig là tệp proto văn bản tuân theo giản đồ tiêu chuẩn.

  2. Thêm một phần khai báo cờ tương tự như sau:

    package: "com.example.android.aconfig.demo.flags"
container: "system"

flag {
    name: "my_new_flag"
    namespace: "aconfig_demo_namespace"
    description: "This flag controls untested code"
    bug: "<none>"
}

    Trong trường hợp:

    • package khi kết hợp với tên cờ sẽ cung cấp một khoá duy nhất. Trong Java, việc đặt package thành foo.bar sẽ tạo ra một lớp được tạo tự động có tên là foo.bar.Flags. Trong C++, các phương thức truy cập cờ sẽ có tên là foo::bar::"flagname". Các cờ trong cùng một tệp khai báo thuộc cùng một gói, nhưng nhiều tệp khai báo có thể đóng góp cờ cho cùng một gói.

    • container xác định một tập hợp mã được tạo và vận chuyển cùng nhau dưới dạng tệp nhị phân. Các vùng chứa hợp lệ là system, vendor, system_ext, product, name.of.apex, và name.of.apk.

    • name chứa tên của cờ chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.

    • namespace chứa không gian tên cho các đóng góp. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định không gian tên của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng không gian tên theo ý muốn.

    • description chứa nội dung mô tả ngắn gọn về tính năng hoặc thay đổi được gắn cờ.

    • bug là số lỗi liên kết với đóng góp mã mới. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định bug của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng số theo dõi lỗi hoặc sử dụng <none>.

  3. Lưu tệp và thoát khỏi trình chỉnh sửa.

Thiết lập bản dựng

Sau khi khai báo cờ, hãy thiết lập bản dựng để bản dựng có thể tạo mã thư viện dùng để truy cập vào giá trị của cờ.

  1. Trong tệp bản dựng Android.bp, hãy thêm một phần aconfig_declarations tương tự như sau:

    aconfig_declarations {
  name: "aconfig_demo_flags",
  package: "com.example.android.aconfig.demo.flags",
  srcs: [
    "my_new_aconfig_flag_declarations.aconfig"
  ],
}

    Trong trường hợp:

    • name chứa tên của phần khai báo chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.
    • package chứa cùng tên gói được dùng trong phần khai báo.
    • srcs chứa tên của tệp .aconfig nơi cờ được khai báo.

  2. Lưu tệp và thoát khỏi trình chỉnh sửa.

Khai báo cờ aconfig cho C và C++

Cách khai báo cờ aconfig cho C và C++:

  1. Trong một thư mục có mã mới, hãy tạo một tệp có đuôi .aconfig, ví dụ: my_new_aconfig_flag_declarations.aconfig. Tệp aconfig là tệp proto văn bản tuân theo giản đồ tiêu chuẩn.

  2. Thêm một phần khai báo cờ tương tự như sau:

    package: "com.example.android.aconfig.demo.flags"
container: "system"

flag {
    name: "my_new_flag"
    namespace: "aconfig_demo_namespace"
    description: "This flag controls untested code"
    bug: "<none>"
}

    Trong trường hợp:

    • package khi kết hợp với tên cờ sẽ cung cấp một khoá duy nhất. Trong Java, việc đặt package thành foo.bar sẽ tạo ra một lớp được tạo tự động có tên là foo.bar.Flags. Trong C++, các phương thức truy cập cờ sẽ có tên là foo::bar::"flagname". Các cờ trong cùng một tệp khai báo thuộc cùng một gói, nhưng nhiều tệp khai báo có thể đóng góp cờ cho cùng một gói.

    • container xác định một tập hợp mã được tạo và vận chuyển cùng nhau dưới dạng tệp nhị phân. Các vùng chứa hợp lệ là system, vendor, system_ext, product, name.of.apex, và name.of.apk.

    • name chứa tên của cờ chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.

    • namespace chứa không gian tên cho các đóng góp. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định không gian tên của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng không gian tên theo ý muốn.

    • description chứa nội dung mô tả ngắn gọn về tính năng hoặc thay đổi được gắn cờ.

    • bug là số lỗi liên kết với đóng góp mã mới. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định bug của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng số theo dõi lỗi hoặc sử dụng <none>.

  3. Lưu tệp và thoát khỏi trình chỉnh sửa.

Thiết lập bản dựng

Sau khi khai báo cờ, hãy thiết lập bản dựng để bản dựng có thể tạo mã thư viện dùng để truy cập vào giá trị của cờ.

  1. Trong tệp bản dựng Android.bp, hãy thêm một phần aconfig_declarations tương tự như sau:

    aconfig_declarations {
  name: "aconfig_demo_flags",
  package: "com.example.android.aconfig.demo.flags",
  srcs: [
    "my_new_aconfig_flag_declarations.aconfig"
  ],
}

    Trong trường hợp:

    • name chứa tên của phần khai báo chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.
    • package chứa cùng tên gói được dùng trong phần khai báo.
    • srcs chứa tên của tệp aconfig nơi cờ được khai báo.

  2. Trong cùng một tệp, hãy tạo mục tiêu cc_aconfig_library tương tự như sau:

    cc_aconfig_library {
    name: "aconfig_demo_flags_c_lib",
    aconfig_declarations: "aconfig_demo_flags",
}

    Trong trường hợp:

    • name chứa tên của thư viện chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.
    • aconfig_declarations chứa cùng name được dùng trong phần khai báo.

    Mục tiêu bản dựng cc_aconfig_library gọi C hoặc C++ Codegen, tạo một thư viện có mã được tạo tại thời gian xây dựng.

    Thư viện aconfig CC tương tự như mục tiêu thư viện CC, nhưng có các tuỳ chọn như vendor_available, product_available, host_supported và vndk. Nếu mục tiêu bản dựng phụ thuộc vào cc_aconfig_library này yêu cầu một số loại biến thể, bạn cũng có thể cần thêm chế độ cài đặt tương ứng trong mục tiêu thư viện aconfig CC. Ví dụ: nếu mục tiêu bản dựng mẹ đặt vendor_available thành true, bạn cũng có thể muốn đặt vendor_available thành true trong mục tiêu cc_aconfig_library này.

    Sau khi thêm mục tiêu bản dựng này, mã của bạn có thể truy cập vào thư viện này. Bạn có thể thêm thư viện này bằng cú pháp static_lib hoặc shared_lib. Lưu ý: nếu bạn muốn thêm thư viện này dưới dạng static_lib, hãy thêm phần phụ thuộc shared_lib vào server_configurable_flags. Bước 3 cho biết cách thêm thư viện cờ được tạo mã vào libexample_cpp_lib.

  3. Tạo một mục tiêu sử dụng các cờ aconfig, chẳng hạn như ví dụ cc_library sau:

    cc_library {
    name: "libexample_cpp_lib",
    srcs: ["src/example_cpp_lib.cc"],
    double_loadable: true,
    cflags: [
        "-Wall",
        "-Werror",
        "-Wno-unused-function",
        "-Wno-unused-parameter",
    ],
    header_libs: [
        "jni_headers",
    ],
    shared_libs: [
        "server_configurable_flags",
    ],
    static_libs: [
        "aconfig_demo_flags_c_lib",
    ],
    export_include_dirs: ["src/include"],
}

    Trong trường hợp:

    • shared_libs bao gồm các phần phụ thuộc bổ sung cần thiết cho cờ aconfig.
    • static_libs là tên của thư viện được tạo bởi bản dựng theo trường cc_aconfig_library name ở bước 2. Bằng cách tạo một mục cc_library có tên thư viện tĩnh, giờ đây bạn có thể sử dụng các cờ aconfig trong mã của mình.

Khai báo cờ aconfig cho Rust

Cách khai báo cờ aconfig cho Rust:

  1. Trong một thư mục có mã mới, hãy tạo một tệp có đuôi .aconfig, ví dụ: my_new_aconfig_flag_declarations.aconfig. Tệp aconfig là tệp proto văn bản tuân theo giản đồ tiêu chuẩn.

  2. Thêm một phần khai báo cờ tương tự như sau:

    package: "com.example.android.aconfig.demo.flags"
container: "system"

flag {
    name: "my_new_flag"
    namespace: "aconfig_demo_namespace"
    description: "This flag controls untested code"
    bug: "<none>"
}

    Trong trường hợp:

    • package khi kết hợp với tên cờ sẽ cung cấp một khoá duy nhất. Trong Java, việc đặt package thành foo.bar sẽ tạo ra một lớp được tạo tự động có tên là foo.bar.Flags. Trong C++, các phương thức truy cập cờ sẽ có tên là foo::bar::"flagname". Các cờ trong cùng một tệp khai báo thuộc cùng một gói, nhưng nhiều tệp khai báo có thể đóng góp cờ cho cùng một gói.

    • container xác định một tập hợp mã được tạo và vận chuyển cùng nhau dưới dạng tệp nhị phân. Các vùng chứa hợp lệ là system, vendor, system_ext, product, name.of.apex, và name.of.apk.

    • name chứa tên của cờ chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.

    • namespace chứa không gian tên cho các đóng góp. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định không gian tên của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng không gian tên theo ý muốn.

    • description chứa nội dung mô tả ngắn gọn về tính năng hoặc thay đổi được gắn cờ.

    • bug là số lỗi liên kết với đóng góp mã mới. Bạn phải làm việc với người xem xét được chỉ định của Google để xác định bug của mình. Nếu đang sử dụng cờ khởi chạy tính năng để duy trì tính ổn định của bản sao AOSP của riêng mình, bạn có thể sử dụng số theo dõi lỗi hoặc sử dụng <none>.

  3. Lưu tệp và thoát khỏi trình chỉnh sửa.

Thiết lập bản dựng

Sau khi khai báo cờ, hãy thiết lập bản dựng để bản dựng có thể tạo mã thư viện dùng để truy cập vào giá trị của cờ.

  1. Trong tệp bản dựng Android.bp, hãy thêm một phần aconfig_declarations tương tự như sau:

    aconfig_declarations {
  name: "aconfig_demo_flags",
  package: "com.example.android.aconfig.demo.flags",
  srcs: [
    "my_new_aconfig_flag_declarations.aconfig"
  ],
}

    Trong trường hợp:

    • name chứa tên của phần khai báo chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.
    • package chứa cùng tên gói được dùng trong phần khai báo.
    • srcs chứa tên của tệp aconfig nơi cờ được khai báo.

  2. Tạo mục tiêu rust_aconfig_library tương tự như ví dụ tiếp theo. Mục tiêu này gọi Rust Codegen và tạo một thư viện Rust có mã được tạo trong thời gian xây dựng.

    rust_aconfig_library {
  name: "libaconfig_demo_flags_rust",
  crate_name: "aconfig_demo_flags_rust",
  aconfig_declarations: "aconfig_demo_flags",
}

    Trong trường hợp:

    • name chứa tên của phần khai báo chỉ chứa các chữ cái viết thường, dấu gạch dưới và số.
    • crate_name chứa cùng tên gói được dùng trong phần khai báo.
    • aconfig_declarations chứa cùng name được dùng trong phần khai báo.

    Với thay đổi này, mã của bạn có thể phụ thuộc vào thư viện Rust này.

  3. Trong cùng một tệp, hãy tạo một mục rust_library tương tự như sau:

    rust_library {
  name: "libexample_lib",
  rustlibs: [
      "libaconfig_demo_flags_rust",
  ]
}

    Mẫu này cho phép các mục tiêu bản dựng mã nguồn libexample_demo_flags_rust bao gồm thư viện cờ được tạo mã.

  4. Lưu tệp và thoát khỏi trình chỉnh sửa.