Installing documentation and examples

[Mark Wielaard <mwielaard at redhat dot com>]

Hi,

I changed the build so that documentation, examples, samples and demos
are installed by default. This seems somewhat more user friendly than
only doing it for the rpm target. The rpm spec files has been changed to
pick up the installed doc dir and move those into the special doc dir
target instead of relying on the dist tarbal containing them.

It seems to work fine for me. But this is my first spec file hacking, so
please yell and scream if things don't look/work correctly.

Thanks,

Mark

diff --git a/ChangeLog b/ChangeLog
index 7f90771..871b509 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2008-07-07  Mark Wielaard  <mwielaard@redhat.com>
+
+	* stapex.5.in: Add section on installed examples, samples and demos
+	and how they are documented.
+
+2008-07-07  Mark Wielaard  <mwielaard@redhat.com>
+
+	* Makefile.am (install-data-hook): Install examples, demos and
+	samples.
+	(uninstall-local): Remove examples, demos and samples.
+	* Makefile.in: Regenerated.
+	* aclocal.m4: Likewise.
+	* systemtap.spec.in (%install): Move examples.
+	Don't copy over examples to src.
+	(testsuite): Don't include src/examples.
+
+2008-07-07  Mark Wielaard  <mwielaard@redhat.com>
+
+	* systemtap.spec.in (%install): Move installed pdf files.
+	(%files): Mark moved installed pdf as %doc files.
+
 2008-07-03  Frank Ch. Eigler  <fche@elastic.org>
 
 	* translate.cxx (translate_pass): Don't #include <linux/compile.h>.
diff --git a/Makefile.am b/Makefile.am
index 8333281..b603c64 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -155,32 +155,33 @@ EXTRA_DIST = auto_free.h buildrun.h elaborate.h loc2c.h session.h \
 	     dwarf_wrappers.h \
 	     git_version.h git_version.sh
 
