:toc:
:toc-title:

= How to build *resvg*

== Into

*resvg* doesn't include a 2D graphics library and uses external ones via https://en.wikipedia.org/wiki/Foreign_function_interface[FFI].
Their support is implemented separately, therefore we call them _backends_.
You can build them separately or together. +
At the moment, there are only two backends: *Qt* and *cairo*.
The first one uses the https://www.qt.io/[Qt framework] and the second one uses the
https://www.cairographics.org/[cairo] library.

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 both
cargo build --release --features="qt-backend cairo-backend"
```

== Dependencies

- The library requires the latest stable
  https://www.rust-lang.org/tools/install[Rust].
- _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.

- _cairo backend_ requires https://www.cairographics.org/[cairo] itself and https://www.pango.org/[pango] for text rendering (with the `pangocairo` glue library, which is an optional part of the `pango`). +
  There is no specific minimal supported version at the moment.

== Windows

=== Qt backend via MSVC

Install `stable-x86_64-pc-windows-msvc` https://www.rust-lang.org/tools/install[Rust] target.

Install Qt built with MSVC 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=%userprofile%\.cargo\bin;%PATH%
set QT_DIR=C:\Qt\5.12.0\msvc2015_64

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

Instead of `msvc2015_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-i686-pc-windows-gnu` https://www.rust-lang.org/tools/install[Rust] target.

Install Qt built with MinGW 32-bit via an
http://download.qt.io/official_releases/online_installers/qt-unified-windows-x86-online.exe[official installer]. +
64-bit version, available since Qt 5.12, will not work due to https://github.com/rust-lang/rust/issues/47048[#47048].

Build using `cmd.exe`:

```batch
set PATH=C:\Qt\5.11.3\mingw53_32\bin;C:\Qt\Tools\mingw530_32\bin;%userprofile%\.cargo\bin;%PATH%
set QT_DIR=C:\Qt\5.11.3\mingw53_32

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

Instead of `mingw53_32` you can use any other Qt mingw build. +
We are using Qt 5.11.3 just for example.

=== cairo backend via MSYS2

Install `stable-x86_64-pc-windows-gnu` https://www.rust-lang.org/tools/install[Rust] target.

Install GTK+ dependencies using MSYS2 as explained
http://gtk-rs.org/docs/requirements.html#windows[here].

We do not need the whole GTK+, so we can install only `pango` (which will install
`cairo` too) and `gdk-pixbuf2`:

```bash
pacman -S mingw-w64-x86_64-pango mingw-w64-x86_64-gdk-pixbuf2

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

You can use x86/i686 target in the same way.

== Linux

=== Qt backend

Install Qt 5 using your distributive package manager and then 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`, `pango` (with `pangocairo`) and `gdk-pixbuf` using your distributive package manager.

For Ubuntu its `libpango1.0-dev` (will pull `cairo` too) and `libgdk-pixbuf2.0-dev`.

```bash
cargo build --release --features "cairo-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 pango gdk-pixbuf

cargo build --release --features "cairo-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 *.so)
/bin/usvg (completely optional)
/include/resvg.h (from capi/include)
/include/ResvgQt.h (from capi/include)
/lib/libresvg-cairo.so
/lib/libresvg-qt.so
```
