: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 four backends: https://www.qt.io/[Qt],
https://www.cairographics.org/[cairo], https://skia.org/[Skia] and
https://github.com/jrmuizel/raqote[raqote].

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 a skia backend
cargo build --release --features="skia-backend"
# or with all
cargo build --release --all-features
```

== 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. +
  Technically, any Qt 5 version should work, but we only support Qt >= 5.6.
* The _cairo backend_ requires https://www.cairographics.org/[cairo] >= 1.12.
* The _raqote backend_ doesn't require any external dependencies.
* The _skia backend_ requires the https://skia.org/[Skia] itself.
* (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

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.

=== Skia 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).
* Skia itself (we assume that you have already built one).

`SKIA_DIR` should point to a Skia directory that contains the Skia `include` directory.
`SKIA_LIB_DIR` should point to a Skia directory that contains `skia.dll`.

Build using `x64 Native Tools Command Prompt for VS 2017` shell:

```batch
set PATH=%userprofile%\.cargo\bin;C:\Program Files\CMake\bin;%PATH%
set SKIA_DIR=path
set SKIA_LIB_DIR=path

cargo.exe build --release --features "skia-backend"
```

== 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` and `harfbuzz` using your distributive's package manager.

On Ubuntu you can install them via:

```
sudo apt install libcairo2-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"
```

=== Skia backend

We assume that you have already built Skia itself.

Install `harfbuzz` using your distributive's package manager.

On Ubuntu you can install it via:

```
sudo apt install libharfbuzz-dev
```

`SKIA_DIR` should point to a Skia directory that contains the Skia `include` directory.
`SKIA_LIB_DIR` should point to a Skia directory that contains `libskia.so`.

```sh
SKIA_DIR=path SKIA_LIB_DIR=path cargo build --release --features "skia-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

cargo build --release --features "cairo-backend"
```

=== raqote backend

```bash
cargo build --release --features "raqote-backend"
```

=== Skia backend

We assume that you have already built Skia itself.

Install `harfbuzz` using Homebrew via:

```
brew install harfbuzz
```

`SKIA_DIR` should point to a Skia directory that contains the Skia `include` directory.
`SKIA_LIB_DIR` should point to a Skia directory that contains `libskia.dylib`.

```sh
SKIA_DIR=path SKIA_LIB_DIR=path cargo build --release --features "skia-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
/lib/libresvg-raqote.so
/lib/libresvg-skia.so
```