-EXAMPLE_DEST_DIR = $(distdir)/examples
-SAMPLE_DEST_DIR = $(EXAMPLE_DEST_DIR)/samples
-
-EXAMPLE_SRC = $(srcdir)/testsuite/systemtap.examples
-
-SAMPLE_SRC = $(srcdir)/testsuite/systemtap.samples/iotask.stp \
-	     $(srcdir)/testsuite/systemtap.samples/kmalloc-stacks.stp \
-	     $(srcdir)/testsuite/systemtap.samples/kmalloc-top \
-	     $(srcdir)/testsuite/systemtap.samples/pfaults.stp \
-	     $(srcdir)/testsuite/systemtap.samples/profile.stp \
-	     $(srcdir)/testsuite/systemtap.samples/tcp_connections.stp \
-	     $(srcdir)/testsuite/systemtap.samples/topsys.stp
-
-dist-add-examples: $(EXAMPLE_SRC)
-	rm -rf $(EXAMPLE_DEST_DIR)
-	mkdir -p $(EXAMPLE_DEST_DIR)
-	cp -a $(EXAMPLE_SRC)/* $(EXAMPLE_DEST_DIR)/.
-
-# Copy some of the testsuite sample scripts to the distdir
-# 'examples/samples' directory.
-dist-add-samples: $(SAMPLE_SRC) dist-add-examples
-	rm -rf $(SAMPLE_DEST_DIR)
-	mkdir -p $(SAMPLE_DEST_DIR)
-	cp $(SAMPLE_SRC) $(SAMPLE_DEST_DIR)
-
-dist-hook: dist-add-samples dist-gitversion
+EXAMPLE_SOURCE_DIR = $(srcdir)/testsuite/systemtap.examples
+EXAMPLE_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/examples
+DEMO_SOURCE_DIR = $(srcdir)/testsuite/systemtap.examples/small_demos
+DEMO_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/examples/small_demos
+SAMPLE_SOURCE_DIR = $(srcdir)/testsuite/systemtap.samples
+SAMPLE_INSTALL_DIR = $(EXAMPLE_INSTALL_DIR)/samples
+
+EXAMPLE_SRC = $(EXAMPLE_SOURCE_DIR)/ChangeLog \
+	$(EXAMPLE_SOURCE_DIR)/README \
+	$(EXAMPLE_SOURCE_DIR)/*.stp \
+	$(EXAMPLE_SOURCE_DIR)/*.txt \
+	$(EXAMPLE_SOURCE_DIR)/*.meta
+
+DEMO_SRC = \
+	$(EXAMPLE_SOURCE_DIR)/small_demos/*.stp \
+	$(EXAMPLE_SOURCE_DIR)/small_demos/*.txt \
+	$(EXAMPLE_SOURCE_DIR)/small_demos/*.wav
+
+SAMPLE_SRC = $(SAMPLE_SOURCE_DIR)/iotask.stp \
+	$(SAMPLE_SOURCE_DIR)/kmalloc-stacks.stp \
+	$(SAMPLE_SOURCE_DIR)/kmalloc-top \
+	$(SAMPLE_SOURCE_DIR)/pfaults.stp \
+	$(SAMPLE_SOURCE_DIR)/profile.stp \
+	$(SAMPLE_SOURCE_DIR)/tcp_connections.stp \
+	$(SAMPLE_SOURCE_DIR)/topsys.stp
+
+dist-hook: dist-gitversion
 	find $(distdir) -name CVS -o -name '*~' -o -name '.#*' | xargs rm -rf
 	find $(distdir) -name '*.o' -o -name '*.ko' -o -name '*.cmd' -o -name '*.mod.c' -o -name '.??*' | xargs rm -rf
 	find $(distdir) -name 'stap' -o -name '*.log' -o -name '*.sum' -o -name 'site.exp' | xargs rm -rf
@@ -195,6 +196,12 @@ install-data-local:
 		do $(INSTALL_DATA) -D $$f $(DESTDIR)$(pkgdatadir)/runtime/uprobes/$$f; done)
 	(cd $(srcdir)/tapset; find . \( -name '*.stp' -o -name README \) -print \
 		| while read f; do $(INSTALL_DATA) -D $$f $(DESTDIR)$(pkgdatadir)/tapset/$$f; done)
+	$(MKDIR_P) $(EXAMPLE_INSTALL_DIR)
+	$(INSTALL_DATA) $(EXAMPLE_SRC) $(EXAMPLE_INSTALL_DIR)
+	$(MKDIR_P) $(DEMO_INSTALL_DIR)
+	$(INSTALL_DATA) $(DEMO_SRC) $(DEMO_INSTALL_DIR)
+	$(MKDIR_P) $(SAMPLE_INSTALL_DIR)
+	$(INSTALL_DATA) $(SAMPLE_SRC) $(SAMPLE_INSTALL_DIR)
 
 TEST_COV_DIR = coverage
 
@@ -222,6 +229,18 @@ uninstall-local:
 	rm -rf $(DESTDIR)$(libexecdir)/$(PACKAGE)
 	rm -rf $(DESTDIR)$(libdir)/$(PACKAGE)
 	-rm -rf $(DESTDIR)$(localstatedir)/cache/$(PACKAGE)
+	@list='$(EXAMPLE_SRC)'; for f in $$list; do p=`basename $$f`; \
+	  echo " rm -f '$(EXAMPLE_INSTALL_DIR)/$$p'"; \
+	  rm -f "$(EXAMPLE_INSTALL_DIR)/$$p"; \
+	done
+	@list='$(DEMO_SRC)'; for f in $$list; do p=`basename $$f`; \
+	  echo " rm -f '$(DEMO_INSTALL_DIR)/$$p'"; \
+	  rm -f "$(DEMO_INSTALL_DIR)/$$p"; \
+	done
+	@list='$(SAMPLE_SRC)'; for f in $$list; do p=`basename $$f`; \
+	  echo " rm -f '$(SAMPLE_INSTALL_DIR)/$$p'"; \
+	  rm -f "$(SAMPLE_INSTALL_DIR)/$$p"; \
+	done
 # XXX: leaves behind man pages
 
 SUBDIRS = testsuite doc
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 25eb61d..e4bc380 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,11 +1,24 @@
 # Makefile.am --- automake input file for systemtap docs
 ## process this file with automake to produce Makefile.in
 
+PDF_FILES = tutorial.pdf langref.pdf
+DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap
+
 if BUILD_DOCS
-all-local: tutorial.pdf langref.pdf
+all-local: $(PDF_FILES)
 
 clean-local:
 	rm -f *.pdf *.out *.log *.aux *.toc *.lot *.idx *.glo
+
+install-data-hook:
+	$(MKDIR_P) $(DOC_INSTALL_DIR)
+	$(INSTALL_DATA) $(PDF_FILES) $(DOC_INSTALL_DIR)
+
+uninstall-local:
+	@list='$(PDF_FILES)'; for p in $$list; do \
+	  echo " rm -f '$(DOC_INSTALL_DIR)/$$p'"; \
+	  rm -f "$(DOC_INSTALL_DIR)/$$p"; \
+	done
 endif
 
 SUFFIXES = ps pdf dvi ps tex
diff --git a/stapex.5.in b/stapex.5.in
index 2c9ecb6..e676326 100644
--- a/stapex.5.in
+++ b/stapex.5.in
@@ -106,6 +106,13 @@ To list the probeable functions in the kernel, use the listings mode.
 % stap \-l \[aq]kernel.function("*")\[aq]
 .ESAMPLE
 
+.SH MORE EXAMPLES
+
+Larger examples, demos and samples can be found in
+@prefix@/doc/systemtap*/examples, each example comes with either a .txt
+or .meta file explaining what the example, sample or demo does and how
+it is ordinarily run.
+
 .SH SEE ALSO
 .BR @prefix@/doc/systemtap*/examples
 .IR stap (1)
