Librsvg uses a mostly normal autotools setup, but it has some peculiarities due to librsvg's use of a Rust sub-library. The details of how librsvg integrates Cargo and Rust into its autotools setup are described in this blog post, although hopefully you will not need to refer to it.
It is perfectly fine to ask the maintainer if you have questions about the Autotools setup; it's a tricky bit of machinery, and we are glad to help.
There are generic compilation/installation instructions in the
INSTALL file, which comes from Autotools. The following
explains librsvg's peculiarities.
- Installing dependencies for building
- Basic compilation instructions
- Debug or release builds
- Selecting a Rust toolchain
- Building with no network access
Installing dependencies for building
To compile librsvg, you need the following packages installed. The minimum version is listed here; you may use a newer version instead.
- a C compiler and
maketool; we recommend GNU
- rust 1.36 or later
- Cairo 1.16.0 with PNG support
- Freetype2 2.8.0
- Libcroco 0.6.1
- Gdk-pixbuf 2.20.0
- GIO 2.24.0
- GObject-Introspection 0.10.8
- Libxml2 2.9.0
- Pango 1.38.0
The following sections describe how to install these dependencies on several systems.
Debian based systems
As of 2018/Feb/22, librsvg cannot be built in
debian stable and
ubuntu 18.04, as they have packages that are too old.
Build dependencies on Debian Testing or Ubuntu 18.10:
apt-get install -y gcc make rustc cargo \ automake autoconf libtool gettext itstool \ libgdk-pixbuf2.0-dev libgirepository1.0-dev \ gtk-doc-tools git \ libxml2-dev libcroco3-dev libcairo2-dev libpango1.0-dev
Additionally, as of September 2018 you need to add
gdk-pixbuf utilities to your path, see #331 for more.
Fedora based systems
dnf install -y gcc rust rust-std-static cargo make \ automake autoconf libtool gettext itstool \ gdk-pixbuf2-devel gobject-introspection-devel \ gtk-doc git redhat-rpm-config gettext-devel \ libxml2-devel libcroco-devel cairo-devel pango-devel
openSUSE based systems
zypper install -y gcc rust rust-std cargo make \ automake autoconf libtool gettext itstool git \ gtk-doc gobject-introspection-devel \ libxml2-devel libcroco-devel cairo-devel \ pango-devel gdk-pixbuf-devel
Dependencies may be installed using Homebrew or another package manager.
brew install cairo gdk-pixbuf glib libcroco pango \ gobject-introspection rust export PKG_CONFIG_PATH="`brew --prefix`/lib/pkgconfig:\ `brew --prefix libffi`/lib/pkgconfig:\ /usr/lib/pkgconfig" export ARCHFLAGS="-arch x86_64"
PKG_CONFIG_PATH must be manually set to include Homebrew's libffi,
as the system libffi is too old but Homebrew does not install it in a public
location by default.
Currently, cairo 1.15.4 or later must also be installed manually, as the
Homebrew package is for the older stable release. This may require adding
PKG_CONFIG_PATH as well if you do not install it in
ARCHFLAGS is required if gobject-introspection is using the system
Python provided by Apple, as on Homebrew.
Basic compilation instructions
If you are compiling a tarball:
./configure make make install
INSTALL file for details on options you can pass
configure script to select where to install the compiled
If you are compiling from a git checkout:
./autogen.sh make make install
By default the compilation process is quiet, and it just tells you which files it is compiling.
If you wish to see the full compilation command lines, use "
instead of plain "
Debug or release builds
Librsvg has code both in C and Rust, and each language has a different way of specifying compilation options to select compiler optimizations, or whether debug information should be included.
You should set the
CFLAGS environment variable with compiler flags
that you want to pass to the C compiler.
Controlling debug or release mode for Rust
- With a
- With an environment variable:
For the Rust part of librsvg, we have a flag that
you can pass at
configure time. When enabled, the Rust
sub-library will have debugging information and no compiler
optimizations. This flag is off by default: if the flag is not
specified, the Rust sub-library will be built in release mode (no
debug information, full compiler optimizations).
The rationale is that people who already had scripts in place to build binary packages for librsvg, generally from release tarballs, are already using conventional machinery to specify C compiler options, such as that in RPM specfiles or Debian source packages. However, they may not contemplate Rust sub-libraries and they will certainly not want to modify their existing packaging scripts too much.
So, by default, the Rust library builds in release mode, to make
life easier to binary distributions. Librsvg's build scripts will add
--release to the Cargo command line by default.
Developers can request a debug build of the Rust sub-library by
--enable-debug to the
configure script, or by setting the
LIBRSVG_DEBUG=yes environment variable before calling
This will omit the
--release option from Cargo, so that it will
build the Rust sub-library in debug mode.
In case both the environment variable and the command-line option are specified, the command-line option overrides the env var.
Selecting a Rust toolchain
By default, the configure/make steps will use the
cargo binary that
is found in your
$PATH. If you have a system installation of Rust
and one in your home directory, or for special build systems, you may
need to override the locations of
rustc. In this
case, you can set any of these environment variables before running
RUSTC- path to the
CARGO- path to
$RUSTC only gets used in the
configure script to ensure
that there is a Rust compiler installed with an appropriate version.
The actual compilation process just uses
$CARGO, and assumes that
cargo binary will use the same Rust compiler as the other
If you need to cross-compile librsvg, specify the
configure script as usual with Autotools. This will cause
librsvg's build scripts to automatically pass
Note, however, that Rust may support different targets than the C
compiler on your system. Rust's supported targets can be found in the
rust/src/librustc_back/target in the Rust
compiler's source code.
You can check Jorge Aparicio's guide on cross-compilation for Rust for more details.
Overriding the Rust target name
If you need
cargo --target=FOO to obtain a different value from the
one you specified for
--host=TRIPLE, you can use the
variable, and this will be passed to
cargo. For example,
RUST_TARGET=aarch64-unknown-linux-gnu ./configure --host=aarch64-buildroot-linux-gnu # will run "cargo --target=aarch64-unknown-linux-gnu" for the Rust part
Cross-compiling to a target not supported by Rust out of the box
When building with a target that is not supported out of the box by Rust, you have to do this:
Create a target JSON definition file.
Set the environment variable
RUST_TARGET_PATHto its directory for the
cd /my/target/definition echo "JSON goes here" > MYMACHINE-VENDOR-OS.json cd /source/tree/for/librsvg ./configure --host=MYMACHINE-VENDOR-OS make RUST_TARGET_PATH=/my/target/definition
Cross-compiling for win32 target
You can also cross-compile to win32 (Microsoft Windows) target by using MinGW-w64. You need to specify the appropriate target in the same way as usual:
- Set an appropriate target via the
i686-w64-mingw32for 32-bit target
x86_64-w64-mingw32for 64-bit target
- Set an appropriate RUST_TARGET:
i686-pc-windows-gnufor 32-bit target
x86_64-pc-windows-gnufor 64-bit target
In addition you may need to link with some win32 specific libraries like
./configure \ --host=x86_64-w64-mingw32 \ RUST_TARGET=x86_64-pc-windows-gnu \ LIBS="-lws2_32 -luserenv" make
The most painful aspect of this way of building is preparing a win32 build for each of librsvg's dependencies. MXE may help you on this work.
Building with no network access
Automated build systems generally avoid network access so that they can compile from known-good sources, instead of pulling random updates from the net every time. However, normally Cargo likes to download dependencies when it first compiles a Rust project.
cargo vendor to ship librsvg release tarballs
with the source code for Rust dependencies embedded within the
tarball. If you unpack a librsvg tarball, these sources will appear
rust/vendor subdirectory. If you build librsvg from a
tarball, instead of git, it should not need to access the network to
download extra sources at all.
Build systems can use Cargo's source replacement mechanism to override the location of the source code for the Rust dependencies, for example, in order to patch one of the Rust crates that librsvg uses internally.
The source replacement information is in
rust/.cargo/config in the
unpacked tarball. Your build system can patch this file as needed.
make distcheck command will built a release tarball, extract it,
compile it and test it. However, part of the
make install process
within that command will try to install the gdk-pixbuf loader in your
system location, and it will fail.
make distcheck like this:
$ make distcheck DESTDIR=/tmp/foo
DESTDIR will keep the gdk-pixbuf loader installation from
trying to modify your system locations.