diff options
Diffstat (limited to 'hello/README.pod')
-rw-r--r-- | hello/README.pod | 260 |
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> |