.. -*- rest -*-

=======================
G3 F2PY library package 
=======================

:Author:
  Pearu Peterson <pearu.peterson@gmail.com>
:Created: July 2007

.. contents:: Table of Contents

Overview
========

The G3 F2PY library package contains tools to parse Fortran codes and
construct Python C/API extension modules for wrapping Fortran
programs. These tools are also suitable for implementing Fortran
program translators or wrappers to any other programming language.  In
fact, wrapping Fortran programs to Python would be just one example of
using these tools.

Wrapping Fortran with Python - UI
=================================

There are two user interfaces to wrap Fortran programs with Python:

  - the command line program `f2py` that scans Fortran files
    given as command line arguments and builds extension modules
    that can be used to call Fortran programs from Python.
    The `f2py` program has four different ways of building
    extension modules as specified with the following command
    line flags:

    - `--g3-numpy` --- create extension modules with NumPy array
      support using the new tools from `the 3rd generation of F2PY`__.
      This is a work-in-progress feature.

    - `--2d-numpy` --- create extension modules with NumPy array
      support using `the stable version of F2PY`__. This is default.

    - `--2d-numeric` --- create extension modules with Numeric
      array support using the old version of f2py2e. The f2py2e
      package must be downloaded and installed separately from
      the `f2py2e homepage`__.

    - `--2d-numarray` --- create extension modules with Numarray
      array support using the old version of f2py2e.

    Example::

      $ cat hello.f90 
      subroutine hello
        print*, "Hello!"
      end subroutine hello
      $ f2py --g3-numpy -m foo -c hello.f90 --fcompiler=gnu95
      $ python
      >>> import foo
      >>> foo.hello()
       Hello!
      >>>

    See the output of `f2py` for more information.

__ http://projects.scipy.org/scipy/numpy/wiki/G3F2PY/
__ http://www.scipy.org/F2py/
__ http://cens.ioc.ee/projects/f2py2e/

  - the function `compile()` that scans its string input containing
    Fortran code and returns a list of imported extension modules
    that can be used to call Fortran programs from Python.

    Example::

      $ python
      >>> from numpy.f2py.lib.api import compile
      >>> code = 'subroutine hello\n  print*, "Hello!"\nend'
      >>> print code
      subroutine hello
        print*, "Hello!"
      end
      >>> foo, = compile(code, extra_args = ['--fcompiler=gnu95'])
      >>> foo.hello()
       Hello!
      >>>

Wrapping Fortran with Python - how it works?
============================================

The two users interfaces discussed above are implemented by functions
`main(sys_argv=None)` and `compile(source, jobname='untitled',
extra_args=[], source_ext=None, modulenames=None)` in file
`numpy/f2py/lib/main.py`.  Both these functions call
`build_extension(sys_argv, sources_only=False)` function that reads
`sys_argv` list for files and options, constructs wrapper functions,
creates a `numpy.distutils` style `setup.py` file, and finally runs
it.

`build_extension` options
-------------------------

