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