+ added hello/ : demonstrate use of autotools utilities for Pd externals

svn path=/trunk/externals/moocow/; revision=10768

1 files changed, 260 insertions, 0 deletions

diff --git a/hello/README.pod b/hello/README.pod
new file mode 100644
index 0000000..8941f49
--- /dev/null
+++ b/hello/README.pod
@@ -0,0 +1,260 @@
+=pod
+
+README for example pd external package 'hello'
+
+Last updated for hello v0.01
+
+=head1 DESCRIPTION
+
+The 'hello' package is an example external package intended
+to demonstrate one way of using GNU autotools (automake, autoconf, autoheader)
+to manage a Pd external distribution.
+
+See L</"HOWTO"> for a developer-oriented introduction.
+
+
+=head1 INSTALLATION
+
+Issue the following commands to the shell:
+
+   cd PACKAGE-XX.YY  (or wherever you extracted the distribution)
+   ./configure
+   make
+   make install
+
+=head1 CONFIGURATION OPTIONS
+
+The 'configure' script supports the following options, among others:
+
+=over 4
+
+=item * --help
+
+Output a brief usage summary of the 'configure' script,
+including a list of supported options and influential
+environment variables.
+
+=item * --enable-debug , --disable-debug
+
+Whether to enable verbose debugging messages.
+Default=no.
+
+=item * --with-pd-dir=PD_DIR
+
+Set base Pd directory.  Default PREFIX/pd
+
+=item * --with-pd-include=PD_INC
+
+Where to look for m_pd.h
+
+=item * --with-pd-extdir=PD_EXTERNS
+
+Where to install compiled externals.  Default: PD_DIR/externs
+
+=item * --enable-object-externals , --disable-object-externals
+
+Whether to build single-object externals or only multilibs (default),
+for packages which support both.
+
+=back
+
+
+=head1 HOWTO
+
+This section provides a brief developer-oriented description of
+how to use GNU autotools to manage your own Pd external package.
+
+=head2 Files
+
+=over 4
+
+=item $(top_srcdir)/m4
+
+The directory m4/ should be copied to your top-level package directory.
+See L</"ax_pd_external.m4"> for details.
+
+=item $(top_srcdir)/pdexternal.am
+
+The file pdexternal.am should be copied to your top-level package directory
+See L</"pdexternal.am"> for details.
+
+=item $(srcdir)/mooPdUtils.h (optional)
+
+The file mooPdUtils.h may be copied to your source-level directory.
+Currently, this only provides a PDEXT_UNUSED macro to avoid annoying
+gcc warnings under -W.
+
+=back
+
+
+=head2 Running aclocal
+
+You must pass the "-I m4" flag to aclocal when you call it.
+For maintainer-mode rebuilding and autoreconf, you should add
+the following to your top-level Makefile.am:
+
+ ACLOCAL_AMFLAGS = -I m4
+
+See the example package's autogen.sh for a useful wrapper script.
+
+
+=head2 configure.ac
+
+You must call the macro AX_PD_EXTERNAL from configure.ac.
+Before doing so (and before calling AC_PROG_CC), make sure
+that you cache the values of important user flags in shell
+variables:
+
+ ##-- save user's CFLAGS,CPPFLAGS
+ UCPPFLAGS="$CPPFLAGS"
+ UCFLAGS="$CFLAGS"
+ ULDFLAGS="$LDFLAGS"
+
+ ##-- Pd external stuff
+ AX_PD_EXTERNAL
+
+See the example package's configure.ac for a complete working example.
+
+
+=head2 Makefile.am
+
+You probably want to include $(top_srcdir)/pdexternal.am in
+your Makefile.am(s).  This will allow you to build Pd externals
+as "_PROGRAMS" targets.  In particular, pdext_PROGRAMS targets
+will be built as externals and installed in PDEXT_DIR (see above).
+
+See the example package's Makefile.am for a complete working example.
+
+=over 4
+
+=item Externals
+
+To build & install the external "hello.$(PDEXT)", add the
+following to Makefile.am:
+
+ pdexterns_PROGRAMS = hello
+ hello_SOURCES = hello.c mooPdUtils.h
+
+=item Abstractions
+
+To install the abstraction "heynow.pd", add the
+following to Makefile.am:
+
+ pdexterns_DATA = heynow.pd
+
+=item Documentation
+
+To install the documentation patch "hello-help.pd", add the
+following to Makefile.am:
+
+ pddoc_DATA = hello-help.pd
+
+=back
+
+=cut
+
+=pod
+
+=head2 ax_pd_external.m4
+
+The AX_PD_EXTERNAL macro defined in m4/ax_pd_external.m4
+is intended to perform all common autoconf-level
+checks and substitutions necessary for building Pd external packages on
+various systems.  Among other things, this includes:
+
+=over 4
+
+=item *
+
+Providing --with-FEATURE and --enable-FEATURE arguments such as
+--with-pd-dir (see L</"CONFIGURATION OPTIONS">, above).
+
+=item *
+
+Defining automake-style "Xdir" variables for easy definition
+of package externals, abstractions, and documentation.
+
+=item *
+
+Checking for the required header "m_pd.h".
+
+=item *
+
+Defining platform-dependent compiler and linker flags for
+building Pd externals, and adding these to the relevant
+system variables (CPPFLAGS, CFLAGS, LDFLAGS, etc.)
+
+=back
+
+See the comments at the top of m4/ax_pd_external.m4 for
+more details on the AX_PD_EXTERNAL macro.
+
+
+=head2 pdexternal.am
+
+pdexternal.am is intended to be included in your package's Makefile.am.
+It redefines the automake EXEEXT to allow building Pd externals using
+automake's _PROGRAMS targets.  Additionally, it defines the
+automake varibles PDEXT, SUFFIXES, EXTRA_DIST, CLEANFILES, DISTCLEANFILES,
+and MAINTAINERCLEANFILES.
+
+
+=head2 Multilibs and Single-Object Externals
+
+You can use automake's EXTRA_PROGRAMS variable, together
+with the pdexterns_PROGRAMS automake target, the automake conditional
+WANT_OBJECT_EXTERNALS, and the C preprocessor macro WANT_OBJECT_EXTERNALS
+to allow building single-object-externals or multilibs from a single
+source distribution.
+
+Makefile.am should contain something like:
+
+ ##-- always build these externals
+ pdexterns_PROGRAMS = hello
+
+ ##-- potential single-object externals (as _PROGRAMS)
+ EXTRA_PROGRAMS = goodbye
+
+ ##-- build single-object externals?
+ if WANT_OBJECT_EXTERNALS
+  pdexterns_PROGRAMS += goodbye
+ endif
+
+If single-object externals were requested by the user,
+then the C preprocessor macro WANT_OBJECT_EXTERNALS will be defined
+by autoheader, to allow you to
+conditionally #include<> the EXTRA_PROGRAMS sources in your
+top-level multilib source file if desired.  In the above example,
+hello.c might contain:
+
+ #ifdef HAVE_CONFIG_H
+ # include "config.h"
+ #endif
+
+ #ifndef WANT_OBJECT_EXTERNALS
+ /*-- Multilib build: include source for the goodbye external --*/
+ # include "goodbye.c"
+ #endif
+
+ /*... local definitions etc. go here ...*/
+
+ void hello_setup(void)
+ {
+  #ifndef WANT_OBJECT_EXTERNALS
+   goodbye_setup();
+  #endif
+
+  /*... local setup code goes here ...*/
+ }
+
+=cut
+
+=pod
+
+=head1 ACKNOWLEDGEMENTS
+
+PD by Miller Puckette and others.
+
+=head1 AUTHOR
+
+Bryan Jurish E<lt>moocow@ling.uni-potsdam.deE<gt>