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 flag 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 flag configurations, such as the trunk_staging
configuration where all flags are READ_WRITE
and set to ENABLED
for testing.
Flag 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 flag configuration for the target.
For example, the
following is a trunk_staging
target:
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
Trunk staging is a development configuration because it's
used by Google 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 configuration. A release
configuration uses READ_ONLY
flags and reflects all of the code
enabled for that release.
Add a flag to the trunk_staging release config
To test a new flag, add it to the trunk_staging
release config as
follows:
- Navigate to
WORKING_DIRECTORY/build/release/aconfig/trunk_staging/
- 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. - Navigate to the new directory.
- In the directory, create a flag values file that combines the name used in
the flag declaration (
.aconfig
) file, such asmy_static_flag
shown in Declare an aconfig flag for Java with_flag_values.textproto
. The resulting filename ismy_static_flag_flag_values.textproto
. 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 eitherENABLED
orDISABLED
.permission
is eitherREAD_WRITE
orREAD_ONLY
. Generally, thepermission
is set toREAD_ONLY
for flag values files that are part of a release configuration.
Save the file and exit your editor.
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.In the
Android.bp
file, create aaconfig_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 ofaconfig-values-platform_PATH_TO_RELEASE_CONFIG_DIR-CONFIG-NAME-package.name-all
. Note thatPATH_TO_RELEASE_CONFIG_DIR
isbuild/release
.package
contains the same package name used in the declaration.srcs
is a list of all of your flag values files.
Save the file and exit your editor.
Navigate to the directory above the current directory (
cd ..
)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.Build Android, and run your new code to ensure that it's enabled per the setting in the flag values file.