README.md
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