Khai báo cờ aconfig

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Bạn có thể sử dụng cờ aconfig trong mã Java, C, C++ và mã Rust. Hệ thống xây dựng AOSP sẽ 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ể sử 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ờ cấu hình cho Java:

1. Trong thư mục chứa 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 đồ chuẩn.

2. Thêm nội dung 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, đặt package thành foo.bar sẽ dẫn đến một lớp được tạo tự động có tên foo.bar.Flags. Trong C++, các phương thức trình truy cập cờ sẽ được đặt tên là foo::bar::"flagname". Cờ trong cùng một nội dung khai báo tệp 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 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 khoản đóng góp. Bạn phải hợp tác với nhân viên đánh giá của Google được chỉ định để xác định vùng chứa tên của bạn. Nếu đang sử dụng cờ phát hành tính năng để duy trì sự ổ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 về tính năng hoặc thay đổi được gắn cờ.

   • bug là mã số lỗi liên quan đến việc đóng góp mã mới. Bạn phải hãy làm việc với người đánh giá được chỉ định của Google để xác định bug của bạn. Nếu bạn 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 bạn, bạn có thể dùng số theo dõi lỗi hoặc <none>.

3. Lưu tệp rồi thoát khỏi 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 để có thể tạo mã thư viện dùng để truy cập 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 nội dung khai báo chỉ chứa chữ cái viết thường, dấu gạch dưới và số.
   • package chứa cùng một 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 thư mục chứa 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 đồ chuẩn.

2. Thêm nội dung 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, đặt package thành foo.bar sẽ dẫn đến một lớp được tạo tự động có tên foo.bar.Flags. Trong C++, các phương thức trình truy cập cờ sẽ được đặt tên là foo::bar::"flagname". Cờ trong cùng một nội dung khai báo tệp 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 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 khoản đóng góp. Bạn phải hợp tác với nhân viên đánh giá của Google được chỉ định để xác định vùng chứa tên của bạn. Nếu đang sử dụng cờ phát hành tính năng để duy trì sự ổ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 về tính năng hoặc thay đổi được gắn cờ.

   • bug là mã số lỗi liên quan đến việc đóng góp mã mới. Bạn phải hãy làm việc với người đánh giá được chỉ định của Google để xác định bug của bạn. Nếu bạn 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 bạn, bạn có thể dùng số theo dõi lỗi hoặc <none>.

3. Lưu tệp rồi thoát khỏi 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 để có thể tạo mã thư viện dùng để truy cập 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 nội dung khai báo chỉ chứa chữ cái viết thường, dấu gạch dưới và số.
   • package chứa chính tên gói đã dùng trong phần khai báo.
   • srcs chứa tên của tệp aconfig nơi khai báo cờ.

2. Trong cùng tệp, hãy tạo một 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 chữ cái viết thường, dấu gạch dưới và số.
   • aconfig_declarations chứa cùng name 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 bằng mã được tạo tại thời điểm tạo bản dựng.

   Thư viện CC aconfig 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ẹ đặt vendor_available thành true, bạn cũng nê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ể đưa thư viện này vào 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 làm static_lib, hãy thêm phần phụ thuộc shared_lib trên server_configurable_flags. Bước 3 hướng dẫn 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ờ aconfig, chẳng hạn như ví dụ sau về 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 ra theo trường cc_aconfig_library name ở bước 2. Bằng cách tạo mục nhập cc_library với tên thư viện tĩnh, giờ đây, bạn có thể sử dụng cờ aconfig trong mã của mình.

Khai báo cờ aconfig cho Rust

Cách khai báo cờ cấu hình cho Rust:

1. Trong thư mục chứa 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 đồ chuẩn.

2. Thêm nội dung 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, đặt package thành foo.bar sẽ dẫn đến một lớp được tạo tự động có tên foo.bar.Flags. Trong C++, các phương thức trình truy cập cờ sẽ được đặt tên là foo::bar::"flagname". Cờ trong cùng một nội dung khai báo tệp 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 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 khoản đóng góp. Bạn phải hợp tác với nhân viên đánh giá của Google được chỉ định để xác định vùng chứa tên của bạn. Nếu đang sử dụng cờ phát hành tính năng để duy trì sự ổ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 về tính năng hoặc thay đổi được gắn cờ.

   • bug là mã số lỗi liên quan đến việc đóng góp mã mới. Bạn phải hãy làm việc với người đánh giá được chỉ định của Google để xác định bug của bạn. Nếu bạn 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 bạn, bạn có thể dùng số theo dõi lỗi hoặc <none>.

3. Lưu tệp rồi thoát khỏi 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 để có thể tạo mã thư viện dùng để truy cập 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 nội dung khai báo chỉ chứa chữ cái viết thường, dấu gạch dưới và số.
   • package chứa chính tên gói đã dùng trong phần khai báo.
   • srcs chứa tên của tệp aconfig nơi khai báo cờ.

2. Tạo một mục tiêu rust_aconfig_library tương tự như ví dụ tiếp theo. Chiến dịch này mục tiêu gọi Rust Codegen và tạo thư viện Rust bằng mã đã 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 chữ thường, dấu gạch dưới và số.
   • crate_name chứa cùng một tên gói được dùng trong phần khai báo.
   • aconfig_declarations chứa cùng name 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. Cũng trong tệp đó, hãy tạo một mục nhập 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 của bạn libexample_demo_flags_rust để bao gồm thư viện cờ được tạo mã.

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