aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--hello/README.txt191
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>
+