aconfig_proto: add doc in aconfig.proto file
This change adds docs in aconfig.proto file and adds more detail in the
error message for bad package, name and namespace.
Bug: 318759389
Test: atest aconfig.test
Change-Id: I0d45495cd864506b2fcc06ad47e3ffbd6caca9fb
diff --git a/tools/aconfig/aconfig_protos/protos/aconfig.proto b/tools/aconfig/aconfig_protos/protos/aconfig.proto
index ed4b24c..8833722 100644
--- a/tools/aconfig/aconfig_protos/protos/aconfig.proto
+++ b/tools/aconfig/aconfig_protos/protos/aconfig.proto
@@ -20,6 +20,19 @@
package android.aconfig;
+// This protobuf file defines messages used to represent and manage flags in the "aconfig" system
+// The following format requirements apply across various message fields:
+// # name: a lowercase string in snake_case format, no consecutive underscores, and no leading digit
+// For example adjust_rate is a valid name, while AdjustRate, adjust__rate, and
+// 2adjust_rate are invalid
+//
+// # namespace: a lowercase string in snake_case format, no consecutive underscores, and no leading
+// digit. For example android_bar_system
+//
+// # package: lowercase strings in snake_case format, delimited by dots, no consecutive underscores
+// and no leading digit in each string. For example com.android.mypackage is a valid name
+// while com.android.myPackage, com.android.1mypackage are invalid
+
// messages used in both aconfig input and output
enum flag_state {
@@ -35,12 +48,30 @@
// aconfig input messages: flag declarations and values
message flag_declaration {
+ // Name of the flag (required)
+ // See # name for format detail
optional string name = 1;
+
+ // Namespace the flag belongs to (required)
+ // See # namespace for format detail
optional string namespace = 2;
+
+ // Textual description of the flag's purpose (required)
optional string description = 3;
+
+ // Single bug id related to the flag (required)
repeated string bug = 4;
+
+ // Indicates if the flag is permanently read-only and cannot be changed
+ // via release configs (optional)
+ // Default value false
optional bool is_fixed_read_only = 5;
+
+ // Indicates if the flag is exported and accessible beyond its originating container (optional)
+ // Default value false
optional bool is_exported = 6;
+
+ // Additional information about the flag, including its purpose and form factors (optional)
optional flag_metadata metadata = 7;
};
@@ -59,14 +90,26 @@
}
message flag_declarations {
+ // Package to which the flag belongs (required)
+ // See # package for format detail
optional string package = 1;
+
+ // List of flag_declaration objects (required)
repeated flag_declaration flag = 2;
+
+ // Container the flag belongs to (optional)
optional string container = 3;
};
message flag_value {
+ // Package to which the flag belongs (required)
+ // See # package for format detail
optional string package = 1;
+
+ // Name of the flag (required)
+ // See # name for format detail
optional string name = 2;
+
optional flag_state state = 3;
optional flag_permission permission = 4;
};
@@ -85,17 +128,41 @@
}
message parsed_flag {
+ // Package to which the flag belongs (required)
+ // See # package for format detail
optional string package = 1;
+
+ // Name of the flag (required)
+ // See # name for format detail
optional string name = 2;
+
+ // Namespace the flag belongs to (required)
+ // See # namespace for format detail
optional string namespace = 3;
+
+ // Textual description of the flag's purpose (required)
optional string description = 4;
+
+ // Single bug id related to the flag (required)
repeated string bug = 5;
+
optional flag_state state = 6;
optional flag_permission permission = 7;
repeated tracepoint trace = 8;
+
+ // Indicates if the flag is permanently read-only and cannot be changed
+ // via release configs (optional)
+ // Default value false
optional bool is_fixed_read_only = 9;
+
+ // Indicates if the flag is exported and accessible beyond its originating container (optional)
+ // Default value false
optional bool is_exported = 10;
+
+ // Container the flag belongs to (optional)
optional string container = 11;
+
+ // Additional information about the flag, including its purpose and form factors (optional)
optional flag_metadata metadata = 12;
}
diff --git a/tools/aconfig/aconfig_protos/src/lib.rs b/tools/aconfig/aconfig_protos/src/lib.rs
index 8f5667f..81bbd7e 100644
--- a/tools/aconfig/aconfig_protos/src/lib.rs
+++ b/tools/aconfig/aconfig_protos/src/lib.rs
@@ -69,6 +69,9 @@
use anyhow::Result;
use paste::paste;
+/// Path to proto file
+const ACONFIG_PROTO_PATH: &str = "//build/make/tools/aconfig/aconfig_protos/protos/aconfig.proto";
+
/// Check if the name identifier is valid
pub fn is_valid_name_ident(s: &str) -> bool {
// Identifiers must match [a-z][a-z0-9_]*, except consecutive underscores are not allowed
@@ -124,8 +127,18 @@
pub fn verify_fields(pdf: &ProtoFlagDeclaration) -> Result<()> {
ensure_required_fields!("flag declaration", pdf, "name", "namespace", "description");
- ensure!(is_valid_name_ident(pdf.name()), "bad flag declaration: bad name");
- ensure!(is_valid_name_ident(pdf.namespace()), "bad flag declaration: bad name");
+ ensure!(
+ is_valid_name_ident(pdf.name()),
+ "bad flag declaration: bad name {} expected snake_case string; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pdf.name()
+ );
+ ensure!(
+ is_valid_name_ident(pdf.namespace()),
+ "bad flag declaration: bad namespace {} expected snake_case string; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pdf.namespace()
+ );
ensure!(!pdf.description().is_empty(), "bad flag declaration: empty description");
ensure!(pdf.bug.len() == 1, "bad flag declaration: exactly one bug required");
@@ -149,8 +162,12 @@
pub fn verify_fields(pdf: &ProtoFlagDeclarations) -> Result<()> {
ensure_required_fields!("flag declarations", pdf, "package");
// TODO(b/312769710): Make the container field required.
-
- ensure!(is_valid_package_ident(pdf.package()), "bad flag declarations: bad package");
+ ensure!(
+ is_valid_package_ident(pdf.package()),
+ "bad flag declarations: bad package {} expected snake_case strings delimited by dots; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pdf.package()
+ );
ensure!(
!pdf.has_container() || is_valid_container_ident(pdf.container()),
"bad flag declarations: bad container"
@@ -172,8 +189,18 @@
pub fn verify_fields(fv: &ProtoFlagValue) -> Result<()> {
ensure_required_fields!("flag value", fv, "package", "name", "state", "permission");
- ensure!(is_valid_package_ident(fv.package()), "bad flag value: bad package");
- ensure!(is_valid_name_ident(fv.name()), "bad flag value: bad name");
+ ensure!(
+ is_valid_package_ident(fv.package()),
+ "bad flag value: bad package {} expected snake_case strings delimited by dots; \
+ see {ACONFIG_PROTO_PATH} for details",
+ fv.package()
+ );
+ ensure!(
+ is_valid_name_ident(fv.name()),
+ "bad flag value: bad name {} expected snake_case string; \
+ see {ACONFIG_PROTO_PATH} for details",
+ fv.name()
+ );
Ok(())
}
@@ -255,13 +282,28 @@
"permission"
);
- ensure!(is_valid_package_ident(pf.package()), "bad parsed flag: bad package");
+ ensure!(
+ is_valid_package_ident(pf.package()),
+ "bad parsed flag: bad package {} expected snake_case strings delimited by dots; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pf.package()
+ );
ensure!(
!pf.has_container() || is_valid_container_ident(pf.container()),
"bad parsed flag: bad container"
);
- ensure!(is_valid_name_ident(pf.name()), "bad parsed flag: bad name");
- ensure!(is_valid_name_ident(pf.namespace()), "bad parsed flag: bad namespace");
+ ensure!(
+ is_valid_name_ident(pf.name()),
+ "bad parsed flag: bad name {} expected snake_case string; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pf.name()
+ );
+ ensure!(
+ is_valid_name_ident(pf.namespace()),
+ "bad parsed flag: bad namespace {} expected snake_case string; \
+ see {ACONFIG_PROTO_PATH} for details",
+ pf.namespace()
+ );
ensure!(!pf.description().is_empty(), "bad parsed flag: empty description");
ensure!(!pf.trace.is_empty(), "bad parsed flag: empty trace");
for tp in pf.trace.iter() {