README: Describe building with Meson and Autotools

and remove the description of the directory structure,
which is not very useful.

1 files changed, 84 insertions, 28 deletions

diff --git a/README b/README
index 5515a7d..a6e36d2 100644
--- a/README
+++ b/README
@@ -1,6 +1,5 @@
 libsigc++ -- The Typesafe Callback Framework for C++
 
-
 General information:
 
    libsigc++ implements a typesafe callback system for standard C++. It
@@ -14,15 +13,12 @@ General information:
    Further information is available on the libsigc++ project home page:
    https://libsigcplusplus.github.io/libsigcplusplus/
 
-
 License information:
 
    Distribution of library and components is under the LGPL as listed in the
    file COPYING. Examples and tests are Public Domain.
 
-
 Contact information:
-   Maintainer: mailto: murrayc@murrayc.com
    Maillist: mailto: libsigc-list@gnome.org
    Homepage: https://libsigcplusplus.github.io/libsigcplusplus/
    Online reference documentation: https://developer.gnome.org/libsigc++/unstable/
@@ -31,34 +27,94 @@ Contact information:
    Git: https://github.com/libsigcplusplus/libsigcplusplus
    Bug reports: https://github.com/libsigcplusplus/libsigcplusplus/issues
 
+Compatibility:
 
-Overview of the distribution:
+   Compatible compilers must support C++11, such as the decltype() specifier.
 
-   docs/                             documentation on the signal system
-      docs/reference/                reference documentation
-   
-   examples/                         examples of various signal functions
-   
-   sigc++/                           source for library
-      sigc++/macros/                 .m4 files used to auto-generate source files
-      sigc++/functors/               source for library (various functors)
-      sigc++/functors/macros/        .m4 files used to auto-generate source files
-      sigc++/adaptors/               source for library (various adaptors)
-      sigc++/adaptors/macros/        .m4 files used to auto-generate source files
-   
-   build/                            auxiliary files for building with Autotools
+   All releases are tested with the gcc (g++) compiler.
 
-   untracked/                        auxiliary files for building with Meson
-                                     See untracked/README
-   
-   tests/                            programs testing and verifying proper behaviour
-   
-   MSVC_NMake/                       NMake Makefiles for building the library with MSVC++ 2013 and later
-                                     See MSVC_NMake/README.txt
+# Building
 
+Whenever possible, you should use the official binary packages approved by the
+supplier of your operating system, such as your Linux distribution.
 
-Compatibility:
+## Building on Windows
 
-   Compatible compilers must support C++11, such as the decltype() specifier.
+See MSVC_NMake/README.txt.
 
-   All releases are tested with the gcc (g++) compiler.
+## Building from a release tarball
+
+It's easiest to build with Meson, if the tarball was made with Meson,
+and to build with Autotools, if the tarball was made with Autotools.
+Then you don't have to use maintainer-mode.
+
+How do you know how the tarball was made? If it was made with Meson,
+it contains files in untracked/build_scripts/, untracked/docs/ and possibly
+other subdirectories of untracked/.
+
+### Building from a tarball with Meson
+
+Don't call the builddir 'build'. There is a directory called 'build' with
+files used by Autotools.
+
+If the tarball was made with Autotools, you must enable maintainer-mode:
+  $ meson --prefix=/some_directory --libdir=lib -Dmaintainer-mode=true your_builddir .
+If the tarball was made with Meson:
+  $ meson --prefix=/some_directory --libdir=lib your_builddir .
+
+Then
+  $ cd your_builddir
+  $ ninja
+  $ ninja install
+You can run the tests like so:
+  $ ninja test
+
+### Building from a tarball with Autotools
+
+If the tarball was made with Autotools:
+  $ ./configure --prefix=/some_directory
+If the tarball was made with Meson, you must enable maintainer-mode:
+  $ ./autogen.sh --prefix=/some_directory
+
+Then
+  $ make
+  $ make install
+You can build the examples and tests, and run the tests, like so:
+  $ make check
+
+## Building from git
+
+Building from git can be difficult so you should prefer building from
+a release tarball unless you need to work on the libsigc++ code itself.
+
+jhbuild can be a good help
+  https://gitlab.gnome.org/GNOME/jhbuild
+  https://wiki.gnome.org/Projects/Jhbuild
+
+### Building from git with Meson
+
+Maintainer-mode is enabled by default when you build from a git clone.
+
+Don't call the builddir 'build'. There is a directory called 'build' with
+files used by Autotools.
+
+  $ meson --prefix=/some_directory --libdir=lib your_builddir .
+  $ cd your_builddir
+  $ ninja
+  $ ninja install
+You can run the tests like so:
+  $ ninja test
+You can create a tarball like so:
+  $ ninja dist
+
+### Building from git with Autotools
+
+  $ ./autogen.sh --prefix=/some_directory
+  $ make
+  $ make install
+You can build the examples and tests, and run the tests, like so:
+  $ make check
+You can create a tarball like so:
+  $ make distcheck
+or
+  $ make dist