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 bản dựng AOSP khởi chạy một công cụ có tên là aconfig dùng để tạo một thư viện phương thức theo ngôn ngữ cụ thể 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à một tệp proto văn bản tuân theo một giản đồ tiêu chuẩn.

2. Thêm một 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 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 một 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 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 đánh giá được chỉ định của Google để xác định không gian tên của mình. Nếu đang 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ể dùng không gian tên theo ý muốn.

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

   • bug là số lỗi liên quan đến phần đóng góp mã mới. Bạn phải hợp tác với người đánh giá được chỉ định của Google để xác định bug. Nếu đang sử dụng cờ ra mắt 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>.

   Lưu ý: Bạn không thể dùng cờ trong các tệp APK không được tạo bằng APEX hoặc phân vùng hệ thống.

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

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

Sau khi bạn 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 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 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 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à một tệp proto văn bản tuân theo một giản đồ tiêu chuẩn.

2. Thêm một 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 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 một 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 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 đánh giá được chỉ định của Google để xác định không gian tên của mình. Nếu đang 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ể dùng không gian tên theo ý muốn.

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

   • bug là số lỗi liên quan đến phần đóng góp mã mới. Bạn phải hợp tác với người đánh giá được chỉ định của Google để xác định bug. Nếu đang sử dụng cờ ra mắt 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>.

   Lưu ý: Bạn không thể dùng cờ trong các tệp APK không được tạo bằng APEX hoặc phân vùng hệ thống.

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

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

Sau khi bạn 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 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 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ột đích 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 một name được dùng trong khai báo.

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

   Thư viện aconfig CC tương tự như mục tiêu thư viện CC, nhưng có các lựa 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ể nhất định, 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ẹ có vendor_available được đặt 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. Xin lưu ý rằng nếu bạn muốn thêm thư viện này làm 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 đưa 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ụ sau cc_library:

   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 do bản dựng tạo 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à một tệp proto văn bản tuân theo một giản đồ tiêu chuẩn.

2. Thêm một 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 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 một 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 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 đánh giá được chỉ định của Google để xác định không gian tên của mình. Nếu đang 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ể dùng không gian tên theo ý muốn.

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

   • bug là số lỗi liên quan đến phần đóng góp mã mới. Bạn phải hợp tác với người đánh giá được chỉ định của Google để xác định bug. Nếu đang sử dụng cờ ra mắt 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>.

   Lưu ý: Bạn không thể dùng cờ trong các tệp APK không được tạo bằng APEX hoặc phân vùng hệ thống.

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

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

Sau khi bạn 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 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 khai báo.
   • srcs chứa tên của tệp aconfig nơi cờ được khai báo.

2. Tạo một đích 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 bằng 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 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 khai báo.
   • aconfig_declarations chứa cùng một name được dùng trong 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 xây dựng mã nguồn libexample_demo_flags_rust của bạn bao gồm thư viện cờ được tạo mã.

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