Home | History | Annotate | Download | only in docs 
      1 Android Emulator Config File Formats:
      2 ====================================
      3 
      4 Introduction:
      5 -------------
      6 
      7 The Android emulator supports several file formats for its configuration
      8 files, depending on specific usage. This file documents them.
      9 
     10 
     11 I. Android .ini configuration files:
     12 ------------------------------------
     13 
     14 The code in android/utils/ini.[hc] is used to support a simple .ini file
     15 format for some configuration files. Here's the BNF for it:
     16 
     17   file             := <line>*
     18   line             := <comment> | <LF> | <assignment>
     19   comment          := (';'|'#') <noLF>* <LF>
     20   assignment       := <space>* <keyName> <space>* '=' <space>* <valueString> <space>* <LF>
     21   keyName          := <keyNameStartChar> <keyNameChar>*
     22   keyNameStartChar := [A-Za-z_]
     23   keyNameChar      := [A-Za-z0-9_.-]
     24   valueString      := <noLF>*
     25   space            := ' ' | '\t'
     26   LF               := '\r\n' | '\n' | '\r'
     27   noLF             := [^<LF>]
     28 
     29 Or, in plain English:
     30 
     31  - No support for sections
     32  - Empty lines are ignored, as well as lines beginning with ';' or '#'
     33  - Lines must be of the form: "<keyName> = <value>"
     34  - Key names must start with a letter or an underscore
     35  - Other key name characters can be letters, digits, underscores, dots or
     36    dashes
     37 
     38  - Leading and trailing space are allowed and ignored before/after the key
     39    name and before/after the value
     40 
     41  - There is no restriction on the value, except that it can't contain
     42    leading/trailing space/tab characters or newline/charfeed characters
     43 
     44  - Empty values are possible, and will be stored as an empty string.
     45  - Any badly formatted line is discarded (and will print a warning)
     46 
     47 
     48 II. Android 'aconfig' configuration files:
     49 ------------------------------------------
     50 
     51 Alternatively, another configuration file format is supported by the code
     52 in android/config.[hc]. Its purpose is to support each config file as a
     53 tree of key/value pairs. More specifically:
     54 
     55  - Each key or value is a string
     56  - Each key can be associated either to a value, or a sub-tree
     57  - A (key,value) pair is written in the config file as:
     58 
     59       <keyname> <value>
     60 
     61    which means the key name, some spaces, then the value.
     62 
     63  - Dots can be used to separate keys in a tree path, as in:
     64 
     65      some.other.name   value
     66 
     67    corresponding to a top-level key named 'some' with a single
     68    sub-key 'other' which itself has a sub-key 'name' associated to
     69    value 'value'.
     70 
     71  - As a consequence, key names *cannot* contain a dot.
     72 
     73  - Alternatively, braces can be used to group sub-keys, as in:
     74 
     75      some {
     76         other {
     77             name   value
     78             name2  other-value
     79         }
     80      }
     81 
     82    which defines a top-level 'some' key with two sub-keys 'name' and
     83    'name2'
     84 
     85  - Brace and dot notations are equivalent, so the above config file
     86    can also be written as:
     87 
     88         some.other.name value
     89         some.other.name2 other-value
     90 
     91  - If a key appears twice in the config file, it replaces any
     92    assigned value, hence:
     93 
     94         some-key  foo
     95         some-key  bar
     96 
     97    defines 'some-key' to 'bar'
     98 
     99  - If a sharp (#) appears whenever a key name is expected by the parser,
    100    then it is considered a comment and will be ignored along anything that
    101    follows on the current line.
    102 
    103 
    104