[librsvg/hospitality: 7/12] COMPILING.md: New file with details on compilation options

[Federico Mena Quintero <federico src gnome org>]

commit c1386f105b20a7c5c6747858e678e4fd5d97b4ec
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Nov 30 09:15:55 2017 -0600

    COMPILING.md: New file with details on compilation options

 COMPILING.md |  111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    |    9 +++++
 2 files changed, 120 insertions(+), 0 deletions(-)
---
diff --git a/COMPILING.md b/COMPILING.md
new file mode 100644
index 0000000..c8f789b
--- /dev/null
+++ b/COMPILING.md
@@ -0,0 +1,111 @@
+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.
+
+There are generic compilation/installation instructions in the
+[`INSTALL`][install] file, which comes from Autotools.  The following
+explains librsvg's peculiarities.
+
+* [Verbosity][#verbosity]
+* [Debug or release builds][#debug-or-release-builds]
+* [Cross-compilation][#cross-compilation]
+* [Building with no network access][#building-with-no-network-access]
+
+# 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 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
+
+For the Rust part of librsvg, we have an `--enable-debug` flag that
+you can pass to the `configure` script.  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
+passing `--enable-debug` to the `configure` script.  This will omit
+the `--release` option from Cargo, so that it will build the Rust
+sub-library in debug mode.
+
+# 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 `--host=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
+[`rust/src/librustc_back/target`][rust-target-dir] in the Rust
+compiler's source code.
+
+## 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 will have to create a target JSON definition file and set
+the environment variable `RUST_TARGET_PATH` to its directory when
+building librsvg.
+
+```sh
+cd /my/target/definition
+echo "JSON goes here" > MYMACHINE-VENDOR-OS.json
+cd /source/tree/for/librsvg
+RUST_TARGET_PATH=/my/target/definition ./configure --host=MYMACHINE-VENDOR-OS
+make
+```
+# 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.
+
+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.
+
+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.
+
+[autotools]: https://autotools.io/index.html
+[blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html
+[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
diff --git a/README.md b/README.md
index 7899e3e..09dff87 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,13 @@ minimal API?  Librsvg may be adequate for you.
 Using librsvg
 -------------
 
+**Compiling:** Librsvg uses a mostly normal [autotools] setup.  You
+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.
+
 **Documentation:** You can read the [documentation for librsvg][docs] at
 developer.gnome.org.  Please [tell us][mail] if you don't find
 something there that you need.
@@ -83,6 +90,8 @@ can [mail me][mail] for any other questions you have about librsvg.
 [gnome]: https://www.gnome.org/
 [cairo]: https://www.cairographics.org/
 [coc]: code-of-conduct.md
+[autotools]: https://autotools.io/index.html
+[compiling]: COMPILING.md
 [docs]: https://developer.gnome.org/rsvg/stable/
 [mail]: mailto:federico gnome org
 [bugs]: https://bugzilla.gnome.org/page.cgi?id=browse.html&product=librsvg