1 How to build Skia 2 ================= 3 4 Make sure you have first followed the [instructions to download 5 Skia](./download). 6 7 Skia uses [GN](https://chromium.googlesource.com/chromium/src/tools/gn/) to 8 configure its builds. 9 10 `is_official_build` and Third-party Dependencies 11 ------------------------------------------------ 12 13 Most users of Skia should set `is_official_build=true`, and most developers 14 should leave it to its `false` default. 15 16 This mode configures Skia in a way that's suitable to ship: an optimized build 17 with no debug symbols, dynamically linked against its third-party dependencies 18 using the ordinary library search path. 19 20 In contrast, the developer-oriented default is an unoptimized build with full 21 debug symbols and all third-party dependencies built from source and embedded 22 into libskia. This is how we do all our manual and automated testing. 23 24 Skia offers several features that make use of third-party libraries, like 25 libpng, libwebp, or libjpeg-turbo to decode images, or ICU and sftnly to subset 26 fonts. All these third-party dependencies are optional and can be controlled 27 by a GN argument that looks something like `skia_use_foo` for appropriate 28 `foo`. 29 30 If `skia_use_foo` is enabled, enabling `skia_use_system_foo` will build and 31 link 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 33 use `extra_cflags` and `extra_ldflags` to add include or library paths if 34 needed. 35 36 Quickstart 37 ---------- 38 39 Run 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 44 If you find you don't have `bin/gn`, make sure you've run 45 46 python tools/git-sync-deps 47 48 GN 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 56 To see all the arguments available, you can run 57 58 bin/gn args out/Debug --list 59 60 Having 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 70 If some header files are missing, install the corresponding dependencies 71 72 tools/install_dependencies.sh 73 74 Android 75 ------- 76 77 To build Skia for Android you need an [Android 78 NDK](https://developer.android.com/ndk/index.html). 79 80 If you do not have an NDK and have access to CIPD, you 81 can use one of these commands to fetch the NDK our bots use: 82 83 python infra/bots/assets/android_ndk_linux/download.py -t /tmp/ndk 84 python infra/bots/assets/android_ndk_darwin/download.py -t /tmp/ndk 85 python infra/bots/assets/android_ndk_windows/download.py -t C:/ndk 86 87 When generating your GN build files, pass the path to your `ndk` and your 88 desired `target_cpu`: 89 90 bin/gn gen out/arm --args='ndk="/tmp/ndk" target_cpu="arm"' 91 bin/gn gen out/arm64 --args='ndk="/tmp/ndk" target_cpu="arm64"' 92 bin/gn gen out/x64 --args='ndk="/tmp/ndk" target_cpu="x64"' 93 bin/gn gen out/x86 --args='ndk="/tmp/ndk" target_cpu="x86"' 94 95 Other arguments like `is_debug` and `is_component_build` continue to work. 96 Tweaking `ndk_api` gives you access to newer Android features like Vulkan. 97 98 To test on an Android device, push the binary and `resources` over, 99 and run it as normal. You may find `bin/droid` convenient. 100 101 ninja -C out/arm64 102 adb push out/arm64/dm /data/local/tmp 103 adb push resources /data/local/tmp 104 adb shell "cd /data/local/tmp; ./dm --src gm --config gl" 105 106 107 ChromeOS 108 -------------- 109 To cross-compile Skia for arm ChromeOS devices the following is needed: 110 111 - Clang 4 or newer 112 - An armhf sysroot 113 - The (E)GL lib files on the arm chromebook to link against. 114 115 To compile Skia for an x86 ChromeOS device, one only needs Clang and the lib files. 116 117 If you have access to CIPD, you can fetch all of these as follows: 118 119 python infra/bots/assets/clang_linux/download.py -t /opt/clang 120 python infra/bots/assets/armhf_sysroot/download.py -t /opt/armhf_sysroot 121 python infra/bots/assets/chromebook_arm_gles/download.py -t /opt/chromebook_arm_gles 122 python infra/bots/assets/chromebook_x86_64_gles/download.py -t /opt/chromebook_x86_64_gles 123 124 If you don't have authorization to use those assets, then see the README.md files for 125 [armhf_sysroot](https://skia.googlesource.com/skia/+/master/infra/bots/assets/armhf_sysroot/README.md), 126 [chromebook_arm_gles](https://skia.googlesource.com/skia/+/master/infra/bots/assets/chromebook_arm_gles/README.md), and 127 [chromebook_x86_64_gles](https://skia.googlesource.com/skia/+/master/infra/bots/assets/chromebook_x86_64_gles/README.md) 128 for instructions on creating those assets. 129 130 Once those files are in place, generate the GN args that resemble the following: 131 132 #ARM 133 cc= "/opt/clang/bin/clang" 134 cxx = "/opt/clang/bin/clang++" 135 136 extra_asmflags = [ 137 "--target=armv7a-linux-gnueabihf", 138 "--sysroot=/opt/armhf_sysroot/", 139 "-march=armv7-a", 140 "-mfpu=neon", 141 "-mthumb", 142 ] 143 extra_cflags=[ 144 "--target=armv7a-linux-gnueabihf", 145 "--sysroot=/opt/armhf_sysroot", 146 "-I/opt/chromebook_arm_gles/include", 147 "-I/opt/armhf_sysroot/include/", 148 "-I/opt/armhf_sysroot/include/c++/4.8.4/", 149 "-I/opt/armhf_sysroot/include/c++/4.8.4/arm-linux-gnueabihf/", 150 "-DMESA_EGL_NO_X11_HEADERS", 151 "-funwind-tables", 152 ] 153 extra_ldflags=[ 154 "--sysroot=/opt/armhf_sysroot", 155 "-B/opt/armhf_sysroot/bin", 156 "-B/opt/armhf_sysroot/gcc-cross", 157 "-L/opt/armhf_sysroot/gcc-cross", 158 "-L/opt/armhf_sysroot/lib", 159 "-L/opt/chromebook_arm_gles/lib", 160 "--target=armv7a-linux-gnueabihf", 161 ] 162 target_cpu="arm" 163 skia_use_fontconfig = false 164 skia_use_system_freetype2 = false 165 skia_use_egl = true 166 167 168 # x86_64 169 cc= "/opt/clang/bin/clang" 170 cxx = "/opt/clang/bin/clang++" 171 extra_cflags=[ 172 "-I/opt/clang/include/c++/v1/", 173 "-I/opt/chromebook_x86_64_gles/include", 174 "-DMESA_EGL_NO_X11_HEADERS", 175 "-DEGL_NO_IMAGE_EXTERNAL", 176 ] 177 extra_ldflags=[ 178 "-stdlib=libc++", 179 "-fuse-ld=lld", 180 "-L/opt/chromebook_x86_64_gles/lib", 181 ] 182 target_cpu="x64" 183 skia_use_fontconfig = false 184 skia_use_system_freetype2 = false 185 skia_use_egl = true 186 187 Compile dm (or another executable of your choice) with ninja, as per usual. 188 189 Push the binary to a chromebook via ssh and [run dm as normal](https://skia.org/dev/testing/tests) 190 using the gles GPU config. 191 192 Most chromebooks by default have their home directory partition marked as noexec. 193 To avoid "permission denied" errors, remember to run something like: 194 195 sudo mount -i -o remount,exec /home/chronos 196 197 Mac 198 --- 199 200 Mac users may want to pass `--ide=xcode` to `bin/gn gen` to generate an Xcode project. 201 202 iOS 203 --- 204 205 Run GN to generate your build files. Set `target_os="ios"` to build for iOS. 206 This defaults to `target_cpu="arm64"`. Choosing `x64` targets the iOS simulator. 207 208 bin/gn gen out/ios64 --args='target_os="ios"' 209 bin/gn gen out/ios32 --args='target_os="ios" target_cpu="arm"' 210 bin/gn gen out/iossim --args='target_os="ios" target_cpu="x64"' 211 212 This will also package (and for devices, sign) iOS test binaries. This defaults to a 213 Google signing identity and provisioning profile. To use a different one set `skia_ios_identity` 214 to match your code signing identity and `skia_ios_profile` to the name of your provisioning 215 profile, e.g. `skia_ios_identity=".*Jane Doe.*" skia_ios_profile="iPad Profile"`. A list of 216 identities can be found by typing `security find-identity` on the command line. The name of the 217 provisioning profile should be available on the Apple Developer site. 218 219 For signed packages `ios-deploy` makes installing and running them on a device easy: 220 221 ios-deploy -b out/Debug/dm.app -d --args "--match foo" 222 223 Alternatively you can generate an Xcode project by passing `--ide=xcode` to `bin/gn gen`. 224 225 If you find yourself missing a Google signing identity or provisioning profile, 226 you'll want to have a read through go/appledev. 227 228 Deploying to a device with an OS older than the current SDK doesn't currently work through Xcode, 229 but can be done on the command line by setting the environment variable IPHONEOS_DEPLOYMENT_TARGET 230 to the desired OS version. 231 232 Windows 233 ------- 234 235 Skia can build on Windows with Visual Studio 2017 or Visual Studio 2015 Update 3. 236 If GN is unable to locate either of those, it will print an error message. In that 237 case, you can pass your `VC` path to GN via `win_vc`. 238 239 Skia can be compiled with the free [Build Tools for Visual Studio 240 2017](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017). 241 242 The bots use a packaged 2017 toolchain, which Googlers can download like this: 243 244 python infra/bots/assets/win_toolchain/download.py -t C:/toolchain 245 246 You can then pass the VC and SDK paths to GN by setting your GN args: 247 248 win_vc = "C:\toolchain\depot_tools\win_toolchain\vs_files\a9e1098bba66d2acccc377d5ee81265910f29272\VC" 249 win_sdk = "C:\toolchain\depot_tools\win_toolchain\vs_files\a9e1098bba66d2acccc377d5ee81265910f29272\win_sdk" 250 251 This toolchain is the only way we support 32-bit builds, by also setting `target_cpu="x86"`. 252 There is also a corresponding 2015 toolchain, downloaded via `infra/bots/assets/win_toolchain_2015`. 253 254 ### Visual Studio Solutions 255 256 If you use Visual Studio, you may want to pass `--ide=vs` to `bin/gn gen` to 257 generate `all.sln`. That solution will exist within the GN directory for the 258 specific configuration, and will only build/run that configuration. 259 260 If you want a Visual Studio Solution that supports multiple GN configurations, 261 there is a helper script. It requires that all of your GN directories be inside 262 the `out` directory. First, create all of your GN configurations as usual. 263 Pass `--ide=vs` when running `bin/gn gen` for each one. Then: 264 265 python gn/gn_meta_sln.py 266 267 This creates a new dedicated output directory and solution file 268 `out/sln/skia.sln`. It has one solution configuration for each GN configuration, 269 and supports building and running any of them. It also adjusts syntax highlighting 270 of inactive code blocks based on preprocessor definitions from the selected 271 solution configuration. 272 273 CMake 274 ----- 275 276 We have added a GN-to-CMake translator mainly for use with IDEs that like CMake 277 project descriptions. This is not meant for any purpose beyond development. 278 279 bin/gn gen out/config --ide=json --json-ide-script=../../gn/gn_to_cmake.py 280
