diff options
| author | Bryan Jurish <mukau@users.sourceforge.net> | 2009-02-14 20:34:47 +0000 |
|---|---|---|
| committer | Bryan Jurish <mukau@users.sourceforge.net> | 2009-02-14 20:34:47 +0000 |
| commit | c3764252f3c566cdd0f325eac2401378ab92775f (patch) | |
| tree | b6b0563c459d192c7b1910b8a591e0c481fbe2c0 /hello/README.html | |
| parent | 4f69b08833151fab744e64a16ae8016a123fa929 (diff) | |
+ added hello/ : demonstrate use of autotools utilities for Pd externals
svn path=/trunk/externals/moocow/; revision=10768
Diffstat (limited to 'hello/README.html')
| -rw-r--r-- | hello/README.html | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/hello/README.html b/hello/README.html new file mode 100644 index 0000000..8f0d7a2 --- /dev/null +++ b/hello/README.html @@ -0,0 +1,277 @@ +<?xml version="1.0" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>DESCRIPTION</title> +<meta http-equiv="content-type" content="text/html; charset=utf-8" /> +<link rev="made" href="mailto:root@localhost" /> +</head> + +<body style="background-color: white"> + +<p><a name="__index__"></a></p> +<!-- INDEX BEGIN --> + +<ul> + + <li><a href="#description">DESCRIPTION</a></li> + <li><a href="#installation">INSTALLATION</a></li> + <li><a href="#configuration_options">CONFIGURATION OPTIONS</a></li> + <li><a href="#howto">HOWTO</a></li> + <ul> + + <li><a href="#files">Files</a></li> + <li><a href="#running_aclocal">Running aclocal</a></li> + <li><a href="#configure_ac">configure.ac</a></li> + <li><a href="#makefile_am">Makefile.am</a></li> + <li><a href="#ax_pd_external_m4">ax_pd_external.m4</a></li> + <li><a href="#pdexternal_am">pdexternal.am</a></li> + <li><a href="#multilibs_and_singleobject_externals">Multilibs and Single-Object Externals</a></li> + </ul> + + <li><a href="#acknowledgements">ACKNOWLEDGEMENTS</a></li> + <li><a href="#author">AUTHOR</a></li> +</ul> +<!-- INDEX END --> + +<hr /> +<p>README for example pd external package 'hello'</p> +<p>Last updated for hello v0.01</p> +<p> +</p> +<hr /> +<h1><a name="description">DESCRIPTION</a></h1> +<p>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.</p> +<p>See <a href="#howto">HOWTO</a> for a developer-oriented introduction.</p> +<p> +</p> +<hr /> +<h1><a name="installation">INSTALLATION</a></h1> +<p>Issue the following commands to the shell:</p> +<pre> + cd PACKAGE-XX.YY (or wherever you extracted the distribution) + ./configure + make + make install</pre> +<p> +</p> +<hr /> +<h1><a name="configuration_options">CONFIGURATION OPTIONS</a></h1> +<p>The 'configure' script supports the following options, among others:</p> +<ul> +<li><strong><a name="item__2d_2dhelp">--help</a></strong> + +<p>Output a brief usage summary of the 'configure' script, +including a list of supported options and influential +environment variables.</p> +</li> +<li><strong><a name="item__2d_2denable_2ddebug__2c__2d_2ddisable_2ddebug">--enable-debug , --disable-debug</a></strong> + +<p>Whether to enable verbose debugging messages. +Default=no.</p> +</li> +<li><strong><a name="item__2d_2dwith_2dpd_2ddir_3dpd_dir">--with-pd-dir=PD_DIR</a></strong> + +<p>Set base Pd directory. Default PREFIX/pd</p> +</li> +<li><strong><a name="item__2d_2dwith_2dpd_2dinclude_3dpd_inc">--with-pd-include=PD_INC</a></strong> + +<p>Where to look for m_pd.h</p> +</li> +<li><strong><a name="item__2d_2dwith_2dpd_2dextdir_3dpd_externs">--with-pd-extdir=PD_EXTERNS</a></strong> + +<p>Where to install compiled externals. Default: PD_DIR/externs</p> +</li> +<li><strong><a name="item__2d_2denable_2dobject_2dexternals__2c__2d_2ddisabl">--enable-object-externals , --disable-object-externals</a></strong> + +<p>Whether to build single-object externals or only multilibs (default), +for packages which support both.</p> +</li> +</ul> +<p> +</p> +<hr /> +<h1><a name="howto">HOWTO</a></h1> +<p>This section provides a brief developer-oriented description of +how to use GNU autotools to manage your own Pd external package.</p> +<p> +</p> +<h2><a name="files">Files</a></h2> +<dl> +<dt><strong><a name="item___top_srcdir__m4">$(top_srcdir)/m4</a></strong></dt> + +<dd> +<p>The directory m4/ should be copied to your top-level package directory. +See <a href="#ax_pd_external_m4">ax_pd_external.m4</a> for details.</p> +</dd> +<dt><strong><a name="item___top_srcdir__pdexternal_am">$(top_srcdir)/pdexternal.am</a></strong></dt> + +<dd> +<p>The file pdexternal.am should be copied to your top-level package directory +See <a href="#pdexternal_am">pdexternal.am</a> for details.</p> +</dd> +<dt><strong><a name="item_h">$(srcdir)/mooPdUtils.h (optional)</a></strong></dt> + +<dd> +<p>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.</p> +</dd> +</dl> +<p> +</p> +<h2><a name="running_aclocal">Running aclocal</a></h2> +<p>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:</p> +<pre> + ACLOCAL_AMFLAGS = -I m4</pre> +<p>See the example package's autogen.sh for a useful wrapper script.</p> +<p> +</p> +<h2><a name="configure_ac">configure.ac</a></h2> +<p>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:</p> +<pre> + ##-- save user's CFLAGS,CPPFLAGS + UCPPFLAGS="$CPPFLAGS" + UCFLAGS="$CFLAGS" + ULDFLAGS="$LDFLAGS"</pre> +<pre> + ##-- Pd external stuff + AX_PD_EXTERNAL</pre> +<p>See the example package's configure.ac for a complete working example.</p> +<p> +</p> +<h2><a name="makefile_am">Makefile.am</a></h2> +<p>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).</p> +<p>See the example package's Makefile.am for a complete working example.</p> +<dl> +<dt><strong><a name="item_externals">Externals</a></strong></dt> + +<dd> +<p>To build & install the external ``hello.$(PDEXT)'', add the +following to Makefile.am:</p> +<pre> + pdexterns_PROGRAMS = hello + hello_SOURCES = hello.c mooPdUtils.h</pre> +</dd> +<dt><strong><a name="item_abstractions">Abstractions</a></strong></dt> + +<dd> +<p>To install the abstraction ``heynow.pd'', add the +following to Makefile.am:</p> +<pre> + pdexterns_DATA = heynow.pd</pre> +</dd> +<dt><strong><a name="item_documentation">Documentation</a></strong></dt> + +<dd> +<p>To install the documentation patch ``hello-help.pd'', add the +following to Makefile.am:</p> +<pre> + pddoc_DATA = hello-help.pd</pre> +</dd> +</dl> +<p> +</p> +<h2><a name="ax_pd_external_m4">ax_pd_external.m4</a></h2> +<p>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:</p> +<ul> +<li> +<p>Providing --with-FEATURE and --enable-FEATURE arguments such as +--with-pd-dir (see <a href="#configuration_options">CONFIGURATION OPTIONS</a>, above).</p> +</li> +<li> +<p>Defining automake-style ``Xdir'' variables for easy definition +of package externals, abstractions, and documentation.</p> +</li> +<li> +<p>Checking for the required header ``m_pd.h''.</p> +</li> +<li> +<p>Defining platform-dependent compiler and linker flags for +building Pd externals, and adding these to the relevant +system variables (CPPFLAGS, CFLAGS, LDFLAGS, etc.)</p> +</li> +</ul> +<p>See the comments at the top of m4/ax_pd_external.m4 for +more details on the AX_PD_EXTERNAL macro.</p> +<p> +</p> +<h2><a name="pdexternal_am">pdexternal.am</a></h2> +<p>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.</p> +<p> +</p> +<h2><a name="multilibs_and_singleobject_externals">Multilibs and Single-Object Externals</a></h2> +<p>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.</p> +<p>Makefile.am should contain something like:</p> +<pre> + ##-- always build these externals + pdexterns_PROGRAMS = hello</pre> +<pre> + ##-- potential single-object externals (as _PROGRAMS) + EXTRA_PROGRAMS = goodbye</pre> +<pre> + ##-- build single-object externals? + if WANT_OBJECT_EXTERNALS + pdexterns_PROGRAMS += goodbye + endif</pre> +<p>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:</p> +<pre> + #ifdef HAVE_CONFIG_H + # include "config.h" + #endif</pre> +<pre> + #ifndef WANT_OBJECT_EXTERNALS + /*-- Multilib build: include source for the goodbye external --*/ + # include "goodbye.c" + #endif</pre> +<pre> + /*... local definitions etc. go here ...*/</pre> +<pre> + void hello_setup(void) + { + #ifndef WANT_OBJECT_EXTERNALS + goodbye_setup(); + #endif</pre> +<pre> + /*... local setup code goes here ...*/ + }</pre> +<p> +</p> +<hr /> +<h1><a name="acknowledgements">ACKNOWLEDGEMENTS</a></h1> +<p>PD by Miller Puckette and others.</p> +<p> +</p> +<hr /> +<h1><a name="author">AUTHOR</a></h1> +<p>Bryan Jurish <<a href="mailto:moocow@ling.uni-potsdam.de">moocow@ling.uni-potsdam.de</a>></p> + +</body> + +</html> |