1VNDK Definition Tool
2====================
3
4VNDK definition tool was designed to classify all shared libraries in the
5system partition and give suggestions to copy necessary libraries to the vendor
6partition.
7
8## Usage
9
10To run VNDK definition tool, you will need three inputs:
11
121. The system and vendor image for your target
132. Android Treble reference image
143. Eligible VNDK list from Google (e.g. eligible-list-v3.0.csv)
15
16The high-level overview of the command line usage is:
17
18    $ python3 ./vndk_definition_tool.py vndk \
19        --system "/path/to/your/product_out/system" \
20        --vendor "/path/to/your/product_out/vendor" \
21        --aosp-system "/path/to/aosp/generic/system" \
22        --tag-file "eligible-list-v3.0.csv"
23
24This command will print several lines such as:
25
26    vndk-sp: libexample1.so
27    vndk-sp-ext: libexample2.so
28    extra-vendor-libs: libexample3.so
29
30The output implies:
31
321. `libexample1.so` should be copied to `/system/lib[64]/vndk-sp`.
332. `libexample2.so` should be copied to `/vendor/lib[64]/vndk-sp`.
343. `libexample3.so` should be copied to `/vendor/lib[64]`.
35
36
37# Makefile Boilerplates
38
39There are some boilerplates in `templates` directory that can automate the
40process to copy shared libraries.  Please copy a boilerplate, rename it as
41`Android.mk`, and replace the placeholders with corresponding values:
42
43* `##_VNDK_SP_##` should be replaced by library names tagged with `vndk_sp`.
44
45* `##_VNDK_SP_EXT_##` should be replaced by library names tagged with
46  `vndk_sp_ext`.
47
48* `##_EXTRA_VENDOR_LIBS_##` should be replaced by library names tagged with
49  `extra_vendor_libs`.
50
51* `$(YOUR_DEVICE_NAME)` has to be replaced by your own device product name.
52
53VNDK definition tool can fill in the library names and generate an `Android.mk`
54when the `--output-format=make` is specified:
55
56    $ python3 ./vndk_definition_tool.py vndk \
57        --system "/path/to/your/product_out/system" \
58        --vendor "/path/to/your/product_out/vendor" \
59        --aosp-system "/path/to/aosp/generic/system" \
60        --tag-file "eligible-list-v3.0.csv" \
61        --output-format=make
62
63These boilerplates only define the modules to copy shared libraries.
64Developers have to add the phony package name to `PRODUCT_PACKAGES` variable in
65the `device.mk` for their devices.
66
67    PRODUCT_PACKAGES += $(YOUR_DEVICE_NAME)-vndk
68
69
70## Ignore Subdirectories
71
72Some devices keep their vendor modules in `/system/vendor`.  To run VNDK
73definition tool for those devices, we have to skip `/system/vendor` and specify
74it with `--vendor` option.  For example:
75
76    python3 vndk_definition_tool.py vndk \
77        --system ${ANDROID_PRODUCT_OUT}/system \
78        --system-dir-ignored vendor \
79        --vendor ${ANDROID_PRODUCT_OUT}/system/vendor \
80        # ...
81
82
83## Implicit Dependencies
84
85If there are implicit dependencies, such as `dlopen()`, we can specify them in
86a dependency file and load the dependency file with `--load-extra-deps`.  The
87dependency file format is simple: (a) each line stands for a dependency, and
88(b) the file before the colon depends on the file after the colon.  For
89example, `libart.so` depends on `libart-compiler.so`:
90
91    /system/lib64/libart.so: /system/lib64/libart-compiler.so
92
93And then, run VNDK definition tool with:
94
95    $ python3 vndk_definition_tool.py vndk \
96        --system ${ANDROID_PRODUCT_OUT}/system \
97        --vendor ${ANDROID_PRODUCT_OUT}/vendor \
98        --aosp-system ${ANDROID_PRODUCT_OUT}/../generic_arm64_a \
99        --tag-file eligible-list-v3.0.csv \
100        --load-extra-deps dlopen.dep
101
102
103## Remarks
104
105To run VNDK definition tool against an image (`.img`), run the following
106command to mount the images and run `vndk_definition_tool.py` with `sudo`:
107
108    $ simg2img system.img system.raw.img
109
110    $ simg2img vendor.img vendor.raw.img
111
112    $ mkdir system
113
114    $ mkdir vendor
115
116    $ sudo mount -o loop,ro system.raw.img system
117
118    $ sudo mount -o loop,ro vendor.raw.img vendor
119
120    $ sudo python3 vndk_definition_tool.py vndk \
121        --system system \
122        --vendor vendor \
123        --aosp-system /path/to/aosp/generic/system \
124        --tag-file eligible-list-v3.0.csv
125