From 343c2f4dfbabb9cadacd524e07006b1adc9446c2 Mon Sep 17 00:00:00 2001 From: hcm Date: Thu, 8 Jan 2015 10:43:34 -0800 Subject: [PATCH] Adding user doc section and core files for new site - Updated QSGs with relative links to download page, removed outdated and googler-only iOS instructions. - Will add "contributing" page and update project roles link in next batch with developer section Preview link: http://skiadocs.com:8000/user/quick/android?cl=834353003 BUG=skia: Review URL: https://codereview.chromium.org/834353003 --- site/user/quick/android.md | 167 +++++++++++++++ site/user/quick/index.md | 3 + site/user/quick/ios.md | 104 ++++++++++ site/user/quick/macos.md | 69 +++++++ site/user/quick/nacl.md | 93 +++++++++ site/user/quick/windows.md | 96 +++++++++ site/user/sample/building.md | 320 +++++++++++++++++++++++++++++ site/user/sample/hello.md | 123 +++++++++++ site/user/sample/index.md | 2 + site/user/special/index.md | 3 + site/user/special/lua.md | 54 +++++ site/user/special/windows_angle.md | 32 +++ 12 files changed, 1066 insertions(+) create mode 100644 site/user/quick/android.md create mode 100644 site/user/quick/index.md create mode 100644 site/user/quick/ios.md create mode 100644 site/user/quick/macos.md create mode 100644 site/user/quick/nacl.md create mode 100644 site/user/quick/windows.md create mode 100644 site/user/sample/building.md create mode 100644 site/user/sample/hello.md create mode 100644 site/user/sample/index.md create mode 100644 site/user/special/index.md create mode 100644 site/user/special/lua.md create mode 100644 site/user/special/windows_angle.md diff --git a/site/user/quick/android.md b/site/user/quick/android.md new file mode 100644 index 0000000000..a73523b702 --- /dev/null +++ b/site/user/quick/android.md @@ -0,0 +1,167 @@ +Android +======= + +Prerequisites +------------- + +_Currently we only support building Skia for Android on a Linux or Mac host!_ + +The following libraries/utilities are required in addition to those needed for a standard skia checkout: + + * Apache Ant + * The Android SDK: http://developer.android.com/sdk/ + +~~~~ +$ sudo apt-get install ant git +~~~~ + +Check out the source code +------------------------- + +Follow the instructions [here](../download) for downloading the Skia source. Modify .gclient to add the following line to +the bottom, and then run gclient sync again: + + target_os = ["android"] + +Inside your Skia checkout, `platform_tools/android` contains the Android setup +scripts, Android specific dependencies, and the Android Sample App. + +Setup the Android SDK +--------------------- + +To finish setting up the Android SDK you need to download use the SDK to +download the appropriate API level. To do this simply go to the directory +where you installed the SDK and run the following commands + + # You may want to add this export to your shell's .bash_profile or .profile + export ANDROID_SDK_ROOT=/path/to/android/sdk + + $ ANDROID_SDK_ROOT/tools/android update sdk --no-ui --filter android-19 + +From here you will need to type 'y' to approve the license agreement and that +is all. You will then have downloaded the SDK for API level 19 (Android 4.4 +KitKat) which will be used to build the Skia SampleApp. You can download as +many other Android add-ons or APIs as you want, but you only are required to +have this one in order to complete the Skia build process. + +Setup Environment for Android +----------------------------- + +The Android build needs to set up some specific variables needed by both GYP +and Make. We make this setup easy for developers by encapsulating all the +details into a custom script that acts as a replacement for make. + +Custom Android Build Script +--------------------------- + +The android_ninja script is a wrapper for the ninja command (provided by +depot_tools) and is specifically designed to work with the Skia's build +system. To use the script you need to call it from Skia's trunk directory with +the -d option plus any of the options or arguments you would normally pass to +ninja (see descriptions of some of the other flags here). + + export ANDROID_SDK_ROOT=/path/to/android/sdk + export PATH=$PATH:/path/to/depot_tools + + cd skia + ./platform_tools/android/bin/android_ninja -d nexus_10 # or nexus_7, galaxy_nexus, etc... + +The -d option enables the build system to target the build to a specific +architecture such as MIPS (generic), x86 (generic) and ARM (generic and device +specific flavors for Nexus devices). This in turn allows Skia to take +advantage of specific device optimizations (e.g. NEON instructions). + +Generate build file from GYP +---------------------------- + +We use the open-source gyp tool to generate build files from our multiplatform +"gyp" files. While most other platforms enable you to regenerate these files +using `./gyp_skia` it is recommend that you do NOT do this for Android. Instead +you can rely on it being run automatically by android_ninja. + +Faster rebuilds +--------------- + +You can use ccache to improve the speed of rebuilding: + + # You may want to add this export to your shell's .bash_profile or .profile + export ANDROID_MAKE_CCACHE=[ccache] + +Build and run executables on the device +--------------------------------------- + +The build system packages the Skia executables as shared libraries. As such, +in order to run any executable on the device you must install the library and +a launcher executable on your device. To assist in this process there is a +script called `android_run_skia` that is located in the +`platform_tools/android/bin` directory. + +Run correctness tests +--------------------- + +First build the app and then run it on an attached device: + + ./platform_tools/android/bin/android_ninja [-d device_id] dm + ./platform_tools/android/bin/android_run_skia dm # uploads and runs the dm binary on the attached device + +Run performance tests +--------------------- + +Since nanobench tests performance, it usually makes more sense to run it in +Release mode. + + BUILDTYPE=Release ./platform_tools/android/bin/android_ninja [-d device_id] nanobench + + # uploads and runs the nanobench binary on the attached device + ./platform_tools/android/bin/android_run_skia --release nanobench + +If you pass nanobench SKP files, it will benchmark them too. + + ./platform_tools/android/bin/[linux/mac]/adb push ../skp # is dir on device + +Finally to run the executable there are two approaches. The simplest of the +two run the app on the device like you would do for gm or tests, however this +approach will also produce the noisiest results. + + # is file/dir on device + ./platform_tools/android/bin/android_run_skia --release nanobench --skps + +Build and run SampleApp +----------------------- + +The SampleApp on Android provides a simple UI for viewing sample slides and gm images. + + BUILDTYPE=Debug ./platform_tools/android/bin/android_ninja -d $TARGET_DEVICE + +Then, install the app onto the device: + + ./platform_tools/android/bin/android_install_apk + +Finally to run the application you must navigate to the Skia Samples +application using the application launcher on your device. + +Build tools +----------- + +The Android platform does not support skdiff at this time. + +Clean up all generated files +---------------------------- + + make clean + +Debugging on Android +-------------------- + +We support debugging on using a GDB wrapper script. The script loads the app +onto the device, starts a gdbserver instance with that app, and then enters a +GDB client shell on the host. Necessary symbol files are pulled from the +device and placed into a temporary folder. The script does not build the app - +you'll have to do that first. + + # you can include additional arguments in quotes (e.g. "dm --nopdf") + ./platform_tools/android/bin/android_gdb_exe dm + +When the gdb client is ready, insert a breakpoint, and continue to let the +program resume execution. + diff --git a/site/user/quick/index.md b/site/user/quick/index.md new file mode 100644 index 0000000000..0a349a43cd --- /dev/null +++ b/site/user/quick/index.md @@ -0,0 +1,3 @@ +Quick Start Guides +================== + diff --git a/site/user/quick/ios.md b/site/user/quick/ios.md new file mode 100644 index 0000000000..e060a28725 --- /dev/null +++ b/site/user/quick/ios.md @@ -0,0 +1,104 @@ +iOS +=== + +Prerequisites +------------- + +_These steps should closely follow building on Mac OS X. Those steps seem slightly out of date._ + +Build and run SampleApp in the XCode IDE +---------------------------------------- + +### XCode 4.5 + + +To build SampleApp on XCode 4.5 using the IDE these steps should work: + + GYP_DEFINES="skia_os='ios' skia_arch_type='arm' armv7=1 arm_neon=0" ./gyp_skia + xed out/gyp/SampleApp.xcodeproj # opens the SampleApp project in the IDE + +Note that if you run make at the command line the gyp\_skia script will rerun +and you'll lose the effect of the GYP\_DEFINES. To avoid this do: + + export GYP_DEFINES="skia_os='ios' skia_arch_type='arm' armv7=1 arm_neon=0" + +### XCode 3 + +Use GYP\_DEFINES to tell gyp\_skia how to build for iOS. Here's a bash shell +snippet that sets the world up to build SampleApp with XCode 3: + + function buildSampleApp() + { + sdkVersion="4.3" + if [[ "$1" == "sim" ]] ; then + export GYP_DEFINES="skia_os='ios' skia_arch_type='x86' \ + ios_sdk_dir='/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator' \ + ios_sdk_version='$sdkVersion'" + elif [[ "$1" == "iphone" ]] ; then + export GYP_DEFINES="skia_os='ios' skia_arch_type='arm' armv7='1' arm_neon='0' \ + ios_sdk_dir='/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS' \ + ios_sdk_version='$sdkVersion'" + elif [[ "$1" == "mac" ]] ; then + export GYP_DEFINES="" + else + echo "buildSampleApp expects 'sim', 'iphone', or 'mac'" + fi + if [[ "$1" == "sim" ]] || [[ "$1" == "iphone" ]] || [[ "$1" == "mac" ]] ; then + save=`pwd` + cd /chrome/nih/skia/trunk + echo "$GYP_DEFINES ./gyp_skia gyp/SampleApp.gyp" + ./gyp_skia gyp/SampleApp.gyp + cd $save + fi + if [[ "$1" == "sim" ]] ; then + setiossdk iphonesimulator$sdkVersion + elif [[ "$1" == "iphone" ]] ; then + setiossdk iphoneos$sdkVersion + fi + } + +The script function setiossdk called by buildSampleApp is a +not-completely-working hackery. When gyp builds an iOS-targeted project, it is +hard-coded for the iOS simulator. To point the project at either the iOS +simulator, or an iOS device, the project file must be opened to create a +custom pbxuser file. + +This is accomplished by: + + function setiossdk() + { + osascript -e 'tell app "Xcode" to quit' + osascript -e 'repeat until appIsRunning("Xcode") is false' -e \ + 'do shell script "sleep 1"' -e 'end repeat' + save=`pwd` + skia + cd out/gyp + for project in *.xcodeproj; do + open $project + done + osascript -e 'tell app "Xcode" to quit' + osascript -e 'repeat until appIsRunning("Xcode") is false' -e \ + 'do shell script "sleep 1"' -e 'end repeat' + for project in *.xcodeproj; do + lsave=`pwd` + cd $project + filename=`eval whoami`.pbxuser + while [[ ! -s $filename ]] ; do + sleep 1 + echo -n "." + done + sed -e '/activeSDKPreference/ d' <$filename | sed -e '/activeTarget/ i\ + \ activeSDKPreference = '$1';' >x$filename + if [[ -s x$filename ]] ; then + mv x$filename $filename + else + echo "mv x$filename $project/$filename failed" + fi + cd $lsave + done + open SampleApp.xcodeproj + cd $save + } + +In particular, the calls to osascript to wait for Xcode to quit use faulty syntax. + diff --git a/site/user/quick/macos.md b/site/user/quick/macos.md new file mode 100644 index 0000000000..ed74551d8b --- /dev/null +++ b/site/user/quick/macos.md @@ -0,0 +1,69 @@ +Mac OS X +======== + +Prerequisites +------------- + +Make sure the following have been installed: + + * XCode (Apple's development environment): required + * publicly available at http://developer.apple.com/xcode/ + * add the optional Unix Tools to the install so you get the make command line tool. + * Chromium depot_tools: required to download the source and dependencies + * http://www.chromium.org/developers/how-tos/depottools + +Check out the source code +------------------------- + +See the instructions [here](../download). + +Generate XCode projects +----------------------- + +We use the open-source gyp tool to generate XCode projects (and analogous +build scripts on other platforms) from our multiplatform "gyp" files. + +Before building, make sure that gyp knows to create an XCode project or ninja +build files. If you leave GYP_GENERATORS undefined it will assume the +following default: + + GYP_GENERATORS="ninja,xcode" + +Or you can set it to `ninja` or `xcode` alone, if you like. + +You can then generate the Xcode projects and ninja build files by running: + + ./gyp_skia + +Build and run tests from the command line +----------------------------------------- + + ninja -C out/Debug dm + out/Debug/dm + +The usual mode you want for testing is Debug mode (SK_DEBUG is defined, and +debug symbols are included in the binary). If you would like to build the +Release version instead: + + ninja -C out/Release dm + out/Release/dm + +Build and run nanobench (performance tests) +------------------------------------------- + +In this case, we will build with the "Release" configuration, since we are running performance tests. + + ninja -C out/Release nanobench + out/Release/nanobench [ --skps path/to/*.skp ] + +Build and run SampleApp in the XCode IDE +---------------------------------------- + + * Run gyp_skia as described above. + * In the Finder, navigate to $SKIA_INSTALLDIR/trunk/out/gyp + * Double-click SampleApp.xcodeproj ; this will launch XCode and open the SampleApp project + * Click the “Build and Run” button in the top toolbar + * Once the build is complete, you should see a window with lots of shaded text examples. To move through the sample app, use the following keypresses: + * right- and left-arrow keys: cycle through different test pages + * 'D' key: cycle through rendering methods for each test page + * other keys are defined in SampleApp.cpp’s SampleWindow::onHandleKey() and SampleWindow::onHandleChar() methods diff --git a/site/user/quick/nacl.md b/site/user/quick/nacl.md new file mode 100644 index 0000000000..2d88d8878e --- /dev/null +++ b/site/user/quick/nacl.md @@ -0,0 +1,93 @@ +NaCl (Experimental) +=================== + +Important Notes +--------------- + + * This process has only been verified to work on Linux + * Skia for NaCl is new and currently under development. Therefore, some features are not (yet) supported: + * GPU backend + * Fonts - Currently, NaCl has no way to access system fonts. This means + that text drawn in Skia will not display. A Pepper font API is in the + works and should be available in the near future, but for now your best + bet is to either package font data with your nexe or to send font data + from javascript to your plugin at runtime. Note that this will be the + case with any graphics library in NaCl until the font API is finished. + +Prerequisites +------------- + +Execute the following commands in whatever directory you want to hold the NaCl SDK directory: + + wget http://storage.googleapis.com/nativeclient-mirror/nacl/nacl_sdk/nacl_sdk.zip + unzip nacl_sdk.zip + rm nacl_sdk.zip + nacl_sdk/naclsdk update pepper_32 + export NACL_SDK_ROOT=/path/to/nacl_sdk + +Check out the Skia source +------------------------- + +We use the "gclient" script (part of the depot_tools toolkit) to manage the +Skia source code. Follow the instructions at +http://www.chromium.org/developers/how-tos/depottools to get the gclient +script from depot_tools. + +Instead of checking out trunk directly you will use gclient to checkout the +nacl directory, which will automatically pull the trunk directory for you. +Execute the following commands in whatever directory you want to be the root +for your Skia on NaCl development: + + gclient config https://skia.googlesource.com/skia.git + gclient sync + +Building the Skia libraries for NaCl +------------------------------------ + +The nacl_make script is used to compile Skia targets for NaCl. It sets the +appropriate environment variables, calls GYP to generate makefiles, and runs +Make to build both 32 and 64-bit targets as required by NaCl. To build the +Skia libraries, run the following from the trunk directory: + + platform_tools/nacl/nacl_make skia_lib + +This will result in a set of static libraries being built into the out/nacl32 +and out/nacl64 directories. You can use these libraries in external NaCl +apps. + +Building and running Skia's Apps in NaCl (Experimental) +------------------------------------------------------- + +It is possible to run some of Skia's console apps in the browser. + +### Skia Unit Tests + +Build Skia tests from the trunk directory: + + platform_tools/nacl/bin/nacl_make tests + +This will build the tests executable. We include a tiny HTTP server (borrowed +from the NaCl SDK) in order to run the apps: + + cd platform_tools/nacl + ./httpd.py + +The HTTP server runs on port 5103 by default. In Chrome, navigate to +`http://localhost:5103/` and click on the link for "unit tests." After the +module downloads, you should see the tests begin to run. + +### Sample App + +The sample app relies on the GPU backend. Therefore, it will compile but will not yet run. + + platform_tools/nacl/bin/nacl_make SampleApp + +You can access the sample app at http://localhost:5103/SampleApp. + +### Debugger + +The debugger is currently in a partially-working state: + + platform_tools/nacl/bin/nacl_make debugger + +You can access it at http://localhost:5103/debugger. diff --git a/site/user/quick/windows.md b/site/user/quick/windows.md new file mode 100644 index 0000000000..0607857b9d --- /dev/null +++ b/site/user/quick/windows.md @@ -0,0 +1,96 @@ +Windows +======= + +Prerequisites +------------- + +Make sure the following have been installed: + + * Visual C++ 2013 Express or later, available for free + * http://www.visualstudio.com/downloads/download-visual-studio-vs#d-express-windows-8 + + * Chromium depot_tools + * http://www.chromium.org/developers/how-tos/depottools + * git + * Either use the mysygit installed by depot_tools + * Or install msys git: http://msysgit.github.io/ yourself + * Python 2.7.x (if you're not planning to use cygwin) + * available for free download at http://www.python.org/download/releases/ + * make sure the installer changes your %PATH% environment variable to include the directory with the "python.exe" binary + * Cygwin (optional, but useful if you want to use git) + * Download from http://cygwin.org/setup.exe + * use any mirror you like; http://lug.mtu.edu works well + * Cygwin installs a minimum of options. Add these packages if they aren't already selected: + * Devel git + * Devel subversion + * Editors vim + * to fix arrows in insert, copy /usr/share/vim/vim73/vimrc_example.vim to ~/.vimrc + * Net ca-certificates + * Python python + * Utils patch + * Utils util-linux + * set the windows envionment variable CYGWIN to nodosfilewarning + +Check out the source code +------------------------- + +see https://sites.google.com/site/skiadocs/developer-documentation/contributing-code/downloading + +Generate Visual Studio projects +------------------------------- + +We use the open-source gyp tool to generate Visual Studio projects (and +analogous build scripts on other platforms) from our multi-platform "gyp" +files. + +You can generate the Visual Studio projects by running gyp_skia, as follows: + + cd %SKIA_CHECKOUT_DIR% + python gyp_skia + +This will produce Visual Studio projects in the `%SKIA_CHECKOUT_DIR%\out` directory. + +Build and run tests from the command line +----------------------------------------- + + ninja -C out\Debug dm + out\Debug\dm + +Normally you should run tests in Debug mode (SK_DEBUG is defined, and debug +symbols are included in the binary). If you would like to build the Release +version instead: + + ninja -C out\Release dm + out\Release\dm + +Build and run tests in the Visual Studio IDE +-------------------------------------------- + + * Generate the Visual Studio project files by running gyp_skia as described above + * Open a File Explorer window pointing at the %SKIA_CHECKOUT_DIR%\out\gyp directory + * Double-click on dm.sln to start Visual Studio and load the project + * When Visual Studio starts, you may see an error dialog stating that "One or more projects in the solution were not loaded correctly"... but there's probably nothing to worry about. + * In the "Solution Explorer" window, right-click on the "dm" project and select "Set as StartUp Project". + * In the "Debug" menu, click on "Start Debugging" (or just press F5). If you get a dialog saying that the project is out of date, click on "Yes" to rebuild it. + * Once the build is complete, you should see console output from the tests in the "Output" window at lower right. + +Build and run SampleApp in Visual Studio +---------------------------------------- + + * Generate the Visual Studio project files by running gyp_skia as described above + * Open a File Explorer window pointing at the %SKIA_INSTALLDIR%\trunk\out\gyp directory + * Double-click on SampleApp.sln + * When Visual Studio starts, you may see an error dialog stating that "One or more projects in the solution were not loaded correctly"... but there's probably nothing to worry about. + * In the "Debug" menu, click on "Start Debugging" (or just press F5). If you get a dialog saying that the project is out of date, click on "Yes" to rebuild it. + * Once the build is complete, you should see a window with various example graphics. To move through the sample app, use the following keypresses: + * right-arrow key: cycle through different test pages + * left-arrow key: cycle through rendering methods for each test page + * other keys are defined in SampleApp.cpp’s SampleWindow::onHandleKey() and SampleWindow::onHandleChar() methods + +Build and run nanobench (performance testbench) from the command line +--------------------------------------------------------------------- + +Since nanobench tests performance, it usually makes more sense to run it in Release mode. + + ninja -C out\Release nanobench + out\Release\nanobench diff --git a/site/user/sample/building.md b/site/user/sample/building.md new file mode 100644 index 0000000000..92865d17b8 --- /dev/null +++ b/site/user/sample/building.md @@ -0,0 +1,320 @@ +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.googlecode.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 googlecode 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.googlecode.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("googlecode_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 = new SkString(); + 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("googlecode_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. + diff --git a/site/user/sample/hello.md b/site/user/sample/hello.md new file mode 100644 index 0000000000..324ff6b240 --- /dev/null +++ b/site/user/sample/hello.md @@ -0,0 +1,123 @@ +Creating a Skia "Hello World!" +============================== + +This tutorial will guide you through the steps to create a Hello World Desktop +application in Skia. + +Who this tutorial is for: +------------------------- + +This will be useful to you if you want to create a window that can receive +events and to which you can draw with Skia. + +Step 1: Check out and build Skia +-------------------------------- + +Follow the instructions for: Linux, Mac OS X or Windows. The framework that we +will be using does not currently support other platforms. + +Once you have a working development environment, we can move on to the next step. + +Step 2: Build the included HelloSkia Example +-------------------------------------------- + +We will be using the "SkiaExamples" framework. You can find it in the +experimental/SkiaExamples directory. There is an included HelloWorld example, +and we will start by building it before we go ahead and create our own. + +### On Mac OS X + +Run `GYP_GENERATORS="ninja" ./gyp_skia` +This will generate a ninja target, and `ninja -C out/Debug SkiaExamples` will create `SkiaExamples.app` + +### On Linux: +Run `GYP_GENERATORS="ninja" ./gyp_skia` + +Build the SkiaExamples target: + + ninja -C out/Release SkiaExamples + +The SkiaExamples binary should be in `out/Release/SkiaExamples` + +### On Windows + +Run `./gyp_skia` + +There should be a Visual Studio project `out/gyp/SkiaExamples.vcproj` with +which you can build the SkiaExamples binary. + +### Run the SkiaExamples. + +You should see a window open displaying rotating text and some geometry. + +Step 3: Create your own Sample +------------------------------ + +Create a file `experimental/SkiaExamples/Tutorial.cpp` within the Skia tree. Copy the following code: + +~~~~ + +#include "SkExample.h" +#include "SkDevice.h" + +class HelloTutorial : public SkExample { + public: + HelloTutorial(SkExampleWindow* window) + : SkExample(window) + { + fName = "Tutorial"; // This is how Skia will find your example. + + fWindow->setupBackend(SkExampleWindow::kGPU_DeviceType); + // Another option is the CPU backend: fWindow->setupBackend(kRaster_DeviceType); + } + + protected: + virtual void draw(SkCanvas* canvas) SK_OVERRIDE { + // Clear background + canvas->drawColor(SK_ColorWHITE); + + SkPaint paint; + // Draw a message with a nice black paint. + paint.setFlags(SkPaint::kAntiAlias_Flag); + paint.setColor(SK_ColorBLACK); + paint.setTextSize(SkIntToScalar(20)); + + static const char message[] = "Hello World!"; + + // Translate and draw the text: + canvas->save(); + canvas->translate(SkIntToScalar(50), SkIntToScalar(100)); + canvas->drawText(message, strlen(message), SkIntToScalar(0), SkIntToScalar(0), paint); + canvas->restore(); + + // If you ever want to do animation. Use the inval method to trigger a redraw. + this->fWindow->inval(NULL); + } +}; + +static SkExample* MyFactory(SkExampleWindow* window) { + return new HelloTutorial(window); +} +static SkExample::Registry registry(MyFactory); + +~~~~ + + +Step 4: Compile and run SkiaExamples with your Sample +----------------------------------------------------- + +Here is what you have to do to compile your example. There will be +functionality to make this easier, but for now, this is what you have to do: + * Open `gyp/experimental.gyp` and look for the `SkiaExamples` target. + * In the 'sources' section of the SkiaExampels target, add + `../experimental/SkiaExamples/Tutorial.cpp` to the list of sources. + * Repeat Step 2 to update our gyp targets and build our example. + * Run the SkiaExamples, specifying the name of our new example: `$> out/Release/SkiaExamples --match Tutorial` + +Step 5: How to iterate through multiple examples +------------------------------------------------ + +If you did not specify an example with the --match flag, or if your match +string matches more than one example, you can use the *n* key to iterate +through all of the examples registered. + diff --git a/site/user/sample/index.md b/site/user/sample/index.md new file mode 100644 index 0000000000..ea1b3575dd --- /dev/null +++ b/site/user/sample/index.md @@ -0,0 +1,2 @@ +Samples and Tutorials +===================== diff --git a/site/user/special/index.md b/site/user/special/index.md new file mode 100644 index 0000000000..a38092a573 --- /dev/null +++ b/site/user/special/index.md @@ -0,0 +1,3 @@ +Specialized Builds +================== + diff --git a/site/user/special/lua.md b/site/user/special/lua.md new file mode 100644 index 0000000000..448d8b9b13 --- /dev/null +++ b/site/user/special/lua.md @@ -0,0 +1,54 @@ +Skia Lua Bindings +================= + +**Warning: The following has only been tested on Linux, but it will likely +work for any Unix.** + +Prerequisites +------------- + +This assumes one already has Skia building normally. If not, refer to the +quick start guides. In addition to that, you will need Lua 5.2 installed on +your system in order to use the bindings. + +Building lua requires the readline development library. If missing this can be installed (on Ubuntu) by executing: + + * `apt-cache search libreadline` to see the available libreadline libraries + * `sudo apt-get install libreadline6 libreadline6-dev` to actually install the libraries + +Build +----- + +The build process starts the same way as described in the quick starts, but +before using gyp or make, do this instead: + + $ export GYP_DEFINES="skia_shared_lib=1" + $ make tools + +This tells Skia to build as a shared library, which enables a build of another shared library called 'skia.so' that exposes Skia bindings to Lua. + +Try It Out +---------- + +Once the build is complete, use the same terminal: + + $ cd out/Debug/ + $ lua + + Lua 5.2.0 Copyright (C) 1994-2011 Lua.org, PUC-Rio + > require 'skia' + > paint = Sk.newPaint() + > paint:setColor{a=1, r=1, g=0, b=0} + > doc = Sk.newDocumentPDF('test.pdf') + > canvas = doc:beginPage(72*8.5, 72*11) + > canvas:drawText('Hello Lua', 300, 300, paint) + > doc:close() + +The key part to loading the bindings is `require 'skia'` which tells lua to look +for 'skia.so' in the current directory (among many others) and provides the +bindings. 'skia.so' in turn will load 'libskia.so' from the current directory or +in our case the lib.target directory. 'libskia.so' is what contains the native +skia code. The script shown above uses skia to draw Hello Lua in red text onto +a pdf that will be outputted into the current folder as 'test.pdf'. Go ahead and +open 'test.pdf' to confirm that everything is working. + diff --git a/site/user/special/windows_angle.md b/site/user/special/windows_angle.md new file mode 100644 index 0000000000..abd73ad58c --- /dev/null +++ b/site/user/special/windows_angle.md @@ -0,0 +1,32 @@ +Using ANGLE on Windows +====================== + +Introduction +------------ + +ANGLE converts OpenGL ES 2.0 calls to DirectX 9 calls. These instructions +document how to use ANGLE instead of the native OpenGL backend on Windows. + +Details +------- + +Angle is now downloaded as a part of Skia according to the `DEPS` file. + +Add `skia_angle=1` to your `GYP_DEFINES` environment variable. + +Run: + + python gyp_skia + +Remember +-------- + +In SampleApp you will need to use the 'D' key to get to the ANGLE backend unless you enable the `DEFAULT_TO_ANGLE` #define in `SampleApp.cpp`. + + * Use “--angle” to enable ANGLE in gm. + + * Use “--config ANGLE” to use ANGLE in bench. + + * Use "--config angle" to use ANGLE in bench_pictures and render_pictures. + +ANGLE will automatically be compiled into the GLInterfaceValidation test. -- 2.34.1