Add README.git-buildmsg

3 files changed, 50 insertions, 0 deletions

diff --git a/git-buildmsg/Makefile-files b/git-buildmsg/Makefile-files
index 05938a2..ad5bcc5 100644
--- a/git-buildmsg/Makefile-files
+++ b/git-buildmsg/Makefile-files
@@ -7,6 +7,8 @@ TESTS += git-buildmsg-test
 check_PROGRAMS += git-buildmsg-test
 nodist_git_buildmsg_test_SOURCES = git-buildmsg/git-buildmsg-test.c
 
+dist_doc_DATA +=  git-buildmsg/README.git-buildmsg
+
 BUILT_SOURCES += git-buildmsg/git-buildmsg-test.c
 CLEANFILES    += git-buildmsg/git-buildmsg-test.c
 git-buildmsg/git-buildmsg-test.c: git-buildmsg/git-buildmsg
diff --git a/git-buildmsg/README.git-buildmsg b/git-buildmsg/README.git-buildmsg
new file mode 100644
index 0000000..c95f5e7
--- /dev/null
+++ b/git-buildmsg/README.git-buildmsg
@@ -0,0 +1,44 @@
+========================================================================
+How to hook it into automake-based builds:
+========================================================================
+
+---[ BEGIN top-level Makefile.am ]---
+EXTRA_DIST += git-buildmsg
+---[ END top-level Makefile.am ]---
+
+---[ BEGIN Makefile.am where information is needed ]---
+BUILT_SOURCES += git-buildmsgstamp
+GIT_BUILDMSG_CMD = $(SHELL) "$(top_srcdir)/git-buildmsg"
+GIT_BUILDMSG_H = git-buildmsg.h
+CLEANFILES += $(GIT_BUILDMSG_H)
+git_version.stamp:
+	env GIT_DIR="$(top_srcdir)/.git" $(GIT_VERSION_CMD) -s "$(top_srcdir)" -o "$(GIT_BUILDMSG_H)"
+	@if test -s "$(srcdir)/$(GIT_BUILDMSG_H)"; then \
+		if cmp "$(srcdir)/$(GIT_BUILDMSG_H)" "$(GIT_BUILDMSG_H)"; then :; \
+		else \
+			echo "Error: $(srcdir)/$(GIT_BUILDMSG_H) and $(GIT_BUILDMSG_H) differ."; \
+			echo "       You probably want to remove the former."; \
+			exit 1; \
+		fi; \
+	fi
+
+bin_PROGRAMS += foo
+foo_SOURCES = foo.c
+ndist_foo_SOURCES = $(GIT_BUILDMSG_H)
+---[ END Makefile.am where information is needed ]---
+
+
+========================================================================
+How to hook it into imake-based builds:
+========================================================================
+
+---[ BEGIN Imakefile ]---
+GIT_VERSION_CMD = $(SHELL) $(TOP)/git-buildmsg
+GIT_DEFINES = `env GIT_DIR="$(TOP)/.git" $(GIT_VERSION_CMD) -s $(TOP) -o git-buildmsg.h`
+
+clean::
+	RemoveFile(git-buildmsg.h)
+---[ END Imakefile ]---
+
+Then make sure that the DEFINES the C compiler is run with includes
+$(GIT_DEFINES).
diff --git a/git-buildmsg/git-buildmsg.in b/git-buildmsg/git-buildmsg.in
index e4fb512..7cb53dd 100644
--- a/git-buildmsg/git-buildmsg.in
+++ b/git-buildmsg/git-buildmsg.in
@@ -31,6 +31,10 @@
 #     && ./moo
 #   (bash and other seds should also do)
 #
+# Note:
+#   A man page for this script does NOT make sense. It is supposed to be
+#   copied into and shipped with other peoples' source trees.
+#
 # Ideas:
 #  * Output for languages other than C (Erlang, Python, Perl, sh, ...)