ax_python_embed
===============

Synopsis
********

     AX_PYTHON_DEFAULT
     AX_PYTHON_ENABLE
     AX_PYTHON_WITH
     AX_PYTHON_PATH
     AX_PYTHON_VERSION_ENSURE( [2.2] )
     AX_PYTHON_CSPEC
     AX_PYTHON_LSPEC

Description
***********

This file provides autoconf support for those applications that want to embed python. It supports all pythons >= 2.2 which is the first official release containing distutils. Version 2.2 of python was released December 21, 2001. Since it actually executes the python, cross platform configuration will probably not work. Also, most of the platforms supported are consistent until you look into Mac OS X. The python included with it is installed as a framework which is a very different environment to set up the normal tools such as gcc and libtool to deal with. Therefore, once we establish which python that we are going to use, we use its distutils to actually compile and link our modules or applications.

At this time, it does NOT support linking with Python statically. It does support dynamic linking.

This set of macros help define $PYTHON, $PYTHON_USE, $PYTHON_CSPEC and $PYTHON_LSPEC. $PYTHON defines the full executable path for the Python being linked to and is used within these macros to determine if that has been specified or found. These macros do execute this python version so it must be present on the system at configure time.

$PYTHON_USE is an automake variable that defines whether Python support should be included or not in your application. $PYTHON_CSPEC is a variable that supplies additional CFLAGS for the compilation of the application/shared library. $PYTHON_LSPEC is a variable that supplies additional LDFLAGS for linking the application/shared library.

The following is an example of how to set up for python usage within your application in your configure.in:

       AX_PYTHON_DEFAULT( )
       AX_PYTHON_ENABLE( )             # Optional
       AX_PYTHON_WITH( )               # Optional
       AX_PYTHON_PATH( )               # or AX_PYTHON_INSIST( )
       # if $PYTHON is not defined, then the following do nothing.
       AX_PYTHON_VERSION_ENSURE( [2.2] )
       AX_PYTHON_CSPEC
       AX_PYTHON_LSPEC

The AX_PYTHON_DEFAULT sets the $PYTHON_USE to false. Thereby, excluding it if it was optional.

The AX_PYTHON_ENABLE looks for the optional configure parameters of --enable-python/--disable-python and establishes the $PYTHON and $PYTHON_USE variables accordingly.

The AX_PYTHON_WITH looks for the optional configure parameters of --with-python/--without-python and establishes the $PYTHON and $PYTHON_USE variables accordingly.

The AX_PYTHON_PATH looks for python assuming that none has been previously found or defined and issues an error if it does not find it. If it does find it, it establishes the $PYTHON and $PYTHON_USE variables accordingly. AX_PYTHON_INSIST could be used here instead if you want to insist that Python support be included using the --enable-python or --with-python checks previously done.

The AX_PYTHON_VERSION_ENSURE issues an error if the Python previously found is not of version 2.2 or greater.

Once that these macros have be run, we can use PYTHON_USE within the makefile.am file to conditionally add the Python support such as:

Makefile.am example showing optional inclusion of directories:

      if PYTHON_USE
      plugins = plugins
      src = src
      else
      plugins =
      src =
      endif

      SUBDIRS = . $(plugins) $(src)

Makefile.am example showing optional shared library build:

      if PYTHON_USE
      lib_LTLIBRARIES        = libElemList.la
      libElemList_la_SOURCES = libElemList.c
      libElemList_la_CFLAGS  = @PYTHON_CSPEC@
      libElemList_la_LDFLAGS = @PYTHON_LSPEC@
      endif

Makefile.am example showing optional program build:

      if PYTHON_USE
      bin_PROGRAMS    = runFunc
      runFunc_SOURCES = runFunc.c
      runFunc_CFLAGS  = @PYTHON_CSPEC@
      runFunc_LDFLAGS = @PYTHON_LSPEC@
      endif

The above compiles the modules only if PYTHON_USE was specified as true. Also, the else portion of the if was optional.

Source Code
***********

Download the latest version of ax_python_embed.m4 (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_python_embed.m4) or browse the macro's revision history (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=history;f=m4/ax_python_embed.m4).

License
*******

Copyright © 2008 Robert White kranki@mac.com
 Copyright © 2008 Dustin J. Mitchell dustin@cs.uchicago.edu

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.