xref: /aosp_15_r20/frameworks/base/tools/aapt2/Resources.proto (revision d57664e9bc4670b3ecf6748a746a57c557b6bc9e)
1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17syntax = "proto3";
18
19import "frameworks/base/tools/aapt2/Configuration.proto";
20
21package aapt.pb;
22
23option java_package = "com.android.aapt";
24
25// A string pool that wraps the binary form of the C++ class android::ResStringPool.
26message StringPool {
27  bytes data = 1;
28}
29
30// The position of a declared entity within a file.
31message SourcePosition {
32  uint32 line_number = 1;
33  uint32 column_number = 2;
34}
35
36// Developer friendly source file information for an entity in the resource table.
37message Source {
38  // The index of the string path within the source string pool of a ResourceTable.
39  uint32 path_idx = 1;
40  SourcePosition position = 2;
41}
42
43// The name and version fingerprint of a build tool.
44message ToolFingerprint {
45  string tool = 1;
46  string version = 2;
47}
48
49// References to non local resources
50message DynamicRefTable {
51  PackageId package_id = 1;
52  string package_name = 2;
53}
54
55
56// Top level message representing a resource table.
57message ResourceTable {
58  // The string pool containing source paths referenced throughout the resource table. This does
59  // not end up in the final binary ARSC file.
60  StringPool source_pool = 1;
61
62  // Resource definitions corresponding to an Android package.
63  repeated Package package = 2;
64
65  // The <overlayable> declarations within the resource table.
66  repeated Overlayable overlayable = 3;
67
68  // The version fingerprints of the tools that built the resource table.
69  repeated ToolFingerprint tool_fingerprint = 4;
70
71  repeated DynamicRefTable dynamic_ref_table = 5;
72}
73
74// A package ID in the range [0x00, 0xff].
75message PackageId {
76  uint32 id = 1;
77}
78
79// Defines resources for an Android package.
80message Package {
81  // The package ID of this package, in the range [0x00, 0xff].
82  // - ID 0x00 is reserved for shared libraries, or when the ID is assigned at run-time.
83  // - ID 0x01 is reserved for the 'android' package (framework).
84  // - ID range [0x02, 0x7f) is reserved for auto-assignment to shared libraries at run-time.
85  // - ID 0x7f is reserved for the application package.
86  // - IDs > 0x7f are reserved for the application as well and are treated as feature splits.
87  // This may not be set if no ID was assigned.
88  PackageId package_id = 1;
89
90  // The Java compatible Android package name of the app.
91  string package_name = 2;
92
93  // The series of types defined by the package.
94  repeated Type type = 3;
95}
96
97// A type ID in the range [0x01, 0xff].
98message TypeId {
99  uint32 id = 1;
100}
101
102// A set of resources grouped under a common type. Such types include string, layout, xml, dimen,
103// attr, etc. This maps to the second part of a resource identifier in Java (R.type.entry).
104message Type {
105  // The ID of the type. This may not be set if no ID was assigned.
106  TypeId type_id = 1;
107
108  // The name of the type. This corresponds to the 'type' part of a full resource name of the form
109  // package:type/entry. The set of legal type names is listed in Resource.cpp.
110  string name = 2;
111
112  // The entries defined for this type.
113  repeated Entry entry = 3;
114}
115
116// The Visibility of a symbol/entry (public, private, undefined).
117message Visibility {
118  // The visibility of the resource outside of its package.
119  enum Level {
120    // No visibility was explicitly specified. This is typically treated as private.
121    // The distinction is important when two separate R.java files are generated: a public and
122    // private one. An unknown visibility, in this case, would cause the resource to be omitted
123    // from either R.java.
124    UNKNOWN = 0;
125
126    // A resource was explicitly marked as private. This means the resource can not be accessed
127    // outside of its package unless the @*package:type/entry notation is used (the asterisk being
128    // the private accessor). If two R.java files are generated (private + public), the resource
129    // will only be emitted to the private R.java file.
130    PRIVATE = 1;
131
132    // A resource was explicitly marked as public. This means the resource can be accessed
133    // from any package, and is emitted into all R.java files, public and private.
134    PUBLIC = 2;
135  }
136
137  Level level = 1;
138
139  // The path at which this entry's visibility was defined (eg. public.xml).
140  Source source = 2;
141
142  // The comment associated with the <public> tag.
143  string comment = 3;
144
145  // Indicates that the resource id may change across builds and that the public R.java identifier
146  // for this resource should not be final. This is set to `true` for resources in `staging-group`
147  // tags.
148  bool staged_api = 4;
149}
150
151// Whether a resource comes from a compile-time overlay and is explicitly allowed to not overlay an
152// existing resource.
153message AllowNew {
154  // Where this was defined in source.
155  Source source = 1;
156
157  // Any comment associated with the declaration.
158  string comment = 2;
159}
160
161// Represents a set of overlayable resources.
162message Overlayable {
163  // The name of the <overlayable>.
164  string name = 1;
165
166  // The location of the <overlayable> declaration in the source.
167  Source source = 2;
168
169  // The component responsible for enabling and disabling overlays targeting this <overlayable>.
170  string actor = 3;
171}
172
173// Represents an overlayable <item> declaration within an <overlayable> tag.
174message OverlayableItem {
175  enum Policy {
176    NONE = 0;
177    PUBLIC = 1;
178    SYSTEM = 2;
179    VENDOR = 3;
180    PRODUCT = 4;
181    SIGNATURE = 5;
182    ODM = 6;
183    OEM = 7;
184    ACTOR = 8;
185    CONFIG_SIGNATURE = 9;
186  }
187
188  // The location of the <item> declaration in source.
189  Source source = 1;
190
191  // Any comment associated with the declaration.
192  string comment = 2;
193
194  // The policy defined by the enclosing <policy> tag of this <item>.
195  repeated Policy policy = 3;
196
197  // The index into overlayable list that points to the <overlayable> tag that contains
198  // this <item>.
199  uint32 overlayable_idx = 4;
200}
201
202// The staged resource ID definition of a finalized resource.
203message StagedId {
204  Source source = 1;
205  uint32 staged_id = 2;
206}
207
208// An entry ID in the range [0x0000, 0xffff].
209message EntryId {
210  uint32 id = 1;
211}
212
213// An entry declaration. An entry has a full resource ID that is the combination of package ID,
214// type ID, and its own entry ID. An entry on its own has no value, but values are defined for
215// various configurations/variants.
216message Entry {
217  // The ID of this entry. Together with the package ID and type ID, this forms a full resource ID
218  // of the form 0xPPTTEEEE, where PP is the package ID, TT is the type ID, and EEEE is the entry
219  // ID.
220  // This may not be set if no ID was assigned.
221  EntryId entry_id = 1;
222
223  // The name of this entry. This corresponds to the 'entry' part of a full resource name of the
224  // form package:type/entry.
225  string name = 2;
226
227  // The visibility of this entry (public, private, undefined).
228  Visibility visibility = 3;
229
230  // Whether this resource, when originating from a compile-time overlay, is allowed to NOT overlay
231  // any existing resources.
232  AllowNew allow_new = 4;
233
234  // Whether this resource can be overlaid by a runtime resource overlay (RRO).
235  OverlayableItem overlayable_item = 5;
236
237  // The set of values defined for this entry, each corresponding to a different
238  // configuration/variant.
239  repeated ConfigValue config_value = 6;
240
241  // The staged resource ID of this finalized resource.
242  StagedId staged_id = 7;
243
244  // The set of values defined for this entry which are behind disabled flags
245  repeated ConfigValue flag_disabled_config_value = 8;
246}
247
248// A Configuration/Value pair.
249message ConfigValue {
250  Configuration config = 1;
251  Value value = 2;
252  reserved 3;
253}
254
255// The generic meta-data for every value in a resource table.
256message Value {
257  // Where the value was defined.
258  Source source = 1;
259
260  // Any comment associated with the value.
261  string comment = 2;
262
263  // Whether the value can be overridden.
264  bool weak = 3;
265
266  // The value is either an Item or a CompoundValue.
267  oneof value {
268    Item item = 4;
269    CompoundValue compound_value = 5;
270  }
271}
272
273// An Item is an abstract type. It represents a value that can appear inline in many places, such
274// as XML attribute values or on the right hand side of style attribute definitions. The concrete
275// type is one of the types below. Only one can be set.
276message Item {
277  oneof value {
278    Reference ref = 1;
279    String str = 2;
280    RawString raw_str = 3;
281    StyledString styled_str = 4;
282    FileReference file = 5;
283    Id id = 6;
284    Primitive prim = 7;
285  }
286
287  // The status of the flag the value is behind if any
288  uint32 flag_status = 8;
289  bool flag_negated = 9;
290  string flag_name = 10;
291}
292
293// A CompoundValue is an abstract type. It represents a value that is a made of other values.
294// These can only usually appear as top-level resources. The concrete type is one of the types
295// below. Only one can be set.
296message CompoundValue {
297  oneof value {
298    Attribute attr = 1;
299    Style style = 2;
300    Styleable styleable = 3;
301    Array array = 4;
302    Plural plural = 5;
303    MacroBody macro = 6;
304  }
305
306  // The status of the flag the value is behind if any
307  uint32 flag_status = 7;
308  bool flag_negated = 8;
309  string flag_name = 9;
310}
311
312// Message holding a boolean, so it can be optionally encoded.
313message Boolean {
314  bool value = 1;
315}
316
317// A value that is a reference to another resource. This reference can be by name or resource ID.
318message Reference {
319  enum Type {
320    // A plain reference (@package:type/entry).
321    REFERENCE = 0;
322
323    // A reference to a theme attribute (?package:type/entry).
324    ATTRIBUTE = 1;
325  }
326
327  Type type = 1;
328
329  // The resource ID (0xPPTTEEEE) of the resource being referred. This is optional.
330  uint32 id = 2;
331
332  // The name of the resource being referred. This is optional if the resource ID is set.
333  string name = 3;
334
335  // Whether this reference is referencing a private resource (@*package:type/entry).
336  bool private = 4;
337
338  // Whether this reference is dynamic.
339  Boolean is_dynamic = 5;
340
341  // The type flags used when compiling the reference. Used for substituting the contents of macros.
342  uint32 type_flags = 6;
343
344  // Whether raw string values would have been accepted in place of this reference definition. Used
345  // for substituting the contents of macros.
346  bool allow_raw = 7;
347}
348
349// A value that represents an ID. This is just a placeholder, as ID values are used to occupy a
350// resource ID (0xPPTTEEEE) as a unique identifier. Their value is unimportant.
351message Id {
352}
353
354// A value that is a string.
355message String {
356  string value = 1;
357}
358
359// A value that is a raw string, which is unescaped/uninterpreted. This is typically used to
360// represent the value of a style attribute before the attribute is compiled and the set of
361// allowed values is known.
362message RawString {
363  string value = 1;
364}
365
366// A string with styling information, like html tags that specify boldness, italics, etc.
367message StyledString {
368  // The raw text of the string.
369  string value = 1;
370
371  // A Span marks a region of the string text that is styled.
372  message Span {
373    // The name of the tag, and its attributes, encoded as follows:
374    // tag_name;attr1=value1;attr2=value2;[...]
375    string tag = 1;
376
377    // The first character position this span applies to, in UTF-16 offset.
378    uint32 first_char = 2;
379
380    // The last character position this span applies to, in UTF-16 offset.
381    uint32 last_char = 3;
382  }
383
384  repeated Span span = 2;
385}
386
387// A value that is a reference to an external entity, like an XML file or a PNG.
388message FileReference {
389  enum Type {
390    UNKNOWN = 0;
391    PNG = 1;
392    BINARY_XML = 2;
393    PROTO_XML = 3;
394  }
395
396  // Path to a file within the APK (typically res/type-config/entry.ext).
397  string path = 1;
398
399  // The type of file this path points to. For UAM bundle, this cannot be
400  // BINARY_XML.
401  Type type = 2;
402}
403
404// A value that represents a primitive data type (float, int, boolean, etc.).
405// Refer to Res_value in ResourceTypes.h for info on types and formatting
406message Primitive {
407  message NullType {
408  }
409  message EmptyType {
410  }
411  oneof oneof_value {
412    NullType null_value = 1;
413    EmptyType empty_value = 2;
414    float float_value = 3;
415    uint32 dimension_value = 13;
416    uint32 fraction_value = 14;
417    int32 int_decimal_value = 6;
418    uint32 int_hexadecimal_value = 7;
419    bool boolean_value = 8;
420    uint32 color_argb8_value = 9;
421    uint32 color_rgb8_value = 10;
422    uint32 color_argb4_value = 11;
423    uint32 color_rgb4_value = 12;
424    float dimension_value_deprecated = 4 [deprecated=true];
425    float fraction_value_deprecated = 5 [deprecated=true];
426  }
427}
428
429// A value that represents an XML attribute and what values it accepts.
430message Attribute {
431  // A Symbol used to represent an enum or a flag.
432  message Symbol {
433    // Where the enum/flag item was defined.
434    Source source = 1;
435
436    // Any comments associated with the enum or flag.
437    string comment = 2;
438
439    // The name of the enum/flag as a reference. Enums/flag items are generated as ID resource
440    // values.
441    Reference name = 3;
442
443    // The value of the enum/flag.
444    uint32 value = 4;
445
446    // The data type of the enum/flag as defined in android::Res_value.
447    uint32 type = 5;
448  }
449
450  // Bitmask of formats allowed for an attribute.
451  enum FormatFlags {
452    NONE = 0x0;          // Proto3 requires a default of 0.
453    ANY = 0x0000ffff;    // Allows any type except ENUM and FLAGS.
454    REFERENCE = 0x01;    // Allows Reference values.
455    STRING = 0x02;       // Allows String/StyledString values.
456    INTEGER = 0x04;      // Allows any integer BinaryPrimitive values.
457    BOOLEAN = 0x08;      // Allows any boolean BinaryPrimitive values.
458    COLOR = 0x010;       // Allows any color BinaryPrimitive values.
459    FLOAT = 0x020;       // Allows any float BinaryPrimitive values.
460    DIMENSION = 0x040;   // Allows any dimension BinaryPrimitive values.
461    FRACTION = 0x080;    // Allows any fraction BinaryPrimitive values.
462    ENUM = 0x00010000;   // Allows enums that are defined in the Attribute's symbols.
463                         // ENUM and FLAGS cannot BOTH be set.
464    FLAGS = 0x00020000;  // Allows flags that are defined in the Attribute's symbols.
465                         // ENUM and FLAGS cannot BOTH be set.
466  }
467
468  // A bitmask of types that this XML attribute accepts. Corresponds to the flags in the
469  // enum FormatFlags.
470  uint32 format_flags = 1;
471
472  // The smallest integer allowed for this XML attribute. Only makes sense if the format includes
473  // FormatFlags::INTEGER.
474  int32 min_int = 2;
475
476  // The largest integer allowed for this XML attribute. Only makes sense if the format includes
477  // FormatFlags::INTEGER.
478  int32 max_int = 3;
479
480  // The set of enums/flags defined in this attribute. Only makes sense if the format includes
481  // either FormatFlags::ENUM or FormatFlags::FLAGS. Having both is an error.
482  repeated Symbol symbol = 4;
483}
484
485// A value that represents a style.
486message Style {
487  // An XML attribute/value pair defined in the style.
488  message Entry {
489    // Where the entry was defined.
490    Source source = 1;
491
492    // Any comments associated with the entry.
493    string comment = 2;
494
495    // A reference to the XML attribute.
496    Reference key = 3;
497
498    // The Item defined for this XML attribute.
499    Item item = 4;
500  }
501
502  // The optinal style from which this style inherits attributes.
503  Reference parent = 1;
504
505  // The source file information of the parent inheritance declaration.
506  Source parent_source = 2;
507
508  // The set of XML attribute/value pairs for this style.
509  repeated Entry entry = 3;
510}
511
512// A value that represents a <declare-styleable> XML resource. These are not real resources and
513// only end up as Java fields in the generated R.java. They do not end up in the binary ARSC file.
514message Styleable {
515  // An attribute defined for this styleable.
516  message Entry {
517    // Where the attribute was defined within the <declare-styleable> block.
518    Source source = 1;
519
520    // Any comments associated with the declaration.
521    string comment = 2;
522
523    // The reference to the attribute.
524    Reference attr = 3;
525  }
526
527  // The set of attribute declarations.
528  repeated Entry entry = 1;
529}
530
531// A value that represents an array of resource values.
532message Array {
533  // A single element of the array.
534  message Element {
535    // Where the element was defined.
536    Source source = 1;
537
538    // Any comments associated with the element.
539    string comment = 2;
540
541    // The value assigned to this element.
542    Item item = 3;
543  }
544
545  // The list of array elements.
546  repeated Element element = 1;
547}
548
549// A value that represents a string and its many variations based on plurality.
550message Plural {
551  // The arity of the plural.
552  enum Arity {
553    ZERO = 0;
554    ONE = 1;
555    TWO = 2;
556    FEW = 3;
557    MANY = 4;
558    OTHER = 5;
559  }
560
561  // The plural value for a given arity.
562  message Entry {
563    // Where the plural was defined.
564    Source source = 1;
565
566    // Any comments associated with the plural.
567    string comment = 2;
568
569    // The arity of the plural.
570    Arity arity = 3;
571
572    // The value assigned to this plural.
573    Item item = 4;
574  }
575
576  // The set of arity/plural mappings.
577  repeated Entry entry = 1;
578}
579
580// Defines an abstract XmlNode that must be either an XmlElement, or
581// a text node represented by a string.
582message XmlNode {
583  oneof node {
584    XmlElement element = 1;
585    string text = 2;
586  }
587
588  // Source line and column info.
589  SourcePosition source = 3;
590}
591
592// An <element> in an XML document.
593message XmlElement {
594  // Namespaces defined on this element.
595  repeated XmlNamespace namespace_declaration = 1;
596
597  // The namespace URI of this element.
598  string namespace_uri = 2;
599
600  // The name of this element.
601  string name = 3;
602
603  // The attributes of this element.
604  repeated XmlAttribute attribute = 4;
605
606  // The children of this element.
607  repeated XmlNode child = 5;
608}
609
610// A namespace declaration on an XmlElement (xmlns:android="http://...").
611message XmlNamespace {
612  string prefix = 1;
613  string uri = 2;
614
615  // Source line and column info.
616  SourcePosition source = 3;
617}
618
619// An attribute defined on an XmlElement (android:text="...").
620message XmlAttribute {
621  string namespace_uri = 1;
622  string name = 2;
623  string value = 3;
624
625  // Source line and column info.
626  SourcePosition source = 4;
627
628  // The optional resource ID (0xPPTTEEEE) of the attribute.
629  uint32 resource_id = 5;
630
631  // The optional interpreted/compiled version of the `value` string.
632  Item compiled_item = 6;
633}
634
635message MacroBody {
636  string raw_string = 1;
637  StyleString style_string = 2;
638  repeated UntranslatableSection untranslatable_sections = 3;
639  repeated NamespaceAlias namespace_stack = 4;
640  SourcePosition source = 5;
641}
642
643message NamespaceAlias {
644  string prefix = 1;
645  string package_name = 2;
646  bool is_private = 3;
647}
648
649message StyleString {
650  message Span {
651    string name = 1;
652    uint32 start_index = 2;
653    uint32 end_index = 3;
654  }
655  string str = 1;
656  repeated Span spans = 2;
657}
658
659message UntranslatableSection {
660  uint64 start_index = 1;
661  uint64 end_index = 2;
662}
663