Safe Rust bindings for the Skia Graphics Library.
Skia Submodule Status: chrome/m128 (upstream changes, our changes).
This project provides up to date safe bindings that bridge idiomatic Rust with Skia's C++ API on desktop and mobile platforms, including GPU rendering backends for Vulkan, Metal, OpenGL, and Direct3D.
Because we can't build on docs.rs, the cargo doc
output for skia-safe is manually created and uploaded to rust-skia.github.io.
We (slowly) add more documentation by converting Skia's Doxygen comments to Rust.
A prerelease crate is available from crates.io and invoking
cargo add skia-safe
in your project's folder should get you started. And you might want to take a look at the gl-window example if you plan to render to a window.
On Linux you may run into trouble when OpenSSL libraries are missing. On Debian and Ubuntu they can be installed with:
sudo apt-get install pkg-config libssl-dev
For other platforms, more information is available at the OpenSSL crate documentation.
Because building Skia takes a lot of time and needs tools that may be missing, the skia-bindings crate's build.rs
attempts to download prebuilt binaries from the skia-binaries repository using the curl
command line tool.
Platform | Binaries |
---|---|
Windows | x86_64-pc-windows-msvc |
Linux Ubuntu 16+ CentOS 7, 8 |
x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu |
macOS | x86_64-apple-darwin aarch64-apple-darwin |
Android | aarch64-linux-android x86_64-linux-android |
iOS | aarch64-apple-ios x86_64-apple-ios |
WebAssembly | wasm32-unknown-emscripten |
The supported wrappers, Skia codecs, and additional Skia features are documented in the skia-safe package's readme. Prebuilt binaries are available for most feature combinations.
If the target platform or feature configuration is not available as a prebuilt binary, skia-bindings' build.rs
will try to build Skia and generate the Rust bindings.
To prepare for that, LLVM and Python 3 are needed:
LLVM
We recommend the version that comes preinstalled with your platform, or, if not available, the latest official LLVM release. To see which version of LLVM/Clang is installed on your system, use clang --version
.
Python 3
The build script probes for python --version
and python3 --version
and uses the first one that looks like a version 3 executable for building Skia.
-
Install the Command Line Tools for Xcode with
xcode-select --install
or download and install the Command Line Tools for Xcode.
-
macOS Mojave only: install the SDK headers:
sudo open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
If not installed, the Skia build may fail to build
SkJpegUtility.cpp
and the binding generation will fail with'TargetConditionals.h' file not found
. Also note that the Command Line Tools and SDK headers should be reinstalled after an update of XCode. -
As an alternative to Apple's XCode LLVM, install LLVM via
brew install llvm
orbrew install llvm
and then setPATH
,CPPFLAGS
, andLDFLAGS
like instructed.If the environment variables are not set, bindgen will most likely use the wrong
libclang.dylib
and cause confusing compilation errors (see #228).
-
Have the latest versions of
git
and Rust ready. -
Install Visual Studio 2022 Build Tools or one of the other IDE editions. If you installed the IDE, make sure that the Desktop Development with C++ workload is installed.
-
Install the latest LLVM distribution.
If the environment variable
LLVM_HOME
is not defined, the build script will look for LLVM installations located atC:\Program Files\LLVM\
,C:\LLVM\
, and%USERPROFILE%\scoop\apps\llvm\current\
. -
- Install Python 3 with
pacman -S python
.
- Install Python 3 with
-
Windows Shell (
Cmd.exe
):- Download and install Python 3 from python.org.
-
Install and select the MSVC toolchain:
rustup default stable-msvc
- LLVM/Clang should be available already, if not, install the latest version.
- If OpenGL libraries are missing, install the drivers for you graphics card, or a mesa package like
libgl1-mesa-dev
. - For X11, build with feature
x11
. - For Wayland, install
libwayland-dev
and build with thewayland
feature.
-
Install the following packages:
sudo yum install gcc openssl-devel libX11-devel python3 fontconfig-devel mesa-libGL-devel
-
Install the following packages:
sudo yum install gcc openssl-devel libX11-devel python3 clang fontconfig-devel mesa-libGL-devel
-
Set
/usr/bin/python3
as the defaultpython
command:sudo alternatives --set python /usr/bin/python3
Cross compilation to Android is supported for targeting 64 bit ARM and Intel x86 architectures (aarch64
and x86_64
) for API Level 26 (Oreo, Android 8):
We recommend to use cargo apk, but if that does not work for you, following are some instructions on how we build Android targets with GitHub Actions:
For example, to compile for aarch64
:
- Install the Rust target:
rustup target install aarch64-linux-android
- Download the r26d NDK (or newer) for your host architecture and unzip it.
- Compile your project for the
aarch64-linux-android
target:
On macOS:
export ANDROID_NDK=:path-to-android-ndk-r26d
export PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin
export CC_aarch64_linux_android=aarch64-linux-android26-clang
export CXX_aarch64_linux_android=aarch64-linux-android26-clang++
export AR_aarch64_linux_android=llvm-ar
export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang
cargo build -vv --target aarch64-linux-android
We don't support Apple's Clang to build for Android on macOS, so you need to install LLVM and set the PATH
like instructed.
On Linux:
export ANDROID_NDK=:path-to-android-ndk-r26d
export PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin
export CC_aarch64_linux_android=aarch64-linux-android26-clang
export CXX_aarch64_linux_android=aarch64-linux-android26-clang++
export AR_aarch64_linux_android=llvm-ar
export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang
cargo build -vv --target aarch64-linux-android
On Windows the Android NDK Clang executable must be invoked through .cmd
scripts:
export ANDROID_NDK=:path-to-android-ndk-r26d
export PATH=$PATH:$ANDROID_NDK/toolchains/llvm/prebuilt/windows-x86_64/bin
export CC_aarch64_linux_android=aarch64-linux-android26-clang.cmd
export CXX_aarch64_linux_android=aarch64-linux-android26-clang++.cmd
export AR_aarch64_linux_android=llvm-ar
export CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER=aarch64-linux-android26-clang.cmd
cargo build -vv --target aarch64-linux-android
Notes:
- At the time of this writing, the Rust compiler will automatically add a
-lgcc
argument to the linker, which results in a linker error, because newer NDKs do not containlibgcc.a
anymore. To fix this, we created a workaround and copylibunwind.a
over tolibgcc.a
. Cargo apk does something similar. - The
CARGO_TARGET_${TARGET}_LINKER
environment variable name needs to be all uppercase. - In some older shells (for example macOS High Sierra), environment variable replacement can not be used when the variable was defined on the same line. Therefore the
ANDROID_NDK
variable must be defined before it's used in thePATH
variable. - Rebuilding skia-bindings with a different target may cause linker errors, in that case
touch skia-bindings/build.rs
will force a rebuild (#10).
Compilation to iOS is supported on macOS targeting the iOS simulator (--target x86_64-apple-ios
) and 64 bit ARM devices (--target aarch64-apple-ios
). The ARM64e architecture is not supported yet.
Install emscripten
version 3.1.57 or superior and make sure that llvm / clang 16+ is installed. In the examples below, we assume
emsdk
version 3.1.57
was installed with asdf.
Build with the wasm32-unknown-emscripten
target (wasm32-unknown-unknown
is
unsupported because it is fundamentally incompatible with linking C code:
export EMSDK=~/.asdf/installs/emsdk/3.1.57
export EMCC_CFLAGS="-s ERROR_ON_UNDEFINED_SYMBOLS=0"
cargo build --target wasm32-unknown-emscripten
The EMSDK
environment variable must be set to the root of your emscripten
SDK.
In EMCC_CFLAGS
, -s ERROR_ON_UNDEFINED_SYMBOLS
is a
workaround to build with
emscripten > 2.0.9
.
If you want to enable WebGL, you will also have to set MAX_WEBGL_VERSION=2
:
export EMSDK=~/.asdf/installs/emsdk/3.1.57
export EMCC_CFLAGS="-s ERROR_ON_UNDEFINED_SYMBOLS=0 -s MAX_WEBGL_VERSION=2"
cargo build --target wasm32-unknown-emscripten --features gl
On MacOS there is a problem with the OS version of ar
so you will have to install the GNU version from homebrew:
brew install binutils
Then prepend binutils
path for the build. The path depends on your CPU
architecture, and can be retrieved with brew info binutils
. Here is an
example for Apple silicon:
export EMSDK=~/.asdf/installs/emsdk/3.1.57
export EMCC_CFLAGS="-s ERROR_ON_UNDEFINED_SYMBOLS=0"
export PATH="/opt/homebrew/opt/binutils/bin:$PATH"
cargo build --target wasm32-unknown-emscripten
For situations in which Skia does not build or needs to be configured differently, we support some customization support in skia-bindings/build.rs
. For more details take a look at the README of the skia-bindings package.
Please share your build experience so that we can try to automate the build and get to the point where cargo build
is sufficient to build the bindings including Skia, and if that is not possible, clearly prompts to what's missing.
The icon
example generates the rust-skia icon in the current directory.
It computes the position of all the gear teeth etc. based on parameters such as the number of teeth and wheel radius.
If you were able to build the project, run
cargo run --example icon 512
It has a single optional parameter which is the size in pixels for the PNG file. Without parameters, it’ll produce PNG frames for the animated version.
The other examples are taken from Skia's website and ported to the Rust API.
cargo run -- [OUTPUT_DIR]
to generate some Skia drawn PNG images in the directory OUTPUT_DIR
. To render with OpenGL, use
cargo run -- [OUTPUT_DIR] --driver opengl
And to show the drivers that are supported
cargo run -- --help
An example that opens an OpenGL Window and draws the rust-skia icon with skia-safe (contributed by @nornagon).
cargo run --example gl-window --features gl
On Linux the feature x11
needs to be enabled:
cargo run --example gl-window --features gl,x11
Fill, Radial Gradients, Stroke, Stroke with Gradient, Transparency:
Fill, Stroke, Text:
Sweep Gradient:
Dash Path Effect:
For more, you may take a look at the rust-skia.github.io repository.
If you'd like to help with the bindings, take a look at the Wiki to get started and create an issue to prevent duplicate work. For smaller tasks, grep for "TODO"s in the source code. And for heroic work, check out the label help wanted. And if you like to help making the Rust API nicer to use, look out for open issues with the label api ergonomics.
More details can be found at CONTRIBUTING.md.
- Denis Kolodin (@DenisKolodin) contributed build support for Android.
- Alberto González Palomo (@AlbertoGP) designed the Rust-Skia Logo and the example program that renders it.
- Luper Rouch (@flupke, sponsored by Jitter)
added build support for the
wasm32-unknown-emscripten
target. - Osei Fortune (@triniwiz) contributed rendering SVG files.
- LongYinan (@Brooooooklyn)
- Armin (@pragmatrix)
MIT