+ added README.txt

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

1 files changed, 191 insertions, 0 deletions

diff --git a/hello/README.txt b/hello/README.txt
new file mode 100644
index 0000000..e4e5b97
--- /dev/null
+++ b/hello/README.txt
@@ -0,0 +1,191 @@
+    README for example pd external package 'hello'
+
+    Last updated for hello v0.01
+
+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 "HOWTO" for a developer-oriented introduction.
+
+INSTALLATION
+    Issue the following commands to the shell:
+
+       cd PACKAGE-XX.YY  (or wherever you extracted the distribution)
+       ./configure
+       make
+       make install
+
+CONFIGURATION OPTIONS
+    The 'configure' script supports the following options, among others:
+
+    * --help
+        Output a brief usage summary of the 'configure' script, including a
+        list of supported options and influential environment variables.
+
+    * --enable-debug , --disable-debug
+        Whether to enable verbose debugging messages. Default=no.
+
+    * --with-pd-dir=PD_DIR
+        Set base Pd directory. Default PREFIX/pd
+
+    * --with-pd-include=PD_INC
+        Where to look for m_pd.h
+
+    * --with-pd-extdir=PD_EXTERNS
+        Where to install compiled externals. Default: PD_DIR/externs
+
+    * --enable-object-externals , --disable-object-externals
+        Whether to build single-object externals or only multilibs
+        (default), for packages which support both.
+
+HOWTO
+    This section provides a brief developer-oriented description of how to
+    use GNU autotools to manage your own Pd external package.
+
+  Files
+    $(top_srcdir)/m4
+        The directory m4/ should be copied to your top-level package
+        directory. See "ax_pd_external.m4" for details.
+
+    $(top_srcdir)/pdexternal.am
+        The file pdexternal.am should be copied to your top-level package
+        directory See "pdexternal.am" for details.
+
+    $(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.
+
+  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.
+
+  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.
+
+  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.
+
+    Externals
+        To build & install the external "hello.$(PDEXT)", add the following
+        to Makefile.am:
+
+         pdexterns_PROGRAMS = hello
+         hello_SOURCES = hello.c mooPdUtils.h
+
+    Abstractions
+        To install the abstraction "heynow.pd", add the following to
+        Makefile.am:
+
+         pdexterns_DATA = heynow.pd
+
+    Documentation
+        To install the documentation patch "hello-help.pd", add the
+        following to Makefile.am:
+
+         pddoc_DATA = hello-help.pd
+
+  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:
+
+    *   Providing --with-FEATURE and --enable-FEATURE arguments such as
+        --with-pd-dir (see "CONFIGURATION OPTIONS", above).
+
+    *   Defining automake-style "Xdir" variables for easy definition of
+        package externals, abstractions, and documentation.
+
+    *   Checking for the required header "m_pd.h".
+
+    *   Defining platform-dependent compiler and linker flags for building
+        Pd externals, and adding these to the relevant system variables
+        (CPPFLAGS, CFLAGS, LDFLAGS, etc.)
+
+    See the comments at the top of m4/ax_pd_external.m4 for more details on
+    the AX_PD_EXTERNAL macro.
+
+  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.
+
+  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 ...*/
+     }
+
+ACKNOWLEDGEMENTS
+    PD by Miller Puckette and others.
+
+AUTHOR
+    Bryan Jurish <moocow@ling.uni-potsdam.de>
+