README.md
1# FS Config Generator
2
3The `fs_config_generator.py` tool uses the platform `android_filesystem_config.h` and the
4`TARGET_FS_CONFIG_GEN` files to generate the following:
5* `fs_config_dirs` and `fs_config_files` files for each partition
6* `passwd` and `group` files for each partition
7* The `generated_oem_aid.h` header
8
9## Outputs
10
11### `fs_config_dirs` and `fs_config_files`
12
13The `fs_config_dirs` and `fs_config_files` binary files are interpreted by the libcutils
14`fs_config()` function, along with the built-in defaults, to serve as overrides to complete the
15results. The Target files are used by filesystem and adb tools to ensure that the file and directory
16properties are preserved during runtime operations. The host files in the `$OUT` directory are used
17in the final stages when building the filesystem images to set the file and directory properties.
18
19See `./fs_config_generator.py fsconfig --help` for how these files are generated.
20
21### `passwd` and `group` files
22
23The `passwd` and `group` files are formatted as documented in man pages passwd(5) and group(5) and
24used by bionic for implementing `getpwnam()` and related functions.
25
26See `./fs_config_generator.py passwd --help` and `./fs_config_generator.py group --help` for how
27these files are generated.
28
29### The `generated_oem_aid.h` header
30
31The `generated_oem_aid.h` creates identifiers for non-platform AIDs for developers wishing to use
32them in their native code. To do so, include the `oemaids_headers` header library in the
33corresponding makefile and `#include "generated_oem_aid.h"` in the code wishing to use these
34identifiers.
35
36See `./fs_config_generator.py oemaid --help` for how this file is generated.
37
38## Parsing
39
40See the documentation on [source.android.com](https://source.android.com/devices/tech/config/filesystem#configuring-aids) for details and examples.
41
42
43## Ordering
44
45Ordering within the `TARGET_FS_CONFIG_GEN` files is not relevant. The paths for files are sorted
46like so within their respective array definition:
47 * specified path before prefix match
48 * for example: foo before f*
49 * lexicographical less than before other
50 * for example: boo before foo
51
52Given these paths:
53
54 paths=['ac', 'a', 'acd', 'an', 'a*', 'aa', 'ac*']
55
56The sort order would be:
57
58 paths=['a', 'aa', 'ac', 'acd', 'an', 'ac*', 'a*']
59
60Thus the `fs_config` tools will match on specified paths before attempting prefix, and match on the
61longest matching prefix.
62
63The declared AIDs are sorted in ascending numerical order based on the option "value". The string
64representation of value is preserved. Both choices were made for maximum readability of the
65generated file and to line up files. Sync lines are placed with the source file as comments in the
66generated header file.
67
68## Unit Tests
69
70From within the `fs_config` directory, unit tests can be executed like so:
71
72 $ python test_fs_config_generator.py
73 ................
74 ----------------------------------------------------------------------
75 Ran 16 tests in 0.004s
76 OK
77
78
79One could also use nose if they would like:
80
81 $ nose2
82
83To add new tests, simply add a `test_<xxx>` method to the test class. It will automatically
84get picked up and added to the test suite.
85