[Gsrc-commit] /srv/bzr/gsrc/trunk r943: add python config info to the docs

[Brandon Invergo]

------------------------------------------------------------
revno: 943
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Sat 2012-09-22 19:51:09 +0200
message:
  add python config info to the docs
modified:
  doc/gsrc.texi
  doc/version.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2012-09-01 14:34:09 +0000
+++ b/doc/gsrc.texi     2012-09-22 17:51:09 +0000
@@ -49,6 +49,7 @@
 * Introduction::                
 * Getting started::             
 * Advanced configuration::      
+* Appendix::
 * GNU Free Documentation License::  
 
 @detailmenu
@@ -71,6 +72,10 @@
 * Global configuration::
 * Package configuration::
 
+Appendix
+
+* Configuring Python packages
+
 @end detailmenu
 @end menu
 
@@ -382,7 +387,7 @@
 @end example
 
 
address@hidden Advanced configuration, GNU Free Documentation License, Getting 
started, Top
address@hidden Advanced configuration, Appendix, Getting started, Top
 @chapter Advanced configuration
 
 The default behavior of GSRC may be configured, both globally and for
@@ -500,7 +505,147 @@
 If the package requires a patch to even build properly, then this is a
 bug in GSRC. Please report such build problems to @email{bug-gsrc@@gnu.org}.
 
address@hidden GNU Free Documentation License,  , Advanced configuration, Top
address@hidden Appendix, GNU Free Documentation License, Advanced 
configuration, Top
address@hidden Appendix
+
address@hidden
+* Configuring Python packages::
address@hidden menu
+
address@hidden Configuring Python packages, , , Appendix
address@hidden Configuring Python packages
+
+Python packages are typically built using Python's distutils module or
+other similar methods. The result is a file called @file{setup.py},
+which the user runs, passing it directives similar to those passed to
+a standard Makefile. Creating a GSRC Makefile for a Python package is
+relatively uncomplicated, however it lacks the power of the
+traditional @file{configure}/@file{Makefile} paradigm. Furthermore,
+the GNU coding standards require a @file{configure} script when
+packaging a software release.
+
+In the interest of standardizing GSRC Makefiles for GNU packages as
+well as to provide maintainers of Python-based GNU packages an easy
+means of including standards-conforming @file{configure} and
address@hidden files, several files are included in GSRC for
+configuring Python projects. These files are located in the
address@hidden/python-configure/} directory in the GSRC package.
+
+The files may be included without modification in a Python project's
+directory. As such, they will provide a thin wrapper around the project's
address@hidden script. This configure script primarily allows the
+user to set the @code{--prefix} flag, as well as to define the
address@hidden variable declaring the location of the Python
+interpreter.
+
+These template files may, however, be greatly expanded and customized
+to fit the needs of a given software package. To this end, several
+Autoconf macros are included in the @file{m4/python.m4} file. Notable
+macros include:
+
address@hidden @columnfractions .40 .30 .30
address@hidden
+Macro Name
address@hidden
+Description
address@hidden
+Variables exported
+
address@hidden
address@hidden
address@hidden
+Find a Python interpreter
address@hidden
+PYTHON
+
address@hidden
address@hidden
address@hidden
+Find a python-config program
address@hidden
+PYTHON_CONFIG
+
address@hidden
address@hidden
address@hidden
+Verify that the Python interpreter is of a sufficient version number
address@hidden
+
address@hidden
address@hidden
address@hidden
+Get the version of the Python interpreter
address@hidden
+PYTHON_VERSION
+
address@hidden
address@hidden
address@hidden
+Check for the Python header files (i.e. @file{Python.h})
address@hidden
+HAVE_PYTHON_H
+
address@hidden
address@hidden
address@hidden
+Check for the proper LIBS flags to load the Python shared libraries
address@hidden
+PYTHON_LIBS
+
address@hidden
address@hidden
address@hidden
+Test for the presence of the Python shared libraries
address@hidden
+HAVE_LIBPYTHON
+
address@hidden
address@hidden
address@hidden
+Check the appropriate place to install Python packages (i.e.
address@hidden(prefix)/lib/python2.7/site-packages})
address@hidden
+pythondir
+
address@hidden
address@hidden
address@hidden
+A convenience macro; adds the package's name to @code{pythondir}
address@hidden
+pkgpythondir
+
address@hidden
address@hidden
address@hidden
+Test if a given Python module can be successfully loaded
address@hidden
+
address@hidden
address@hidden
address@hidden
+Test if a given function foo.bar() can be called successfully.
address@hidden
address@hidden multitable
+
+Once these macros are integrated into your @file{configure.ac} file as
+necessary, simply run @code{autoconf} to generate a new
address@hidden script. The variables exported by this
address@hidden script may then be used in @file{Makefile.in} to
+influence the build process. 
+
+To include these scripts in a GSRC Makefile, simply create a .tar.gz
+archive including at least @file{configure}, @file{Makefile.in} and
address@hidden/}, such that the contents will extract into a directory called
address@hidden(DISTNAME)} (i.e. the contents should extract into a directory
+called ``mypackage-0.1/''). Put the archive into the @file{files/}
+sub-directory of the package's GSRC directory. Finally, simply add the
+archive's name to the @code{DISTFILES} list in the GSRC Makefile for
+the package and update the checksums file with @code{make
+makesums}. Now your GSRC Makefile can simply include
address@hidden/auto.mk} to automate the configuration and installation
+of the software.
+
address@hidden GNU Free Documentation License,  , Appendix, Top
 @appendix GNU Free Documentation License
 
 @include fdl.texi

=== modified file 'doc/version.texi'
--- a/doc/version.texi  2012-09-07 21:20:09 +0000
+++ b/doc/version.texi  2012-09-22 17:51:09 +0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 1 September 2012
address@hidden UPDATED 22 September 2012
 @set UPDATED-MONTH September 2012
 @set EDITION 2012.09.06
 @set VERSION 2012.09.06