Getting Started with F2x

This document gives a short introduction to get started working with F2x. More detailed information about the single steps can be found in the respective detailed chapter.

Installation

F2x currently depends on Python and setuptools in order to install it. If you have these pre-requirements in place, you can go ahead and install F2x by cloning the repository and running the setup script:

$ git clone https://github.com/DLR-SC/F2x.git
$ cd F2x
$ python setup.py install

Of course you need a working Fortran compiler. As F2x relies on the build chain provided by numpy, this usually mean that if you can build numpy extensions, you should also be able to build F2x extensions.

This should install all dependencies and a command line tool F2x to wrap your Fortran code.

One-shot building

A tiny example is available to try F2x. Extract it to some location and from the containing folder run:

$ F2x -W lib -m mylib.* mylib/test.f90

This applies a strategy to generate the wrapper modules and compile the extension named mylib.test in one shot. You can try your results by running tests against it:

$ python -m mylib.test
          42

Wrapping Fortran Sources

If you have successfully installed F2x, you can use the F2x command line tool to wrap your source files. The general synopsis is:

$ F2x [-t template]... [source file]...

This will make F2x parse the source files and apply each template to each source file to generate the wrapper output. A full overview of all options is available here <command_line>.

The following templates are the recommended choice:

bindc

@bindc/_glue.f90.t

Generate a ISO C compliant interface to a Fortran module using BIND(C).

cerr

@cerr/_cerr.c.t

Generates a thin C layer that is used as clean stack snapshot for longjmp error handling.

ctypes

@ctypes/_glue.py.t

Generates a Python module that interacts with a ISO C interface generated by ‘bindc’ template using ctypes including error handling using ‘cerr’ template.

Alternatively, you can also use the following set of templates that generates a wrapper without error handling.

bindc

@bindc/_glue.f90.t

Generate a ISO C compliant interface to a Fortran module using BIND(C).

ctypes_noerr

@ctypes_noerr/_glue.py.t

Generates a Python module that interacts with a ISO C interface generated by ‘bindc’ template using ctypes.

Usually, you need to apply several templates to achieve full wrapping of your Fortran source (and thus make it usable from Python). You can pass all of them at one to F2x.

Building the Extension

After wrapping your Fortran sources, you need to compile the genrated sources. Some of the templates require additional libraries to be used. To include them in compilation, you can use to following helpful commands that returns the full pathes to all required artifacts:

$ export F2X_TEMPLATE_LIBS = \
    $(F2x -t bindc -t cerr -t ctypes --get libraries)
$ export F2X_TEMPLATE_MODS = \
    $(F2x -t bindc -t cerr -t ctypes --get modules)

Example

Consider the following example Fortran source:

mylib/test.f90
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
! Example module to use with F2x documentation.
MODULE TEST

  PUBLIC

CONTAINS

  SUBROUTINE CALL_TEST(INTARG)
     INTEGER, INTENT(IN) :: INTARG

     WRITE (*, *) INTARG
  END SUBROUTINE

END

This file will be wrapped and the resulting sources are compiled to a dynamic library:

$ F2x -t @bindc/_glue.f90.t -t @ctypes_noerr/_glue.py.t mylib/test.f90
$ gfortran -fPIC -shared -o mylib/$(F2x --get extlib mylib/test.f90) \
    $(F2x -t bindc -t ctypes_noerr --get libraries) mylib/test.f90 mylib/test_glue.f90
$ cp $(F2x -t bindc -t ctypes_noerr --get modules) mylib

Now you should be able to call CALL_TEST from Python:

$ python
>>> from mylib import test_glue as test
>>> test.CALL_TEST(123)

Advanced Options

There are several other ways to interact with F2x which are described in more detail in their respective sections.