The following options are defined that can be used as command line
arguments to `f2py` or in `extra_args` list argument of the `compiler`
function:

  - `-m [<name>]` --- specify the name of a wrapper extension
    module. Default is `untitled` or `unspecified` (if `<name>` part
    is not specified).

  - `--target-dir=<path>` --- specify the directory path where
    extension modules are saved. Default is the current working
    directory.

  - `--build-dir=<path>` --- specify the directory path where
    temporary files are created during the build process. Default is
    `_g2f2py` or temporary directory (when `<path>` part is not
    specified)).

  - `-I<path>` --- specifies include directory path that is used for
    finding Fortran 90 modules and when compiling sources.

  - `-D<name>[=<value>]`, `-U<name>` --- defines or undefines CPP
    macro used in compiling sources. See below for F2PY specific
    macros.

  - `-L<path>` --- specifies library directory path that is used in
    linking extension modules.

  - `-l<name>` --- specifies library that is used in linking extension
    modules.

  - `<filename>.(o|a|so|dll|dylib|sl)` --- specifies extra object
    files used in linking extension modules.

  - `<filename>`.pyf --- specifies signature file used for scanning
    Fortran program signatures.

  - `<filename>.(f|f90|F90|F)` --- specifies Fortran source files used
    for scanning Fortran program signatures (in case no signature
    files are specified). These sources will be compiled and linked
    with extension modules.

  - `<filename>.(c|cpp|C|CPP|c++)` --- specifies C/C++ source files
    that will be compiled and linked with extension modules. Note that
    if no signature file is specified then also C/C++ files are
    scanned for Fortran program signatures. The Fortran program
    signatures are assumed to be inside the C comment `/* f2py ... */`
    block.

  - `--fcompiler=<compiler name>` --- specifies Fortran compiler to be
    used in compiling/linking the sources. See also `--help-fcompiler`
    option.

  - `--help-fcompiler` --- list Fortran compilers that are found in
    the system, that are available or unavailable for the current
    system. Then return without processing any other options.

  - `--compiler=<compiler name>` --- specifies C/C++ compiler to be
    used in compiling/linking the sources. See also `--help-compiler` 
    option.

  - `--help-compiler` --- list C/C++ compilers that are available 
    for the current system. Then return without processing any other
    options.

Additional `f2py` command line options
--------------------------------------

Command line tool `f2py` uses the following additional command line
options:

  - `-c` --- specifies that F2PY should build extension
    modules. Without this option F2PY just scans source files for
    signatures and constructs extension module sources --- useful when
    one needs to build extension modules manually (in Makefile, for
    instance). See also `-h` option below.

  - `-h <filename>` --- specifies the signature file name
    where the results of scanning sources will be saved. With this
    option F2PY just scans the sources but does not construct extension
    modules sources --- useful when one needs to edit the signatures
    of Fortran programs. If `<filename>` is `stdout` or `stderr` is
    specified then the scanned signatures will be dumped to `stdout`
    or `stderr` streams, respectively.

  - `--help-link [<resouce name> ]...` --- list system resources as
    defined in `numpy/distutils/system_info.py` and return.

  - `--parse` --- specifies that F2PY should just parce the
    source files and dump the results to `stdout` stream.
    Useful for debugging F2PY parser.


F2PY specific CPP macros
------------------------

F2PY may use the following CPP macros:

  - `-DF2PY_DEBUG_PYOBJ_TOFROM` --- show debug messages from
    `pyobj_(to|from)_<ctype>` functions.

  - `-DPREPEND_FORTRAN`, `-DNO_APPEND_FORTRAN`, `-DUPPERCASE_FORTRAN`,
    `-DUNDERSCORE_G77` --- specify how Fortran compiler mangles Fortran
    symbol names that need to be accessed from C extension modules.
    Usually one never needs to specify these macros as supported
    Fortran compilers should always mangle the names to be lower-cased
    and with exactly one underscore after the name.

Options for `compile`
---------------------

The `compile` function has the following options:

  - `source` --- a string containing Fortran code. To specify the
    Fortran format of the `source` use the following header lines
    in the `source` string:

      - `C -*- f77 -*-` --- the string contains Fortran 77 code
      - `! -*- f90 -*-` --- the string contains Fortran 90 code in
        free format.
      - `! -*- fix -*-` --- the string contains Fortran 90 code in
        fixed format.
      - `! -*- pyf -*-` --- the string contains Fortran signatures.

  - `jobname='untitled'` --- a string specifing the name of an 
    extension module

  - `extra_args=[]` --- a list of `build_extension(..)` arguments,
    see above.

  - `source_ext=None` --- a string specifying the extension (`.f` or
    `.f90`) of the file where `source` will be saved for further
    processing. Default extension will be determined from the `source`
    string.

  - `modulenames=None` --- a list of module names that the build
    process should create. `compile` function will try to import
    these modules and return the corresponding module objects
    as a list.
