Move COMPILING.md to devel-docs/compiling.rst

The compilation guide is now in the development guide.

Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/783>

4 files changed, 268 insertions, 263 deletions

diff --git a/COMPILING.md b/COMPILING.md
deleted file mode 100644
index ee7e6aa3..00000000
--- a/COMPILING.md
+++ /dev/null
@@ -1,257 +0,0 @@
-Compiling librsvg
-=================
-
-# Detailed compilation instructions
-
-A full build of librsvg requires [autotools].  A full build will produce these:
-
-* `rsvg-convert` binary.
-* librsvg shared library with the GObject-based API.
-* Gdk-pixbuf loader for SVG files.
-* HTML documentation for the GObject-based API, with `gi-docgen`.
-* GObject-introspection information for language bindings.
-* Vala language bindings.
-
-Librsvg uses a mostly normal [autotools] setup.  The details of how
-librsvg integrates Cargo and Rust into its autotools setup are
-described in [this blog post][blog], although hopefully you will not
-need to refer to it.
-
-It is perfectly fine to [ask the maintainer][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`][install] file, which comes from Autotools.  The following
-explains librsvg's peculiarities.
-
-* [Basic compilation instructions](#basic-compilation-instructions)
-* [Verbosity](#verbosity)
-* [Debug or release builds](#debug-or-release-builds)
-* [Selecting a Rust toolchain](#selecting-a-rust-toolchain)
-* [Cross-compilation](#cross-compilation)
-* [Building with no network access](#building-with-no-network-access)
-* [Running `make distcheck`](#running-make-distcheck)
-
-# Basic compilation instructions
-
-If you are compiling a tarball:
-
-```sh
-./configure --enable-vala
-make
-make install
-```
-
-See the [`INSTALL`][install] file for details on options you can pass
-to the `configure` script to select where to install the compiled
-library.
-
-If you are compiling from a git checkout:
-
-```sh
-./autogen.sh --enable-vala
-make
-make install
-```
-
-The `--enable-vala` argument is optional.  It will check that you have
-the Vala compiler installed.
-
-# Verbosity
-
-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 "`make V=1`"
-instead of plain "`make`".
-
-# Debug or release builds
-
-Librsvg's artifacts have 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.
-
-* **Rust code:** the librsvg shared library, and the `rsvg-convert`
-  binary.  See below.
-
-* **C code:** the gdk-pixbuf loader; 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 `configure` option: `--enable-debug` or `--disable-debug`
-* With an environment variable: `LIBRSVG_DEBUG=yes` or `LIBRSVG_DEBUG=no`
-
-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 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 code by
-passing `--enable-debug` to the `configure` script, or by setting the
-`LIBRSVG_DEBUG=yes` environment variable before calling `configure`.
-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 `cargo` and/or `rustc`.  In this
-case, you can set any of these environment variables before running
-`configure` or `autogen.sh`:
-
-* `RUSTC` - path to the `rustc` compiler
-* `CARGO` - path to `cargo`
-
-Note that `$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
-that `cargo` binary will use the same Rust compiler as the other
-variable.
-
-# Cross-compilation
-
-If you need to cross-compile librsvg, specify the `--host=TRIPLE` to
-the `configure` script as usual with Autotools.  This will cause
-librsvg's build scripts to automatically pass `--target=TRIPLE` to
-`cargo`.
-
-Note, however, that Rust may support different targets than the C
-compiler on your system.  Rust's supported targets can be found in the
-[rustc manual](https://doc.rust-lang.org/nightly/rustc/platform-support.html)
-
-You can check Jorge Aparicio's [guide on cross-compilation for
-Rust][rust-cross] 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 `RUST_TARGET`
-variable, and this will be passed to `cargo`.  For example,
-
-```sh
-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:
-
-1. Create a [target JSON definition file][target-json].
-
-2. Set the environment variable `RUST_TARGET_PATH` to its directory
-   for the `make` command.
-
-Example:
-
-```sh
-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][mingw-w64]. You need to specify the appropriate target in the same way
-as usual:
-
-* Set an appropriate target via the `--host` configure option:
-    * `i686-w64-mingw32` for 32-bit target
-    * `x86_64-w64-mingw32` for 64-bit target
-* Set an appropriate RUST_TARGET:
-    * `i686-pc-windows-gnu` for 32-bit target
-    * `x86_64-pc-windows-gnu` for 64-bit target
-
-In addition you may need to link with some win32 specific libraries like
-`LIBS="-lws2_32 -luserenv"`.
-
-Example:
-
-```sh
-./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][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.
-
-We use [`cargo vendor`][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
-in the `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][cargo-source-replacement] 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.
-
-# Running `make distcheck`
-
-The `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.
-
-Please run `make distcheck` like this:
-
-```
-$ make distcheck DESTDIR=/tmp/foo
-```
-
-That `DESTDIR` will keep the gdk-pixbuf loader installation from
-trying to modify your system locations.
-
-[autotools]: https://autotools.io/index.html
-[blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html
-[maintainer]: README.md#maintainers
-[install]: INSTALL
-[cargo-vendor]: https://crates.io/crates/cargo-vendor
-[cargo-source-replacement]: http://doc.crates.io/source-replacement.html
-[rust-cross]: https://github.com/japaric/rust-cross
-[target-json]: https://github.com/japaric/rust-cross#target-specification-files
-[mingw-w64]: https://mingw-w64.org/
-[mxe]: https://mxe.cc/
diff --git a/README.md b/README.md
index 1996e7b6..01a213f5 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ may run into some peculiarities due to the Rust internals library if
 you are **cross-compiling** or if you are in a **build system with no
 network access**, or if you are **building binary packages from a
 librsvg tarball**.  In those cases, please refer to the
-[`COMPILING.md`][compiling] file.
+[Detailed compilation instructions][compiling] in the development guide.
 
 **Documentation:** You can read the documentation for librsvg's [C
 API][c-docs] or the [Rust API][rust-docs].  Please [file an
@@ -77,10 +77,9 @@ documentation for information on how to load the `Rsvg` namespace.
 There is a code of conduct for contributors to librsvg; please see the
 file [`code-of-conduct.md`][coc].
 
-Please see the [Development guide for
-librsvg](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html)
-on how to contribute to librsvg, how set up your development
-environment, and for a description of librsvg's architecture.
+Please see the [Development guide for librsvg][devel-guide] on how to
+contribute to librsvg, how set up your development environment, and
+for a description of librsvg's architecture.
 
 For information on how to report bugs, or how to contribute to librsvg
 in general, please see the file [`CONTRIBUTING.md`][contributing].
@@ -193,7 +192,7 @@ ways:
 [cairo]: https://www.cairographics.org/
 [coc]: code-of-conduct.md
 [autotools]: https://autotools.io/index.html
-[compiling]: COMPILING.md
+[compiling]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/compiling.html
 [mail]: mailto:federico@gnome.org
 [bugs]: https://gitlab.gnome.org/GNOME/librsvg/issues
 [gi]: https://wiki.gnome.org/Projects/GObjectIntrospection
@@ -206,3 +205,4 @@ ways:
 [guadec-presentation-2]: https://viruta.org/docs/fmq-refactoring-c-to-rust.pdf
 [gnome-hackers]: https://matrix.to/#/#gnome-hackers:gnome.org
 [gnome-rust]: https://matrix.to/#/#rust:gnome.org
+[devel-guide]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html
diff --git a/devel-docs/compiling.rst b/devel-docs/compiling.rst
new file mode 100644
index 00000000..07ba2e62
--- /dev/null
+++ b/devel-docs/compiling.rst
@@ -0,0 +1,260 @@
+Detailed compilation instructions
+=================================
+
+A full build of librsvg requires
+`autotools <https://autotools.io/index.html>`__. A full build will
+produce these (see :doc:`product` for details):
+
+-  ``rsvg-convert`` binary and its ``man`` page.
+-  librsvg shared library with the GObject-based API.
+-  Gdk-pixbuf loader for SVG files.
+-  HTML documentation for the GObject-based API, with ``gi-docgen``.
+-  GObject-introspection information for language bindings.
+-  Vala language bindings.
+
+Librsvg uses a mostly normal `autotools
+<https://autotools.io/index.html>`__ setup. The historical details of
+how librsvg integrates Cargo and Rust into its autotools setup are
+described in `this blog post
+<https://viruta.org/librsvgs-build-infrastructure-autotools-and-rust.html>`__,
+although hopefully you will not need to refer to it.
+
+It is perfectly fine to `ask the maintainer
+<https://gitlab.gnome.org/GNOME/librsvg/#maintainers>`__ if you have
+questions about the Autotools setup; it’s a tricky bit of machinery, and
+we are glad to help.
+
+The rest of this document explains librsvg’s peculiarities apart from
+the usual way of compiling Autotools projects:
+
+-  `Basic compilation instructions <#basic-compilation-instructions>`__
+-  `Verbosity <#verbosity>`__
+-  `Debug or release builds <#debug-or-release-builds>`__
+-  `Selecting a Rust toolchain <#selecting-a-rust-toolchain>`__
+-  `Cross-compilation <#cross-compilation>`__
+-  `Building with no network
+   access <#building-with-no-network-access>`__
+-  `Running "make distcheck" <#running-make-distcheck>`__
+
+Basic compilation instructions
+------------------------------
+
+If you are compiling a tarball:
+
+.. code:: sh
+
+   ./configure --enable-gtk-doc --enable-vala
+   make
+   make install
+
+See the ``INSTALL`` file for details on options you can
+pass to the ``configure`` script to select where to install the compiled
+library.
+
+If you are compiling from a git checkout:
+
+.. code:: sh
+
+   ./autogen.sh --enable-gtk-doc --enable-vala
+   make
+   make install
+
+The ``--enable-gtk-doc`` and ``--enable-vala`` arguments are
+optional. They will check that you have gi-docgen and the Vala compiler
+installed, respectively.
+
+Verbosity
+---------
+
+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
+“``make V=1``” instead of plain “``make``”.
+
+Debug or release builds
+-----------------------
+
+Librsvg’s artifacts have 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.
+
+-  **Rust code:** the librsvg shared library, and the ``rsvg-convert``
+   binary. See below.
+
+-  **C code:** the gdk-pixbuf loader; 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 ``configure`` option: ``--enable-debug`` or
+   ``--disable-debug``
+-  With an environment variable: ``LIBRSVG_DEBUG=yes`` or
+   ``LIBRSVG_DEBUG=no``
+
+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 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 code by passing
+``--enable-debug`` to the ``configure`` script, or by setting the
+``LIBRSVG_DEBUG=yes`` environment variable before calling ``configure``.
+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 ``cargo`` and/or ``rustc``. In this
+case, you can set any of these environment variables before running
+``configure`` or ``autogen.sh``:
+
+-  ``RUSTC`` - path to the ``rustc`` compiler
+-  ``CARGO`` - path to ``cargo``
+
+Note that ``$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 that ``cargo`` binary will use the same Rust compiler as
+the other variable.
+
+Cross-compilation
+-----------------
+
+If you need to cross-compile librsvg, specify the ``--host=TRIPLE`` to
+the ``configure`` script as usual with Autotools. This will cause
+librsvg’s build scripts to automatically pass ``--target=TRIPLE`` to
+``cargo``.
+
+Note, however, that Rust may support different targets than the C
+compiler on your system. Rust’s supported targets can be found in the
+`rustc
+manual <https://doc.rust-lang.org/nightly/rustc/platform-support.html>`__
+
+You can check Jorge Aparicio’s `guide on cross-compilation for
+Rust <https://github.com/japaric/rust-cross>`__ 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 ``RUST_TARGET``
+variable, and this will be passed to ``cargo``. For example,
+
+.. code:: sh
+
+   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:
+
+1. Create a `target JSON definition
+   file <https://github.com/japaric/rust-cross#target-specification-files>`__.
+
+2. Set the environment variable ``RUST_TARGET_PATH`` to its directory
+   for the ``make`` command.
+
+Example:
+
+.. code:: sh
+
+   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 <https://mingw-w64.org/>`__. You need to specify the
+appropriate target in the same way as usual:
+
+-  Set an appropriate target via the ``--host`` configure option:
+
+   -  ``i686-w64-mingw32`` for 32-bit target
+   -  ``x86_64-w64-mingw32`` for 64-bit target
+
+-  Set an appropriate RUST_TARGET:
+
+   -  ``i686-pc-windows-gnu`` for 32-bit target
+   -  ``x86_64-pc-windows-gnu`` for 64-bit target
+
+In addition you may need to link with some win32 specific libraries like
+``LIBS="-lws2_32 -luserenv"``.
+
+Example:
+
+.. code:: sh
+
+   ./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 <https://mxe.cc/>`__ 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.
+
+You can use `cargo vendor
+<https://doc.rust-lang.org/cargo/commands/cargo-vendor.html>`_ to
+download librsvg's Rust dependencies ahead of time, so that subsequent
+compilation don't require network access.
+
+Build systems can use `Cargo’s source replacement
+mechanism <https://doc.rust-lang.org/cargo/reference/source-replacement.html>`_ 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.
+
+Running ``make distcheck``
+--------------------------
+
+The ``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.
+
+Please run ``make distcheck`` like this:
+
+::
+
+   $ make distcheck DESTDIR=/tmp/foo
+
+That ``DESTDIR`` will keep the gdk-pixbuf loader installation from
+trying to modify your system locations.
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 4b59aede..97e5e724 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -8,6 +8,7 @@ Development guide for librsvg
    product
    features
    roadmap
+   compiling
 
 .. toctree::
    :caption: Getting Started as a Contributor
@@ -59,6 +60,7 @@ evolved into a few different tools.
 - :doc:`features` - Supported elements, attributes, and properties.
 - :doc:`roadmap` - Ever-changing list of priorities for the
   maintainers; check this often!
+- :doc:`compiling` - cross compilation, debug/release builds, special options.
 
 Getting started
 ---------------