Debian Codegraph @

bazel/exporter_tool/README.md

raw
1 # Bazel Project Exporter
2
3 Skia's authoritative build system is moving to Bazel. For users needing to
4 use other build system, this tool will export a subset of the Bazel build
5 targets to other build systems.
6
7 # Bazel to CMake
8
9 **Note:** This is not meant for any purpose beyond development.
10
11 At the root level of the Skia workspace:
12
13 ```sh
14 make -C bazel generate_cmake
15 ```
16
17 This will write to a single `CMakeLists.txt` file a valid CMake project with
18 targets to build the artifacts covered by the Bazel //:core target
19 and all dependent targets.
20
21 ## Current limitations
22
23 * External dependencies are not supported.
24 * Only the `//:core` rule is supported. Other rules *may* work.
25
26 # Bazel to *.gni
27
28 Generating the predefined `*.gni` files is done by running the following
29 at the root level of the Skia workspace:
30
31 ```sh
32 make -C bazel generate_gni
33 ```
34
35 This will update the `*.gni` files that reside in `//gn` that contain
36 file lists necessary for a GN build. The exporter tool is hardcoded
37 with the Bazel rules to be exported, and to which GNI file and
38 file list they should be mapped. As Bazel project rules are
39 refactored it may be necessary to update the exporter tool to reflect
40 those changes.
41
42 ## Bazel Rule to GNI File List Mapping
43
44 The GNI export process is platform agnostic and generates the GNI files
45 with the same file lists on all platforms. Let's describe the mapping
46 process using a fictitious example program:
47
48 In `//include/example/BUILD.bazel` exists a rule defining the header
49 file:
50
51 ```bazel
52 filegroup(
53 name = "public_hdrs",
54 srcs = [ "example.h" ],
55 )
56 ```
57
58 **Note:** Bazel **visibility rules are ignored**. The exporter
59 tool can export private files.
60
61 In `//src/example/BUILD.bazel` a rule to define the example
62 sources:
63
64 ```bazel
65 filegroup(
66 name = "example_srcs",
67 srcs = [
68 "main.cpp",
69 "draw.cpp",
70 ] + select({
71 ":is_windows": [ "draw_win.cpp" ]
72 })
73 )
74 ```
75
76 The rule → file list mapping in the exporter tool looks like:
77
78 ```go
79 var gniExportDescs = []exporter.GNIExportDesc{
80 // ... Other GNI definitions.
81 {GNI: "gn/example.gni", Vars: []exporter.GNIFileListExportDesc{
82 {Var: "example_headers",
83 Rules: []string{"//include/example:public_hdrs"}},
84 {Var: "example_sources",
85 Rules: []string{"//src/example:example_srcs"}}},
86 },
87 // ... Other GNI definitions.
88 }
89 ```
90
91 When the exporter tool is run, it will create the following
92 definitions in `//gn/example.gni`:
93
94 ```gn
95 # DO NOT EDIT: This is a generated file.
96
97 _src = get_path_info("../src", "abspath")
98 _include = get_path_info("../include", "abspath")
99
100 example_headers = [ "$_include/example/example.h" ]
101
102 example_sources = [
103 "$_src/example/main.cpp",
104 "$_src/example/draw.cpp",
105 "$_src/example/draw_win.cpp",
106 ]
107 ```
108
109 **Note:** The exporter always includes the contents of all `select()`
110 calls. This may be desired -- if not the solution is to pull
111 the files in a select into a new Bazel filegroup. For example:
112
113 ```bazel
114 filegroup(
115 name = "win_example_srcs",
116 srcs = [ "draw_win.cpp" ],
117 )
118
119 filegroup(
120 name = "example_srcs",
121 srcs = [
122 "main.cpp",
123 "draw.cpp",
124 srcs = select({
125 ":is_windows": [ ":win_example_srcs" ]
126 }).
127 ],
128 )
129 ```
130
131 Or alternatively:
132
133 ```bazel
134 filegroup(
135 name = "win_example_srcs",
136 srcs = select({
137 ":is_windows": [ "draw_win.cpp" ]
138 }).
139 )
140
141 filegroup(
142 name = "example_srcs",
143 srcs = [
144 "main.cpp",
145 "draw.cpp",
146 ":win_example_srcs", # Not recursively followed.
147 ],
148 )
149 ```
150
151 In each case the referenced rule (`win_example_srcs`) is not
152 followed and **only files directly listed in a rule are exported**
153 to a GNI file.