Setting up your development environment

This chapter will help you set your development environment for librsvg.

System requirements

  • A 64-bit installation of Linux.

  • 8 GB of RAM, or 16 GB recommended if you will be running the full test suite frequently.

  • Around 10 GB free of hard disk space.

  • You can either use podman to work in a containerized setup (this chapter will show you how), or you can install librsvg’s dependencies by hand.

  • Make sure you have git installed.

  • Your favorite text editor.

Downloading the source code

git clone https://gitlab.gnome.org/GNOME/librsvg.git

Setting up with podman

An easy way to set up a development environment is to use podman to download and run a container image. This is similar to having a chroot with all of librsvg’s dependencies already set up.

Install podman on your distro, and then:

cd librsvg      # wherever you did your "git clone"
sh ci/pull-container-image.sh

In the librsvg source tree, ci/pull-container-image.sh is a script that will invoke podman pull to download the container image that you can use for development. It is the same image that librsvg uses for its continuous integration pipeline (CI), so you can have exactly the same setup on your own machine.

That pull-container-image.sh script will give you instructions similar to these:

You can now run this:
  podman run --rm -ti --cap-add=SYS_PTRACE -v $(pwd):/srv/project -w /srv/project $image_name

Don't forget to run this once inside the container:
  source ci/env.sh

You can cut&paste those commands (from the script’s output, not from this document!). The first one should give you a shell prompt inside the container. The second one will make Rust available in the shell’s environment.

What’s all that magic? Let’s dissect the podman command line:

  • podman run - run a specific container image. The image name is the last parameter in that command; it will look something like registry.gitlab.gnome.org/gnome/librsvg/opensuse/tumbleweed:x86_64-1.60.0-2022-08-17.0-main. This is an image built on on a base of the openSUSE Tumbleweed, a rolling distribution of Linux with very recent dependencies.

  • --rm - Remove the container after exiting. It will terminate when you exit the container’s shell.

  • -ti - Set up an interactive session.

  • --cap-add=SYS_PTRACE - Make it possible to run gdb inside the container.

  • -v $(pwd):/srv/project` - Mount the current directory as ``/srv/project inside the container. This lets you build from your current source tree without first copying it into the container; it will be available in /srv/project.

Finally, don’t forget to source ci/env.sh once you are inside podman run.

You can now skip to Building and testing.

Setting up dependencies manually

To compile librsvg, you need the following packages installed. The minimum version is listed here; you may use a newer version instead.

Compilers and build tools:

  • a C compiler and make tool; we recommend GNU make.

  • rust 1.64.0 or later

  • cargo

  • autoconf, automake, libtool, itstool

  • vala (optional)

Mandatory dependencies:

  • Cairo 1.16.0 with PNG support

  • Freetype2 2.8.0

  • Gdk-pixbuf 2.20.0

  • GIO 2.24.0

  • GObject-Introspection 0.10.8

  • gi-docgen

  • python3-docutils

  • Libxml2 2.9.0

  • Pango 1.46.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 gi-docgen python3-docutils git \
libgdk-pixbuf2.0-dev libgirepository1.0-dev \
libxml2-dev libcairo2-dev libpango1.0-dev

Additionally, as of September 2018 you need to add gdk-pixbuf utilities to your path, see #331 for details:

PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0"

Fedora based systems

dnf install -y gcc rust rust-std-static cargo make \
automake autoconf libtool gi-docgen python3-docutils git redhat-rpm-config \
gdk-pixbuf2-devel gobject-introspection-devel \
libxml2-devel cairo-devel cairo-gobject-devel pango-devel

openSUSE based systems

zypper install -y gcc rust rust-std cargo make \
automake autoconf libtool python3-gi-docgen python38-docutils git \
gdk-pixbuf-devel gobject-introspection-devel \
libxml2-devel cairo-devel pango-devel

macOS systems

Dependencies may be installed using Homebrew or another package manager.

brew install automake gi-docgen pkgconfig libtool gobject-introspection gdk-pixbuf pango

Building and testing

Make sure you have gone through the steps in Setting up with podman or Setting up dependencies manually. Then, do the following.

Normal development: You can use cargo build and cargo test as for a simple Rust project; this is what you will use most of the time during regular development. If you are using the podman container as per above, you should do this in the /srv/project directory most of the time.

To casually test rendering, for example, for a feature you are developing, you can run target/debug/rsvg-convert -o output.png my_test_file.svg.

If you do a release build with carto build –release, which includes optimizations, the binary will be in target/release/rsvg-convert. This version is much faster than the debug version.

Doing a full build: You can use the following:

mkdir -p _build
cd _build
../autogen.sh --enable-gtk-doc --enable-vala
make
make check

You should only have to do that if you need to run the full test suite, for the C API tests and the tests for limiting memory consumption.