Add documentation + example for npy-pkg-config files.

1 files changed, 77 insertions, 0 deletions

diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst
index 8b628a507..094d7a2b7 100644
--- a/doc/source/reference/distutils.rst
+++ b/doc/source/reference/distutils.rst
@@ -321,6 +321,83 @@ Other modules
    log.set_verbosity
    exec_command
 
+Building Installable C libraries
+================================
+
+Conventional C libraries (installed through add_library) are not installed, and
+are just used during the build (they are statically linked).  An installable C
+library is a pure C library, which does not depend on the python C runtime, and
+is installed such as it may be used by third-party packages. To build and
+install the C library, you just use the method add_installed_library instead of
+add_library, which takes the same arguments except for an additional
+install_dir argument::
+
+  >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
+
+npy-pkg-config files
+--------------------
+
+To make the necessary build options available to third parties, you could use
+the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is
+based on an .ini file which contains all the options. A .ini file is very
+similar to .pc files as used by the pkg-config unix utility::
+
+  [meta]
+  Name: foo
+  Version: 1.0
+  Description: foo library
+
+  [variables]
+  prefix = /home/user/local
+  libdir = ${prefix}/lib
+  includedir = ${prefix}/include
+
+  [default]
+  cflags = -I${includedir}
+  libs = -L${libdir} -lfoo
+
+Generally, the file needs to be generated during the build, since it needs some
+information known at build time only (e.g. prefix). This is mostly automatic if
+one uses the Configuration method add_npy_pkg_config. Assuming we have a
+template file foo.ini.in as follows::
+
+  [meta]
+  Name: foo
+  Version: @version@
+  Description: foo library
+
+  [variables]
+  prefix = @prefix@
+  libdir = ${prefix}/lib
+  includedir = ${prefix}/include
+
+  [default]
+  cflags = -I${includedir}
+  libs = -L${libdir} -lfoo
+
+and the following code in setup.py::
+
+  >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
+  >>> subst = {'version': '1.0'}
+  >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)
+
+This will install the file foo.ini into the directory package_dir/lib, and the
+foo.ini file will be generated from foo.ini.in, where each @version@ will be
+replaced by subst_dict['version']. The dictionary has an additional prefix
+substitution rule automatically added, which contains the install prefix (since
+this is not easy to get from setup.py).  npy-pkg-config files can also be
+installed at the same location as used for numpy, using the path returned from
+get_npy_pkg_dir function.
+
+Reusing a C library from another package
+----------------------------------------
+
+Info are easily retrieved from the get_info function in numpy.distutils.misc_util::
+
+  >>> info = get_info('npymath')
+  >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
+
+An additional list of paths to look for .ini files can be given to get_info.
 
 Conversion of ``.src`` files
 ============================