+++ /dev/null
-Building with Skia Tutorial
-===========================
-
-dsinclair@chromium.org
-
-
-This document describes the steps used to create an application that uses Skia. The assumptions are that you're using:
-
- * [git](http://git-scm.com)
- * [gclient](https://code.google.com/p/gclient/)
- * [gyp](https://code.google.com/p/gyp/)
- * [ninja](http://martine.github.io/ninja/)
-
-I'm going to describe up to the point where we can build a simple application that prints out an SkPaint.
-
-Overview
---------
-
- 1. Create remote repository.
- 1. Configure and sync using gclient.
- 1. Create DEPS file to pull in third party repositories.
- 1. Setup gitignore for directories pulled in from DEPS.
- 1. Configure GYP.
- 1. Setup GYP auto-run when gclient sync is executed.
-
-gclient setup
--------------
-The first step is to setup a remote git repo, take your pick of provider. In
-my case, the repo is called UsingSkia and lives on
-[bitbucket](https://bitbucket.org).
-
-With the remote repo created, we create a .gclient configuration file. The
-gclient config command will write the file for us:
-
- $ gclient config --name=src https://bitbucket.org/dj2/usingskia.git
-
-This will create the following:
-
- solutions = [
- { "name" : "src",
- "url" : "https://bitbucket.org/dj2/usingskia.git",
- "deps_file" : "DEPS",
- "managed" : True,
- "custom_deps" : {
- },
- "safesync_url": "",
- },
- ]
- cache_dir = None
-
-The name that we configured is the directory in which the repo will be checked
-out. This is done by running gclient sync. There is a bit of magic that
-gclient does around the url to determine if the repo is SVN or GIT. I've found
-the use of ssh:// and the .git on the end seem to work to get the right SCM
-type.
-
- $ gclient sync
-
-This should execute a bunch of commands (and, in this case, may end with an
-error because the repo was empty. That seems to be fine.) When finished, you
-should have a src directory with your git repository checked out.
-
-DEPS
-----
-
-With the repo created we can go ahead and create our src/DEPS file. The DEPS
-file is used by gclient to checkout the dependent repositories of our
-application. In this case, the Skia repository.
-
-Create a src/DEPS file with the following:
-
-~~~~
-
- vars = {
- "skia_revision": "a6a8f00a3977e71dbce9da50a32c5e9a51c49285",
- }
-
- deps = {
- "src/third_party/skia/":
- "http://skia.googlesource.com/skia.git@" + Var("skia_revision"),
- }
-
-~~~~
-
-There are two sections to the `DEPS` file at the moment, `vars` and `deps`.
-The `vars` sections defines variables we can use later in the file with the
-`Var()` accessor. In this case, we define our root directory, a shorter name
-for any googlesource repositories and a specific revision of Skia that we're
-going to use. I've pinned to a specific version to insulate the application
-from changes in the Skia tree. This lets us know that when someone checks out
-the repo they'll be using the same version of Skia that we've built and tested
-against.
-
-The `deps` section defines our dependencies. Currently we have one dependency
-which we're going to checkout into the `src/third_party/skia` directory.
-
-Once the deps file is created, commit and push it to the remote repository.
-Once done, we can use gclient to checkout our dependencies.
-
- $ gclient sync
-
-This should output a whole bunch of lines about files that are being added to
-your project. This may also be a good time to create a `.gitignore` file. You
-don't want to check the `third_party/skia directory` into your repository as
-it's being managed by gclient.
-
-Now, we've run into a problem. Skia itself has a `DEPS` file which defines the
-`third_party` libraries it needs to build. None of those dependencies are being
-checked out so Skia will fail to build.
-
-The way I found around that is to add a second solution to the `.gclient`
-file. This solution tells gclient about Skia and will pull in the needed
-dependencies. I edited my `.gclient` file (created by the `gclient config`
-command above) to look as follows:
-
- solutions = [
- { "name" : "src",
- "url" : "https://bitbucket.org/dj2/usingskia.git",
- "deps_file" : "DEPS",
- "managed" : True,
- "custom_deps" : {
- },
- "safesync_url": "",
- },
- { "name" : "src/third_party/skia",
- "url" : "http://skia.googlesource.com/skia.git@a6a8f00a3977e71dbce9da50a32c5e9a51c49285",
- "deps_file" : "DEPS",
- "managed" : True,
- "custom_deps" : {
- },
- "safesync_url": "",
- },
- ]
- cache_dir = None
-
-This is a little annoying at the moment since I've duplicated the repository
-revision number in the `.gclient` file. I'm hoping to find a way to do this
-through the `DEPS` file, but until then, this seems to work.
-
-With that done, re-run `gclient sync` and you should see a whole lot more
-repositories being checked out. The
-`src/third_party/skia/third_party/externals` directory should now be
-populated.
-
-GYP
----
-
-The final piece of infrastructure we need to set up is GYP. GYP is a build
-system generator, in this project we're going to have it build ninja
-configuration files.
-
-First, we need to add GYP to our project. We'll do that by adding a new entry
-to the deps section of the `DEPS` file.
-
- "src/tools/gyp":
- (Var("googlesource_url") % "gyp") + "/trunk@1700",
-
-As you can see, I'm going to put the library into `src/tools/gyp` and checkout
-revision 1700 (note, the revision used here, 1700, was the head revision at
-the time the `DEPS` file was written. You're probably safe to use the
-tip-of-tree revision in your `DEPS` file). A quick `gclient sync` and we
-should have everything checked out.
-
-In order to run GYP we'll create a wrapper script. I've called this
-`src/build/gyp_using_skia`.
-
-~~~~
-#!/usr/bin/python
-import os
-import sys
-
-script_dir = os.path.dirname(__file__)
-using_skia_src = os.path.abspath(os.path.join(script_dir, os.pardir))
-
-sys.path.insert(0, os.path.join(using_skia_src, 'tools', 'gyp', 'pylib'))
-import gyp
-
-if __name__ == '__main__':
- args = sys.argv[1:]
-
- if not os.environ.get('GYP_GENERATORS'):
- os.environ['GYP_GENERATORS'] = 'ninja'
-
- args.append('--check')
- args.append('-I%s/third_party/skia/gyp/common.gypi' % using_skia_src)
-
- args.append(os.path.join(script_dir, '..', 'using_skia.gyp'))
-
- print 'Updating projects from gyp files...'
- sys.stdout.flush()
-
- sys.exit(gyp.main(args))
-~~~~
-
-Most of this is just setup code. The two interesting bits are:
-
- 1. `args.append('-I%s/third_party/skia/gyp/common.gypi' % using_skia_src)`
- 1. `args.append(os.path.join(script_dir, '..', 'using_skia.gyp'))`
-
-In the case of 1, we're telling GYP to include (-I) the
-`src/third_party/skia/gyp/common.gypi` file which will define necessary
-variables for Skia to compile. In the case of 2, we're telling GYP that the
-main configuration file for our application is `src/using_skia.gyp`.
-
-The `src/using_skia.gyp` file is as follows:
-
-~~~~
-{
- 'targets': [
- {
- 'configurations': {
- 'Debug': { },
- 'Release': { }
- },
- 'target_name': 'using_skia',
- 'type': 'executable',
- 'dependencies': [
- 'third_party/skia/gyp/skia_lib.gyp:skia_lib'
- ],
- 'include_dirs': [
- 'third_party/skia/include/config',
- 'third_party/skia/include/core',
- ],
- 'sources': [
- 'app/main.cpp'
- ],
- 'ldflags': [
- '-lskia', '-stdlib=libc++', '-std=c++11'
- ],
- 'cflags': [
- '-Werror', '-W', '-Wall', '-Wextra', '-Wno-unused-parameter', '-g', '-O0'
- ]
- }
- ]
-}
-~~~~
-
-There is a lot going on in there, I'll touch on some of the highlights. The
-`configurations` section allows us to have different build flags for our `Debug`
-and `Release` build (in this case they're the same, but I wanted to define
-them.) The `target_name` defines the name of the build target which we'll
-provide to ninja. It will also be the name of the executable that we build.
-
-The dependencies section lists our build dependencies. These will be built
-before our sources are built. In this case, we depend on the `skia_lib` target
-inside `third_party/skia/gyp/skia_lib.gyp`.
-
-The include_dirs will be added to the include path when our files are built.
-We need to reference code in the config and core directories of Skia.
-
-`sources`, `ldflags` and `cflags` should be obvious.
-
-Our application is defined in `src/app/main.cpp` as:
-
-~~~~
-#include "SkPaint.h"
-#include "SkString.h"
-
-int main(int argc, char** argv) {
- SkPaint paint;
- paint.setColor(SK_ColorRED);
-
- SkString str;
- paint.toString(&str);
-
- fprintf(stdout, "%s\n", str.c_str());
-
- return 0;
-}
-~~~~
-
-We're just printing out an SkPaint to show that everything is linking correctly.
-
-Now, we can run:
-
- $ ./build/gyp_using_skia
-
-And, we get an error. Turns out, Skia is looking for a `find\_mac\_sdk.py` file in
-a relative tools directory which doesn't exist. Luckily, that's easy to fix
-with another entry in our DEPS file.
-
- "src/tools/":
- File((Var("googlesource_url") % "skia") + "/trunk/tools/find_mac_sdk.py@" +
- Var("skia_revision")),
-
-Here we using the `File()` function of `gclient` to specify that we're checking
-out an individual file. Running `gclient sync` should pull the necessary file
-into `src/tools`.
-
-With that, running `build/gyp\_using\_skia` should complete successfully. You
-should now have an `out/` directory with a `Debug/` and `Release/` directory inside.
-These correspond to the configurations we specified in `using\_skia.gyp`.
-
-With all that out of the way, if you run:
-
- $ ninja -C out/Debug using_skia
-
-The build should execute and you'll end up with an `out/Debug/using\_skia` which
-when executed, prints out our SkPaint entry.
-
-Autorun GYP
------------
-
-One last thing, having to run `build/gyp\_using\_skia` after each sync is a bit of
-a pain. We can fix that by adding a `hooks` section to our `DEPS` file. The `hooks`
-section lets you list a set of hooks to execute after `gclient` has finished the
-sync.
-
- hooks = [
- {
- # A change to a .gyp, .gypi or to GYP itself should run the generator.
- "name": "gyp",
- "pattern": ".",
- "action": ["python", "src/build/gyp_using_skia"]
- }
- ]
-
-Adding the above to the end of DEPS and running gclient sync should show the
-GYP files being updated at the end of the sync procedure.
projects / platform / upstream / libSkiaSharp.git / commitdiff