:toc:
:toc-title:
= How to build *resvg*
== Intro
*resvg* doesn't include a 2D graphics library and uses external ones.
Their support is implemented separately, therefore we call them _backends_.
You can build them separately or together. +
At the moment, there are only three backends: https://www.qt.io/[Qt],
https://www.cairographics.org/[cairo] and
https://github.com/jrmuizel/raqote[raqote] (experimental).
Since *resvg* is a https://www.rust-lang.org/[Rust] library, you should build it via `cargo`. +
To enable a backend use the `--features` option:
```bash
# Build with a Qt backend
cargo build --release --features="qt-backend"
# or with a cairo backend
cargo build --release --features="cairo-backend"
# or with a raqote backend
cargo build --release --features="raqote-backend"
# or with all
cargo build --release --features="qt-backend cairo-backend raqote-backend"
```
== Dependencies
* The library requires the latest stable
https://www.rust-lang.org/tools/install[Rust].
* All backends depend on https://github.com/harfbuzz/harfbuzz[harfbuzz],
which will be built automatically by `cargo` and will be linked statically.
https://cmake.org/download/[CMake] is required as a build-time dependency.
* The _Qt backend_ requires only `QtCore` and `QtGui` libraries
and the JPEG image format plugin (aka `plugins/imageformats/qjpeg`). +
Technically, any Qt 5 version should work, but we only support Qt >= 5.6.
* The _cairo backend_ requires https://www.cairographics.org/[cairo] and `gdk-pixbuf` (part of GTK). +
cairo >= 1.12 and gdk-pixbuf >= 2.30
* The _raqote backend_ doesn't require any external dependencies.
* (Linux, runtime) _fontconfig_. Specifically `fc-match`.
== Windows
=== Qt backend via MSVC
Install:
* `stable-x86_64-pc-windows-msvc` https://www.rust-lang.org/tools/install[Rust] target.
* https://cmake.org/download/[CMake] (required to build harfbuzz).
* Qt built with MSVC via an http://download.qt.io/official_releases/online_installers/qt-unified-windows-x86-online.exe[official installer].
Build using `x64 Native Tools Command Prompt for VS 2017` shell:
```batch
set PATH=%userprofile%\.cargo\bin;%PATH%
set QT_DIR=C:\Qt\5.12.0\msvc2017_64
cargo.exe build --release --features "qt-backend"
```
Instead of `msvc2017_64` you can use any other Qt MSVC build. Even 32-bit one.
We are using Qt 5.12.0 just for example.
=== Qt backend via MinGW
Install:
* `stable-x86_64-pc-windows-gnu` https://www.rust-lang.org/tools/install[Rust] target.
* https://cmake.org/download/[CMake] (required to build harfbuzz).
* Qt built with MinGW 64-bit via an http://download.qt.io/official_releases/online_installers/qt-unified-windows-x86-online.exe[official installer].
Build using `cmd.exe`:
```batch
set PATH=C:\Qt\5.12.0\mingw73_64\bin;C:\Qt\Tools\mingw730_64\bin;%userprofile%\.cargo\bin;%PATH%
set QT_DIR=C:\Qt\5.12.0\mingw73_64
cargo.exe build --release --features "qt-backend"
```
Instead of `mingw73_64` you can use any other Qt mingw build.
We are using Qt 5.12.0 just for example.
=== cairo backend via MSYS2
Install `stable-x86_64-pc-windows-gnu` https://www.rust-lang.org/tools/install[Rust] target.
And then:
```bash
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-cairo mingw-w64-x86_64-gdk-pixbuf2
cargo.exe build --release --features "cairo-backend"
```
You can use i686 target in the same way.
=== raqote backend via MSVC
Install:
* `stable-x86_64-pc-windows-msvc` https://www.rust-lang.org/tools/install[Rust] target.
* https://cmake.org/download/[CMake] (required to build harfbuzz).
Build using `x64 Native Tools Command Prompt for VS 2017` shell:
```batch
set PATH=%userprofile%\.cargo\bin;C:\Program Files\CMake\bin;%PATH%
cargo.exe build --release --features "raqote-backend"
```
=== raqote backend via MSYS2
Install `stable-x86_64-pc-windows-gnu` https://www.rust-lang.org/tools/install[Rust] target.
And then:
```bash
# install harfbuzz dependencies:
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake
cargo.exe build --release --features "raqote-backend"
```
You can use i686 target in the same way.
== Linux
=== Qt backend
Install Qt 5 and `harfbuzz` using your distributive's package manager.
On Ubuntu you can install them via:
```
sudo apt install qtbase5-dev libharfbuzz-dev
```
Build `resvg`:
```bash
cargo build --release --features "qt-backend"
```
If you don't want to use a system Qt, you can alter it with the `PKG_CONFIG_PATH` variable.
```bash
PKG_CONFIG_PATH='/path_to_qt/lib/pkgconfig' cargo build --release --features "qt-backend"
```
=== cairo backend
Install `cairo`, `gdk-pixbuf` and `harfbuzz` using your distributive's package manager.
On Ubuntu you can install them via:
```
sudo apt install libcairo2-dev libgdk-pixbuf2.0-dev libharfbuzz-dev
```
Build `resvg`:
```bash
cargo build --release --features "cairo-backend"
```
=== raqote backend
Install `harfbuzz` using your distributive's package manager.
On Ubuntu you can install it via:
```
sudo apt install libharfbuzz-dev
```
Build `resvg`:
```bash
cargo build --release --features "raqote-backend"
```
== macOS
=== Qt backend
Using https://brew.sh/[homebrew]:
```bash
brew install qt
QT_DIR=/usr/local/opt/qt cargo build --release --features "qt-backend"
```
Or an
http://download.qt.io/official_releases/online_installers/qt-unified-mac-x64-online.dmg[official Qt installer]:
```bash
QT_DIR=/Users/$USER/Qt/5.12.0/clang_64 cargo build --release --features "qt-backend"
```
We are using Qt 5.12.0 just for example.
=== cairo backend
Using https://brew.sh/[homebrew]:
```bash
brew install cairo gdk-pixbuf
cargo build --release --features "cairo-backend"
```
=== raqote backend
```bash
cargo build --release --features "raqote-backend"
```
== For maintainers
*resvg* consists of 4 parts:
- the Rust library (link:./src[src])
- the C library/bindings (link:./capi[capi])
- the CLI tool to render SVG (link:./tools/rendersvg[tools/rendersvg])
- the CLI tool to simplify SVG (link:./tools/usvg[tools/usvg])
All of them are optional and each one, except `usvg`, can be built with a specific backend.
No need to build `rendersvg` for each backend separately since it has a CLI switch
to choose which one to use in runtime.
Not sure how the Rust library can be packaged, but the C libraries should probably be built
separately.
So the final package can look like this:
```
/bin/rendersvg (does not depend on libresvg-*.so)
/bin/usvg (completely optional)
/include/resvg/resvg.h (from capi/include)
/include/resvg/ResvgQt.h (from capi/include, only for Qt backend)
/lib/libresvg-cairo.so
/lib/libresvg-qt.so
```