[librsvg/meson-2022-oct] Add a design doc for switching to meson

[Federico Mena Quintero <federico src gnome org>]

commit a230d97f3b82286b25a0b58be621949c647b7699
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Oct 12 19:02:40 2022 -0500

    Add a design doc for switching to meson

 devel-docs/index.rst |  3 +++
 devel-docs/meson.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
---
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 34625c155..32edbf2cf 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -9,6 +9,7 @@ Development guide for librsvg
    adding_a_property
    memory_leaks
    contributing
+   meson
    ci
    text_layout
    render_tree
@@ -71,6 +72,7 @@ a sort of big-picture development history apart from commit messages.
 - :doc:`render_tree`
 - :doc:`api_observability`
 - :doc:`performance_tracking`
+- :doc:`meson`
 
 See https://rustc-dev-guide.rust-lang.org/walkthrough.html, section
 Overview, to formalize the RFC process for features vs. drive-by
@@ -80,6 +82,7 @@ Information for maintainers
 ---------------------------
 
 - :doc:`releasing`
+- :doc:`ci`
 
 Overview of the maintainer's workflow.
 
diff --git a/devel-docs/meson.rst b/devel-docs/meson.rst
new file mode 100644
index 000000000..0ea4a1931
--- /dev/null
+++ b/devel-docs/meson.rst
@@ -0,0 +1,51 @@
+Meson build system
+==================
+
+As of 2022/Oct, librsvg still uses autotools to call ``cargo`` and
+build all the artifacts that require the C API of librsvg to be built
+beforehand.
+
+The idea is to switch to meson and cargo-cbuild at the same time.
+It's not really worth tweaking the autotools files to deal with
+cargo-cbuild just to remove libtool; it is better to switch to a
+friendlier build system that the rest of GNOME prefers already.
+
+Librsvg's artifacts are listed in :doc:`product` - a reminder, with a
+few extra intermediate stages:
+
+- ``configure.ac``, to be replaced with ``meson.build``, has the
+  version number.  ``build.rs`` looks for it there using a regex, and
+  generates Rust code that includes the version number.  It also
+  builds ``rsvg-version.h`` for the benefit of the C API artifacts,
+  but it may be better to generate it from ``meson.build`` to make
+  meson happier.
+
+- The Rust code can be used to build three artifacts: the static
+  library ``librsvg.a``, the dynamic library ``librsvg.so``, and the
+  ``rsvg-convert`` executable.
+
+- The header files are static / written by hand, with the exception of
+  ``rsvg-version.h``, which is generated.  As noted above, meson can
+  directly generate that file instead of going through ``build.rs``.
+
+- From ``librsvg.so`` and the header files, build the ``.gir`` and
+  ``.typelib`` introspection data.
+
+- From the ``.gir``, build Vala bindings.
+
+- From the ``.gir`` and headers, build the C API docs with ``gi-docgen``.
+
+- The ``.pc`` file for pkg-config can be built by ``cargo-cbuild``.
+
+- Building the ``.man`` page for ``rsvg-convert`` doesn't depend on
+  anything but ``rst2man``.
+
+- The source tree already contains an experimental port of the
+  gdk-pixbuf loader to Rust.  We can either build that trivially with
+  ``cargo`` and install it with Meson, or keep building the C version
+  of the gdk-pixbuf loader with Meson.  I'd like to remove the C code
+  and see what the rest of the platform thinks of having a big binary
+  for a gdk-pixbuf loader.
+
+- Meson also needs to be able to ``cargo test`` as part of the test
+  suite, although that does not generate installable artifacts.