1How to build Skia
2=================
3
4Make sure you have first followed the [instructions to download
5Skia](./download).
6
7Skia uses [GN](https://chromium.googlesource.com/chromium/src/tools/gn/) to
8configure its builds.
9
10`is_official_build` and Third-party Dependencies
11------------------------------------------------
12
13Most users of Skia should set `is_official_build=true`, and most developers
14should leave it to its `false` default.
15
16This mode configures Skia in a way that's suitable to ship: an optimized build
17with no debug symbols, dynamically linked against its third-party dependencies
18using the ordinary library search path.
19
20In contrast, the developer-oriented default is an unoptimized build with full
21debug symbols and all third-party dependencies built from source and embedded
22into libskia.  This is how do all our manual and automated testing.
23
24Skia offers several features that make use of third-party libraries, like
25libpng, libwebp, or libjpeg-turbo to decode images, or ICU and sftnly to subset
26fonts.  All these third-party dependencies are optional and can be controlled
27by a GN argument that looks something like `skia_use_foo` for appropriate
28`foo`.
29
30If `skia_use_foo` is enabled, enabling `skia_use_system_foo` will build and
31link Skia against the headers and libaries found on the system paths.
32`is_official_build=true` enables all `skia_use_system_foo` by default.  You can
33use `extra_cflags` and `extra_ldflags` to add include or library paths if
34needed.
35
36Quickstart
37----------
38
39Run GN to generate your build files.
40
41    bin/gn gen out/Static --args='is_official_build=true'
42    bin/gn gen out/Shared --args='is_official_build=true is_component_build=true'
43
44If you find you don't have `bin/gn`, make sure you've run
45
46    python tools/git-sync-deps
47
48GN allows fine-grained settings for developers and special situations.
49
50    bin/gn gen out/Debug
51    bin/gn gen out/Release  --args='is_debug=false'
52    bin/gn gen out/Clang    --args='cc="clang" cxx="clang++"'
53    bin/gn gen out/Cached   --args='cc_wrapper="ccache"'
54    bin/gn gen out/RTTI     --args='extra_cflags_cc=["-frtti"]'
55
56To see all the arguments available, you can run
57
58    bin/gn args out/Debug --list
59
60Having generated your build files, run Ninja to compile and link Skia.
61
62    ninja -C out/Static
63    ninja -C out/Shared
64    ninja -C out/Debug
65    ninja -C out/Release
66    ninja -C out/Clang
67    ninja -C out/Cached
68    ninja -C out/RTTI
69
70Android
71-------
72
73To build Skia for Android you need an [Android
74NDK](https://developer.android.com/ndk/index.html).
75
76If you do not have an NDK and have access to CIPD, you
77can use one of these commands to fetch the NDK our bots use:
78
79    python infra/bots/assets/android_ndk_linux/download.py  -t /tmp/ndk
80    python infra/bots/assets/android_ndk_darwin/download.py -t /tmp/ndk
81    python infra/bots/assets/android_ndk_windows/download.py -t C:/ndk
82
83When generating your GN build files, pass the path to your `ndk` and your
84desired `target_cpu`:
85
86    bin/gn gen out/arm      --args='ndk="/tmp/ndk" target_cpu="arm"'
87    bin/gn gen out/arm64    --args='ndk="/tmp/ndk" target_cpu="arm64"'
88    bin/gn gen out/mips64el --args='ndk="/tmp/ndk" target_cpu="mips64el"'
89    bin/gn gen out/mipsel   --args='ndk="/tmp/ndk" target_cpu="mipsel"'
90    bin/gn gen out/x64      --args='ndk="/tmp/ndk" target_cpu="x64"'
91    bin/gn gen out/x86      --args='ndk="/tmp/ndk" target_cpu="x86"'
92
93Other arguments like `is_debug` and `is_component_build` continue to work.
94Tweaking `ndk_api` gives you access to newer Android features like Vulkan.
95
96To test on an Android device, push the binary and `resources` over,
97and run it as normal.  You may find `bin/droid` convenient.
98
99    ninja -C out/arm64
100    adb push out/arm64/dm /data/local/tmp
101    adb push resources /data/local/tmp
102    adb shell "cd /data/local/tmp; ./dm --src gm --config gl"
103
104Mac
105---
106
107Mac users may want to pass `--ide=xcode` to `bin/gn gen` to generate an Xcode project.
108
109iOS
110---
111
112Run GN to generate your build files.  Set `target_os="ios"` to build for iOS.
113This defaults to `target_cpu="arm64"`.  Choosing `x64` targets the iOS simulator.
114
115    bin/gn gen out/ios64  --args='target_os="ios"'
116    bin/gn gen out/ios32  --args='target_os="ios" target_cpu="arm"'
117    bin/gn gen out/iossim --args='target_os="ios" target_cpu="x64"'
118
119Googlers who want to sign and run iOS test binaries can do so by running something like
120
121    python gn/package_ios.py out/Debug/dm
122    python gn/package_ios.py out/Release/nanobench
123
124These commands will create and sign `dm.app` or `nanobench.app` packages you
125can push to iOS devices registered for Google development.  `ios-deploy` makes
126installing and running these packages easy:
127
128    ios-deploy -b out/Debug/dm.app -d --args "--match foo"
129
130If you find yourself missing a Google signing identity or provisioning profile,
131you'll want to have a read through go/appledev.
132
133Windows
134-------
135
136Skia can build on Windows with Visual Studio 2015 Update 3.  No older or newer
137version is supported. The bots use a packaged toolchain, which you may be able
138to download like this:
139
140    python infra/bots/assets/win_toolchain/download.py -t C:/toolchain
141
142If you pass that downloaded path to GN via `windk`, you can build using that
143toolchain instead of your own from Visual Studio.  This toolchain is the only
144way we support 32-bit builds, by also setting `target_cpu="x86"`.
145
146### Visual Studio Solutions
147
148If you use Visual Studio, you may want to pass `--ide=vs` to `bin/gn gen` to
149generate `all.sln`.  That solution will exist within the GN directory for the
150specific configuration, and will only build/run that configuration.
151
152If you want a Visual Studio Solution that supports multiple GN configurations,
153there is a helper script. It requires that all of your GN directories be inside
154the `out` directory. First, create all of your GN configurations as usual.
155Pass `--ide=vs` when running `bin/gn gen` for each one. Then:
156
157    python gn/gn_meta_sln.py
158
159This creates a new dedicated output directory and solution file
160`out/sln/skia.sln`. It has one solution configuration for each GN configuration,
161and supports building and running any of them. It also adjusts syntax highlighting
162of inactive code blocks based on preprocessor definitions from the selected
163solution configuration.
164
165CMake
166-----
167
168We have added a GN-to-CMake translator mainly for use with IDEs that like CMake
169project descriptions.  This is not meant for any purpose beyond development.
170
171    bin/gn gen out/config --ide=json --json-ide-script=../../gn/gn_to_cmake.py
172