David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 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 | |