[librsvg: 8/9] Update COMPILING.md now that autotools is not as prominent

[Federico Mena Quintero <federico src gnome org>]

commit 5ba3b9eeeb6767660976f197d5bb38fcf50c2a1d
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri May 28 21:10:44 2021 -0500

    Update COMPILING.md now that autotools is not as prominent

 COMPILING.md | 108 ++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 73 insertions(+), 35 deletions(-)
---
diff --git a/COMPILING.md b/COMPILING.md
index c448a612..c8ee810b 100644
--- a/COMPILING.md
+++ b/COMPILING.md
@@ -1,28 +1,27 @@
 Compiling librsvg
 =================
 
-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][blog], although hopefully you will not
-need to refer to it.
+**For the impatient:**
 
-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.
+First, install librsvg's dependencies; see ["Installing dependencies for
+building"](#installing-dependencies-for-building) below for
+instructions for various operating systems.
 
-There are generic compilation/installation instructions in the
-[`INSTALL`][install] file, which comes from Autotools.  The following
-explains librsvg's peculiarities.
+For everyday hacking, librsvg looks like a regular Rust project.  You
+can `cargo build` to compile the main user-visible artifact for the
+`rsvg-convert` program:
 
-* [Installing dependencies for building](#installing-dependencies-for-building)
-* [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)
+* `cargo build --release` - will compile `rsvg-convert` and put it in
+  `./target/release/rsvg-convert`.  You can use that binary directly.
+  If you need a debug build, use `cargo build --debug` instead; note
+  that debug binaries run *much* slower!
+
+* `cargo test` - this runs almost all of librsvg's test suite, which
+  includes the Rust API and `rsvg-convert`, and is enough for regular
+  hacking.  The full test suite includes tests for the C API; see the
+  section "Compiling the C API" below.
+
+* `cargo doc` - will produce the documentation for the Rust crate.
 
 # Installing dependencies for building
 
@@ -75,7 +74,7 @@ PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0"
 dnf install -y gcc rust rust-std-static cargo make \
 automake autoconf libtool gtk-doc git redhat-rpm-config \
 gdk-pixbuf2-devel gobject-introspection-devel \
-libxml2-devel cairo-devel cairo-gobject-devel pango-devel 
+libxml2-devel cairo-devel cairo-gobject-devel pango-devel
 ```
 
 ### openSUSE based systems
@@ -84,7 +83,7 @@ libxml2-devel cairo-devel cairo-gobject-devel pango-devel
 zypper install -y gcc rust rust-std cargo make \
 automake autoconf libtool gtk-doc git \
 gdk-pixbuf-devel gobject-introspection-devel \
-libxml2-devel cairo-devel pango-devel 
+libxml2-devel cairo-devel pango-devel
 ```
 
 ### macOS systems
@@ -96,12 +95,44 @@ package manager.
 brew install automake gtk-doc pkgconfig libtool gobject-introspection gdk-pixbuf pango
 ```
 
+# 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 `gtk-doc`.
+* 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
+./configure --enable-gtk-doc --enable-vala
 make
 make install
 ```
@@ -113,11 +144,15 @@ library.
 If you are compiling from a git checkout:
 
 ```sh
-./autogen.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 `gtk-doc` and the Vala compiler
+installed, respectively.  You can omit them if you wish.
+
 # Verbosity
 
 By default the compilation process is quiet, and it just tells you
@@ -128,12 +163,17 @@ instead of plain "`make`".
 
 # 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.
+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.
 
-You should set the `CFLAGS` environment variable with compiler flags
-that you want to pass to the C compiler.
+* **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
 
@@ -143,7 +183,7 @@ that you want to pass to the C compiler.
 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
+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).
 
@@ -151,14 +191,14 @@ 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
+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 sub-library by
+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
@@ -194,8 +234,7 @@ librsvg's build scripts to automatically pass `--target=TRIPLE` to
 
 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`][rust-target-dir] in the Rust
-compiler's source code.
+[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.
@@ -273,7 +312,7 @@ 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 `rust/vendor` subdirectory.  If you build librsvg from a
+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.
 
@@ -305,7 +344,6 @@ trying to modify your system locations.
 [blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html
 [maintainer]: README.md#maintainers
 [install]: INSTALL
-[rust-target-dir]: https://github.com/rust-lang/rust/tree/master/src/librustc_back/target
 [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