wingo pushed a commit to branch wip-whippet
in repository guile.
commit 63f52b635b3b2f672eed3c5e9d7796e04d0e0fe3
Author: Andy Wingo <wi...@igalia.com>
AuthorDate: Thu Apr 10 13:39:29 2025 +0200
Add some text about autotools
---
doc/manual.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 69 insertions(+), 2 deletions(-)
diff --git a/doc/manual.md b/doc/manual.md
index a6742cbe5..14577932d 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -201,8 +201,10 @@ compiling user code.
### Compiling the collector
As an embed-only library, Whippet needs to be integrated into the build
-system of its host (embedder). Currently the only supported build
-system uses GNU make. We would be happy to add other systems over time.
+system of its host (embedder). There are two build systems supported
+currently; we would be happy to add other systems over time.
+
+#### GNU make
At a high level, first the embedder chooses a collector and defines how
to specialize the collector against the embedder. Whippet's `embed.mk`
@@ -253,6 +255,71 @@ remove any overhead imposed by the division of code into
separate
compilation units. `embed.mk` includes the necessary LTO flags in
`GC_CFLAGS` and `GC_LDFLAGS`.
+#### GNU Autotools
+
+To use Whippet from an autotools project, the basic idea is to include a
+`Makefile.am` snippet from the subdirectory containing the Whippet
+checkout. That will build `libwhippet.la`, which you should link into
+your binary. There are some `m4` autoconf macros that need to be
+invoked, for example to select the collector.
+
+Let us imagine you have checked out Whippet in `whippet/`. Let us also
+assume for the moment that we are going to build `mt-gcbench`, a program
+included in Whippet itself.
+
+A top-level autoconf file (`configure.ac`) might look like this:
+
+```autoconf
+AC_PREREQ([2.69])
+AC_INIT([whippet-autotools-example],[0.1.0])
+AC_CONFIG_SRCDIR([whippet/benchmarks/mt-gcbench.c])
+AC_CONFIG_AUX_DIR([build-aux])
+AC_CONFIG_MACRO_DIRS([m4 whippet])
+AM_INIT_AUTOMAKE([subdir-objects foreign])
+
+WHIPPET_ENABLE_LTO
+
+LT_INIT
+
+WARN_CFLAGS=-Wall
+AC_ARG_ENABLE([Werror],
+ AS_HELP_STRING([--disable-Werror],
+ [Don't stop the build on errors]),
+ [],
+ WARN_CFLAGS="-Wall -Werror")
+CFLAGS="$CFLAGS $WARN_CFLAGS"
+
+WHIPPET_PKG
+
+AC_CONFIG_FILES(Makefile)
+AC_OUTPUT
+```
+
+Then your `Makefile.am` might look like this:
+
+```automake
+noinst_LTLIBRARIES =
+WHIPPET_EMBEDDER_CPPFLAGS = -include whippet/benchmarks/mt-gcbench-embedder.h
+include whippet/embed.am
+
+noinst_PROGRAMS = whippet/benchmarks/mt-gcbench
+
+AM_CFLAGS = $(WHIPPET_CPPFLAGS) $(WHIPPET_CFLAGS)
$(WHIPPET_TO_EMBEDDER_CPPFLAGS)
+LDADD = libwhippet.la
+```
+
+To actually build, you do the usual autotools dance:
+
+```bash
+autoreconf -vif && ./configure && make
+```
+
+See `./configure --help` for a list of user-facing options. Before the
+`WHIPPET_PKG`, you can run e.g. `WHIPPET_PKG_COLLECTOR(mmc)` to set the
+default collector to `mmc`; if you don't do that, the default collector
+is `pcc`. There are also `WHIPPET_PKG_DEBUG`, `WHIPPET_PKG_TRACING`,
+and `WHIPPET_PKG_PLATFORM`; see `whippet.m4` for more details.
+
#### Compile-time options
There are a number of pre-processor definitions that can parameterize
