diff options
author | Pearu Peterson <pearu.peterson@gmail.com> | 2007-07-27 16:44:39 +0000 |
---|---|---|
committer | Pearu Peterson <pearu.peterson@gmail.com> | 2007-07-27 16:44:39 +0000 |
commit | e4cf3417be16ac14aeff908fc344a632fc1b4399 (patch) | |
tree | bb911bd88b79b8dd97d50b4204710b48abfe4daa /numpy/f2py | |
parent | 2994141453421f306bcd891d559b31b554f220db (diff) | |
download | numpy-e4cf3417be16ac14aeff908fc344a632fc1b4399.tar.gz |
Doc update 2.
Diffstat (limited to 'numpy/f2py')
-rw-r--r-- | numpy/f2py/lib/doc.txt | 161 |
1 files changed, 157 insertions, 4 deletions
diff --git a/numpy/f2py/lib/doc.txt b/numpy/f2py/lib/doc.txt index 13accc371..79ccb0768 100644 --- a/numpy/f2py/lib/doc.txt +++ b/numpy/f2py/lib/doc.txt @@ -20,11 +20,10 @@ 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 -============================ +Wrapping Fortran with Python - UI +================================= -There are two user interfaces to wrap Fortran programs with -Python: +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 @@ -84,3 +83,157 @@ __ http://cens.ioc.ee/projects/f2py2e/ >>> 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. |