diff --git a/systemtap.spec.in b/systemtap.spec.in
index e663b15..1fdd65a 100644
--- a/systemtap.spec.in
+++ b/systemtap.spec.in
@@ -130,16 +130,19 @@ cd ..
 %configure %{?elfutils_config} %{sqlite_config} %{crash_config} %{docs_config}
 make %{?_smp_mflags}
 
+%install
+rm -rf ${RPM_BUILD_ROOT}
+make DESTDIR=$RPM_BUILD_ROOT install
+
+# We want the examples in the special doc dir, not the generoc doc install dir.
+mv $RPM_BUILD_ROOT%{_datadir}/doc/systemtap/examples examples
+
 # Fix paths in the example & testsuite scripts
 find examples testsuite -type f -name '*.stp' -print0 | xargs -0 sed -i -r -e '1s@^#!.+stap@#!%{_bindir}/stap@'
 
 # To avoid perl dependency, make perl sample script non-executable
 chmod -x examples/samples/kmalloc-top
 
-%install
-rm -rf ${RPM_BUILD_ROOT}
-make DESTDIR=$RPM_BUILD_ROOT install
-
 # Because "make install" may install staprun with mode 04111, the
 # post-processing programs rpmbuild runs won't be able to read it.
 # So, we change permissions so that they can read it.  We'll set the
@@ -148,8 +151,12 @@ chmod 755 $RPM_BUILD_ROOT%{_bindir}/staprun
 
 # Copy over the testsuite
 cp -rp testsuite $RPM_BUILD_ROOT%{_datadir}/systemtap
-mkdir $RPM_BUILD_ROOT%{_datadir}/%{name}/src
-cp -rp examples $RPM_BUILD_ROOT%{_datadir}/%{name}/src
+
+#%if %{with_docs}
+# We want the manuals in the special doc dir, not the generic doc install dir.
+mkdir docs.installed
+mv $RPM_BUILD_ROOT%{_datadir}/doc/systemtap/*.pdf docs.installed/
+#%endif
 
 %clean
 rm -rf ${RPM_BUILD_ROOT}
@@ -164,8 +171,7 @@ exit 0
 
 %doc README AUTHORS NEWS COPYING examples
 %if %{with_docs}
-%doc doc/tutorial.pdf
-%doc doc/langref.pdf
+%doc docs.installed/*.pdf
 %endif
 
 %{_bindir}/stap
@@ -196,7 +202,6 @@ exit 0
 
 %files testsuite
 %defattr(-,root,root)
-%{_datadir}/%{name}/src
 %{_datadir}/%{name}/testsuite