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 //:core target
19and 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
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
76The rule → file list mapping in the exporter tool looks like:
77
78```go
79var 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
91When the exporter tool is run, it will create the following
92definitions 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
100example_headers = [ "$_include/example/example.h" ]
101
102example_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()`
110calls. This may be desired -- if not the solution is to pull
111the files in a select into a new Bazel filegroup. For example:
112
113```bazel
114filegroup(
115 name = "win_example_srcs",
116 srcs = [ "draw_win.cpp" ],
117)
118
119filegroup(
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
131Or alternatively:
132
133```bazel
134filegroup(
135 name = "win_example_srcs",
136 srcs = select({
137 ":is_windows": [ "draw_win.cpp" ]
138 }).
139)
140
141filegroup(
142 name = "example_srcs",
143 srcs = [
144 "main.cpp",
145 "draw.cpp",
146 ":win_example_srcs", # Not recursively followed.
147 ],
148)
149```
150
151In each case the referenced rule (`win_example_srcs`) is not
152followed and **only files directly listed in a rule are exported**
153to a GNI file.
154