site/user/build.md

   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 A few build configurations remain unported to GN, so you may see some `.gyp`
  11 files laying around left over from when we used GYP.  Don't bother looking at
  12 them.
  13
  14 Quickstart
  15 ----------
  16
  17 After gclient sync, run `fetch-gn` to make sure you have GN.
  18
  19     gclient sync && python bin/fetch-gn
  20
  21 Run GN to generate your build files.
  22
  23     gn gen out/Static --args='is_official_build=true'
  24     gn gen out/Shared --args='is_official_build=true is_component_build=true'
  25
  26 GN allows fine-grained settings for developers and special situations.
  27
  28     gn gen out/Debug
  29     gn gen out/Release  --args='is_debug=false'
  30     gn gen out/Clang    --args='cc="clang" cxx="clang++"'
  31     gn gen out/Cached   --args='cc_wrapper="ccache"'
  32     gn gen out/RTTI     --args='extra_cflags_cc=["-frtti"]'
  33
  34 To see all the arguments available, you can run
  35
  36     gn args out/Debug --list
  37
  38 Having generated your build files, run Ninja to compile and link Skia.
  39
  40     ninja -C out/Static
  41     ninja -C out/Shared
  42     ninja -C out/Debug
  43     ninja -C out/Release
  44     ninja -C out/Clang
  45     ninja -C out/Cached
  46     ninja -C out/RTTI
  47
  48 Android
  49 -------
  50
  51 To build Skia for Android you need an [Android
  52 NDK](https://developer.android.com/ndk/index.html).
  53
  54 If you do not have an NDK and have access to CIPD, you
  55 can use one of these commands to fetch the NDK our bots use:
  56
  57     python infra/bots/assets/android_ndk_linux/download.py  -t /tmp/ndk
  58     python infra/bots/assets/android_ndk_darwin/download.py -t /tmp/ndk
  59     python infra/bots/assets/android_ndk_windows/download.py -t C:/ndk
  60
  61 When generating your GN build files, pass the path to your `ndk` and your
  62 desired `target_cpu`:
  63
  64     gn gen out/arm      --args='ndk="/tmp/ndk" target_cpu="arm"'
  65     gn gen out/arm64    --args='ndk="/tmp/ndk" target_cpu="arm64"'
  66     gn gen out/mips64el --args='ndk="/tmp/ndk" target_cpu="mips64el"'
  67     gn gen out/mipsel   --args='ndk="/tmp/ndk" target_cpu="mipsel"'
  68     gn gen out/x64      --args='ndk="/tmp/ndk" target_cpu="x64"'
  69     gn gen out/x86      --args='ndk="/tmp/ndk" target_cpu="x86"'
  70
  71 Other arguments like `is_debug` and `is_component_build` continue to work.
  72 Tweaking `ndk_api` gives you access to newer Android features like Vulkan.
  73
  74 To test on an Android device, push the binary and `resources` over,
  75 and run it as normal.  You may find `bin/droid` convenient.
  76
  77     ninja -C out/arm64
  78     adb push out/arm64/dm /data/local/tmp
  79     adb push resources /data/local/tmp
  80     adb shell "cd /data/local/tmp; ./dm --src gm --config gpu"
  81
  82 Mac
  83 ---
  84
  85 Mac users may want to pass `--ide=xcode` to `gn gen` to generate an Xcode project.
  86
  87 Windows
  88 -------
  89
  90 Skia can build on Windows with Visual Studio 2015 Update 3.  No older or newer
  91 version is supported.  If you use Visual Studio, you may want to pass
  92 `--ide=vs` to `gn gen` to generate `all.sln`.
  93
  94 The bots use a packaged toolchain, which you may be able to download like this:
  95
  96     python infra/bots/assets/win_toolchain/download.py -t C:/toolchain
  97
  98 If you pass that downloaded path to GN via `windk`, you can build using that
  99 toolchain instead of your own from Visual Studio.  This toolchain is the only
 100 way we support 32-bit builds, by also setting `target_cpu="x86"`.
 101
 102 CMake
 103 -----
 104
 105 We have added a GN-to-CMake translator mainly for use with IDEs that like CMake
 106 project descriptions.  This is not meant for any purpose beyond development.
 107
 108     gn gen out/config --ide=json --json-ide-script=../../gn/gn_to_cmake.py
 109
 110 Third-party Dependencies
 111 ------------------------
 112
 113 Skia offers several features that make use of third-party libraries, like
 114 libpng, libwebp, or libjpeg-turbo to decode images, or ICU and sftnly to subset
 115 fonts.  All these third-party dependencies are optional, and can be controlled
 116 by a GN argument that looks something like `skia_use_foo` for appropriate
 117 `foo`.
 118
 119 Most of these third-party dependencies can also be satisfied by pre-built
 120 system libraries.  If `skia_use_foo` is enabled, turn on `skia_use_system_foo`
 121 to build and link Skia against the headers and libaries found on the system
 122 paths.  You can use `extra_cflags` and `extra_ldflags` to add include or
 123 library paths if needed.
 124
 125 By default Skia will build and embed its own copies of these third-party
 126 libraries.  This configuration is for development only.  We do not recommend
 127 shipping Skia this way.  However, this is the only configuration of Skia that
 128 receives significant testing.