Set feature launch flag values

By default, all feature launch flags are READ_WRITE and set to DISABLED. Before you can test a feature, you must override the default value used in the build by creating a flag values file for the flag. In a flag values file, you set a individual flag's state (ENABLED or DISABLED) and permission (READ_WRITE or READ_ONLY).

A release configuration is a directory that contains all of the flag values files for a specific build of Android (with certain features enabled and disabled).

AOSP ships with a few release configurations, such as trunk_staging. Release configuration directories are found under WORKING_DIRECTORY/build/release/aconfig/.

When you use the lunch command to choose a target, you're also setting the release configuration for the target. For example, the following is a trunk_staging target:

lunch aosp_cf_x86_64_only_phone-trunk_staging-userdebug

Trunk staging is a development release configuration because Google uses it to test features before general release. This configuration uses mostly READ_WRITE flags that let you test your code with features enabled or disabled at runtime.

At general release, use a release release configuration. A release release configuration mostly uses READ_ONLY flags and reflects all of the code enabled for that release.

Add a flag to the trunk_staging release configuration

To test a new flag, add it to the trunk_staging release configuration as follows:

1. Navigate to WORKING_DIRECTORY/build/release/aconfig/trunk_staging/
2. Create a directory with the same package name as your flag, such as com.example.android.aconfig.demo.flags shown in Declare an aconfig flag for Java.
3. Navigate to the new directory.
4. In the directory, create a flag values file that combines the name used in the flag declaration (.aconfig) file, such as my_static_flag shown in Declare an aconfig flag for Java with _flag_values.textproto. The resulting filename is my_static_flag_flag_values.textproto.

5. Edit the file and add a flag_value similar to the following:

   flag_value {
     package: "com.example.android.aconfig.demo.flags"
     name: "my_static_flag"
     state: DISABLED
     Permission: READ_WRITE
   }
   

   Where:

   • package contains the same package name used in the declaration.
   • name contains the same name used in the declaration.
   • state is either ENABLED or DISABLED.
   • permission is either READ_WRITE or READ_ONLY. Generally, the permission is set to READ_ONLY for flag values files that are part of a release configuration.

6. Save the file and exit your editor.

7. In the same directory as the flag values file, create a build file called Android.bp. This file is used to include the flag values file in the build.

8. In the Android.bp file, create a aconfig_values section similar to:

   aconfig_values {
     name: "aconfig-values-platform_build_release-trunk-staging-com.android.aconfig.test-all",
     package: "com.android.aconfig.test",
     srcs: [
       "*_flag_values.textproto",
     ]
   }
   

   Where:

   • name is the unique name for the Soong build module. Google uses the convention of aconfig-values-platform_PATH_TO_RELEASE_CONFIG_DIR-CONFIG-NAME-package.name-all. Note that PATH_TO_RELEASE_CONFIG_DIR is build/release.
   • package contains the same package name used in the declaration.
   • srcs is a list of all of your flag values files.

9. Save the file and exit your editor.

10. Navigate to the directory above the current directory (cd ..)

11. Edit the Android.bp file. This build file contains a list of the names (name) associated with each flag values file. Add the name you used in the previous build file (step 8) to this list.

12. Build Android, and run your new code to ensure that it's enabled per the setting in the flag values file.