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 we 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 36A note on software backend performance 37-------------------------------------- 38 39A number of routines in Skia's software backend have been written to run 40fastest when compiled by Clang. If you depend on software rasterization, image 41decoding, or color space conversion and compile Skia with GCC, MSVC or another 42compiler, you will see dramatically worse performance than if you use Clang. 43 44This choice was only a matter of prioritization; there is nothing fundamentally 45wrong with non-Clang compilers. So if this is a serious issue for you, please 46let us know on the mailing list. 47 48Quickstart 49---------- 50 51Run GN to generate your build files. 52 53 bin/gn gen out/Static --args='is_official_build=true' 54 bin/gn gen out/Shared --args='is_official_build=true is_component_build=true' 55 56If you find you don't have `bin/gn`, make sure you've run 57 58 python tools/git-sync-deps 59 60GN allows fine-grained settings for developers and special situations. 61 62 bin/gn gen out/Debug 63 bin/gn gen out/Release --args='is_debug=false' 64 bin/gn gen out/Clang --args='cc="clang" cxx="clang++"' 65 bin/gn gen out/Cached --args='cc_wrapper="ccache"' 66 bin/gn gen out/RTTI --args='extra_cflags_cc=["-frtti"]' 67 68To see all the arguments available, you can run 69 70 bin/gn args out/Debug --list 71 72Having generated your build files, run Ninja to compile and link Skia. 73 74 ninja -C out/Static 75 ninja -C out/Shared 76 ninja -C out/Debug 77 ninja -C out/Release 78 ninja -C out/Clang 79 ninja -C out/Cached 80 ninja -C out/RTTI 81 82If some header files are missing, install the corresponding dependencies 83 84 tools/install_dependencies.sh 85 86Android 87------- 88 89To build Skia for Android you need an [Android 90NDK](https://developer.android.com/ndk/index.html). 91 92If you do not have an NDK and have access to CIPD, you 93can use one of these commands to fetch the NDK our bots use: 94 95 python infra/bots/assets/android_ndk_linux/download.py -t /tmp/ndk 96 python infra/bots/assets/android_ndk_darwin/download.py -t /tmp/ndk 97 python infra/bots/assets/android_ndk_windows/download.py -t C:/ndk 98 99When generating your GN build files, pass the path to your `ndk` and your 100desired `target_cpu`: 101 102 bin/gn gen out/arm --args='ndk="/tmp/ndk" target_cpu="arm"' 103 bin/gn gen out/arm64 --args='ndk="/tmp/ndk" target_cpu="arm64"' 104 bin/gn gen out/x64 --args='ndk="/tmp/ndk" target_cpu="x64"' 105 bin/gn gen out/x86 --args='ndk="/tmp/ndk" target_cpu="x86"' 106 107Other arguments like `is_debug` and `is_component_build` continue to work. 108Tweaking `ndk_api` gives you access to newer Android features like Vulkan. 109 110To test on an Android device, push the binary and `resources` over, 111and run it as normal. You may find `bin/droid` convenient. 112 113 ninja -C out/arm64 114 adb push out/arm64/dm /data/local/tmp 115 adb push resources /data/local/tmp 116 adb shell "cd /data/local/tmp; ./dm --src gm --config gl" 117 118 119ChromeOS 120-------------- 121To cross-compile Skia for arm ChromeOS devices the following is needed: 122 123 - Clang 4 or newer 124 - An armhf sysroot 125 - The (E)GL lib files on the arm chromebook to link against. 126 127To compile Skia for an x86 ChromeOS device, one only needs Clang and the lib files. 128 129If you have access to CIPD, you can fetch all of these as follows: 130 131 python infra/bots/assets/clang_linux/download.py -t /opt/clang 132 python infra/bots/assets/armhf_sysroot/download.py -t /opt/armhf_sysroot 133 python infra/bots/assets/chromebook_arm_gles/download.py -t /opt/chromebook_arm_gles 134 python infra/bots/assets/chromebook_x86_64_gles/download.py -t /opt/chromebook_x86_64_gles 135 136If you don't have authorization to use those assets, then see the README.md files for 137[armhf_sysroot](https://skia.googlesource.com/skia/+/master/infra/bots/assets/armhf_sysroot/README.md), 138[chromebook_arm_gles](https://skia.googlesource.com/skia/+/master/infra/bots/assets/chromebook_arm_gles/README.md), and 139[chromebook_x86_64_gles](https://skia.googlesource.com/skia/+/master/infra/bots/assets/chromebook_x86_64_gles/README.md) 140for instructions on creating those assets. 141 142Once those files are in place, generate the GN args that resemble the following: 143 144 #ARM 145 cc= "/opt/clang/bin/clang" 146 cxx = "/opt/clang/bin/clang++" 147 148 extra_asmflags = [ 149 "--target=armv7a-linux-gnueabihf", 150 "--sysroot=/opt/armhf_sysroot/", 151 "-march=armv7-a", 152 "-mfpu=neon", 153 "-mthumb", 154 ] 155 extra_cflags=[ 156 "--target=armv7a-linux-gnueabihf", 157 "--sysroot=/opt/armhf_sysroot", 158 "-I/opt/chromebook_arm_gles/include", 159 "-I/opt/armhf_sysroot/include/", 160 "-I/opt/armhf_sysroot/include/c++/4.8.4/", 161 "-I/opt/armhf_sysroot/include/c++/4.8.4/arm-linux-gnueabihf/", 162 "-DMESA_EGL_NO_X11_HEADERS", 163 "-funwind-tables", 164 ] 165 extra_ldflags=[ 166 "--sysroot=/opt/armhf_sysroot", 167 "-B/opt/armhf_sysroot/bin", 168 "-B/opt/armhf_sysroot/gcc-cross", 169 "-L/opt/armhf_sysroot/gcc-cross", 170 "-L/opt/armhf_sysroot/lib", 171 "-L/opt/chromebook_arm_gles/lib", 172 "--target=armv7a-linux-gnueabihf", 173 ] 174 target_cpu="arm" 175 skia_use_fontconfig = false 176 skia_use_system_freetype2 = false 177 skia_use_egl = true 178 179 180 # x86_64 181 cc= "/opt/clang/bin/clang" 182 cxx = "/opt/clang/bin/clang++" 183 extra_cflags=[ 184 "-I/opt/clang/include/c++/v1/", 185 "-I/opt/chromebook_x86_64_gles/include", 186 "-DMESA_EGL_NO_X11_HEADERS", 187 "-DEGL_NO_IMAGE_EXTERNAL", 188 ] 189 extra_ldflags=[ 190 "-stdlib=libc++", 191 "-fuse-ld=lld", 192 "-L/opt/chromebook_x86_64_gles/lib", 193 ] 194 target_cpu="x64" 195 skia_use_fontconfig = false 196 skia_use_system_freetype2 = false 197 skia_use_egl = true 198 199Compile dm (or another executable of your choice) with ninja, as per usual. 200 201Push the binary to a chromebook via ssh and [run dm as normal](https://skia.org/dev/testing/tests) 202using the gles GPU config. 203 204Most chromebooks by default have their home directory partition marked as noexec. 205To avoid "permission denied" errors, remember to run something like: 206 207 sudo mount -i -o remount,exec /home/chronos 208 209Mac 210--- 211 212Mac users may want to pass `--ide=xcode` to `bin/gn gen` to generate an Xcode project. 213 214iOS 215--- 216 217Run GN to generate your build files. Set `target_os="ios"` to build for iOS. 218This defaults to `target_cpu="arm64"`. Choosing `x64` targets the iOS simulator. 219 220 bin/gn gen out/ios64 --args='target_os="ios"' 221 bin/gn gen out/ios32 --args='target_os="ios" target_cpu="arm"' 222 bin/gn gen out/iossim --args='target_os="ios" target_cpu="x64"' 223 224This will also package (and for devices, sign) iOS test binaries. This defaults to a 225Google signing identity and provisioning profile. To use a different one set `skia_ios_identity` 226to match your code signing identity and `skia_ios_profile` to the name of your provisioning 227profile, e.g. `skia_ios_identity=".*Jane Doe.*" skia_ios_profile="iPad Profile"`. A list of 228identities can be found by typing `security find-identity` on the command line. The name of the 229provisioning profile should be available on the Apple Developer site. 230 231For signed packages `ios-deploy` makes installing and running them on a device easy: 232 233 ios-deploy -b out/Debug/dm.app -d --args "--match foo" 234 235Alternatively you can generate an Xcode project by passing `--ide=xcode` to `bin/gn gen`. 236 237If you find yourself missing a Google signing identity or provisioning profile, 238you'll want to have a read through go/appledev. 239 240Deploying to a device with an OS older than the current SDK doesn't currently work through Xcode, 241but can be done on the command line by setting the environment variable IPHONEOS_DEPLOYMENT_TARGET 242to the desired OS version. 243 244Windows 245------- 246 247Skia can build on Windows with Visual Studio 2017 or Visual Studio 2015 Update 3. 248If GN is unable to locate either of those, it will print an error message. In that 249case, you can pass your `VC` path to GN via `win_vc`. 250 251Skia can be compiled with the free [Build Tools for Visual Studio 2522017](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017). 253 254The bots use a packaged 2017 toolchain, which Googlers can download like this: 255 256 python infra/bots/assets/win_toolchain/download.py -t C:/toolchain 257 258You can then pass the VC and SDK paths to GN by setting your GN args: 259 260 win_vc = "C:\toolchain\VC" 261 win_sdk = "C:\toolchain\win_sdk" 262 263This toolchain is the only way we support 32-bit builds, by also setting `target_cpu="x86"`. 264There is also a corresponding 2015 toolchain, downloaded via `infra/bots/assets/win_toolchain_2015`. 265 266The Skia build assumes that the PATHEXT environment variable contains ".EXE". 267 268### **Highly Recommended**: Build with clang-cl 269 270Skia uses generated code that is only optimized when Skia is built with clang. Other compilers get generic 271unoptimized code. 272 273Setting the `cc` and `cxx` gn args is _not_ sufficient to build with clang-cl. These variables 274are ignored on Windows. Instead set the variable `clang_win` to your LLVM installation directory. 275If you installed the prebuilt LLVM downloaded from [here](https://releases.llvm.org/download.html "LLVM Download") in the default location that would be: 276 277 clang_win = "C:\Program Files\LLVM" 278 279Follow the standard Windows path specification and not MinGW convention (e.g. `C:\Program Files\LLVM` not ~~`/c/Program Files/LLVM`~~). 280 281### Visual Studio Solutions 282 283If you use Visual Studio, you may want to pass `--ide=vs` to `bin/gn gen` to 284generate `all.sln`. That solution will exist within the GN directory for the 285specific configuration, and will only build/run that configuration. 286 287If you want a Visual Studio Solution that supports multiple GN configurations, 288there is a helper script. It requires that all of your GN directories be inside 289the `out` directory. First, create all of your GN configurations as usual. 290Pass `--ide=vs` when running `bin/gn gen` for each one. Then: 291 292 python gn/gn_meta_sln.py 293 294This creates a new dedicated output directory and solution file 295`out/sln/skia.sln`. It has one solution configuration for each GN configuration, 296and supports building and running any of them. It also adjusts syntax highlighting 297of inactive code blocks based on preprocessor definitions from the selected 298solution configuration. 299 300Windows ARM64 301------------- 302 303There is early, experimental support for [Windows 10 on ARM](https://docs.microsoft.com/en-us/windows/arm/). 304This currently requires (a recent version of) MSVC, and the `Visual C++ compilers and libraries for ARM64` 305individual component in the Visual Studio Installer. For Googlers, the win_toolchain asset includes the 306ARM64 compiler. 307 308To use that toolchain, set the `target_cpu` GN argument to `"arm64"`. Note that OpenGL is not supported 309by Windows 10 on ARM, so Skia's GL backends are stubbed out, and will not work. ANGLE is supported: 310 311 bin/gn gen out/win-arm64 --args='target_cpu="arm64" skia_use_angle=true' 312 313This will produce a build of Skia that can use the software or ANGLE backends, in DM. Viewer only works 314when launched with `--backend angle`, because the software backend tries to use OpenGL to display the 315window contents. 316 317CMake 318----- 319 320We have added a GN-to-CMake translator mainly for use with IDEs that like CMake 321project descriptions. This is not meant for any purpose beyond development. 322 323 bin/gn gen out/config --ide=json --json-ide-script=../../gn/gn_to_cmake.py 324