Command-line Tools

Three command-line utilities for automated Fortran-to-Python wrapper generation, documentation creation, and enhanced f2py compilation.

Capabilities

f90wrap - Main Wrapper Generator

The primary tool for generating Python wrappers from Fortran source code.

f90wrap -m MODULE F90_FILES [OPTIONS]

Parameters:

• -m, --module MODULE - Name of the Python module to generate
• F90_FILES - List of Fortran 90/95/2003/2008 source files to wrap

Key Options:

• --prefix PREFIX - Prefix for generated wrapper files
• --only ONLY - Comma-separated list of items to wrap exclusively
• --skip SKIP - Comma-separated list of items to skip
• --callback CALLBACK - Comma-separated list of callback routines
• --constructor CONSTRUCTOR - Comma-separated list of constructor routines
• --destructor DESTRUCTOR - Comma-separated list of destructor routines
• --kind-map KIND_MAP - Python file containing Fortran kind to C type mappings
• --string-lengths STRING_LENGTHS - File with string length definitions
• --init-lines INIT_LINES - File with initialization code lines
• --package - Generate package instead of module
• --package-name PACKAGE_NAME - Name for generated package
• --documentation-plugin PLUGIN - Python file with documentation plugin
• --abort-func ABORT_FUNC - Name of abort function for error handling
• --line-length LINE_LENGTH - Maximum line length for generated code (default: 80)
• --default-to-inout - Treat scalars without intent as intent(inout)
• --type-check - Enable type checking during generation (default: False)
• --relative - Use relative imports in generated Python code
• --force-public NAMES - Force specified names to be public
• --skip-types TYPES - Exclude specified types from wrapping
• --default-string-length LENGTH - Default string length (default: 1024)
• --short-names - Use short names for generated wrappers
• --move-methods - Move type-bound procedures to class methods
• --shorten-routine-names - Shorten long routine names
• --joint-modules - Join multiple modules into single wrapper
• --py-max-line-length LENGTH - Maximum Python line length (default: 80)
• --f90-max-line-length LENGTH - Maximum Fortran line length (default: 72)
• --conf-file FILE - Use Python configuration script for options
• -v, --verbose - Enable verbose output
• -V, --version - Show version information
• -h, --help - Show help message

Usage Examples:

# Basic usage
f90wrap -m mycode source1.f90 source2.f90

# With custom options
f90wrap -m mycode --prefix wrap_ --package source.f90

# Skip certain routines
f90wrap -m mycode --skip private_routine,internal_func source.f90

# Only wrap specific items
f90wrap -m mycode --only public_interface,main_type source.f90

# With constructors and destructors
f90wrap -m mycode --constructor init_type --destructor cleanup_type source.f90

# Generate package with initialization
f90wrap -m mycode --package --init-lines init.txt source.f90

f90doc - Documentation Generator

Generates LaTeX documentation from Fortran source code with API reference and usage information.

f90doc F90_FILES [OPTIONS]

Parameters:

• F90_FILES - List of Fortran source files to document

Key Options:

• -t, --title TITLE - Title for generated documentation
• -a, --author AUTHOR - Author name for documentation
• -d, --doc-filename DOC_FILENAME - Output documentation filename
• --short-doc - Generate short-form documentation
• --intro INTRO - Introduction text file
• --header HEADER - Header text file
• -v, --verbose - Enable verbose output
• -h, --help - Show help message

Usage Examples:

# Basic documentation generation
f90doc source.f90

# With custom title and author
f90doc --title "My Fortran Library" --author "John Doe" source.f90

# Generate short documentation
f90doc --short-doc --doc-filename brief.tex source.f90

# With introduction and header files
f90doc --intro intro.txt --header header.txt source.f90

f2py-f90wrap - Enhanced f2py

A modified version of f2py with f90wrap-specific enhancements for better Fortran-Python interoperability.

f2py-f90wrap [F2PY_OPTIONS]

Enhanced Features:

1. Optional Argument Support: Allows the Fortran present() intrinsic function to work correctly with optional arguments by replacing missing arguments with NULL.

2. Exception Handling: Enables Fortran routines to raise Python RuntimeError exceptions by calling f90wrap_abort() function, implemented using setjmp()/longjmp().

3. Interrupt Handling: Allows Fortran routines to be interrupted with Ctrl+C by installing a custom interrupt handler before Fortran calls and restoring the previous handler afterward.

Standard f2py Options:

• -c - Compile extension module
• -m MODULE - Name of extension module
• --verbose - Verbose output
• --debug - Debug mode
• --help - Show help

Usage Examples:

# Compile f90wrap-generated wrappers
f2py-f90wrap -c -m _mycode f90wrap_*.f90 *.o

# With verbose output
f2py-f90wrap -c -m _mycode --verbose f90wrap_*.f90 *.o

# Debug compilation
f2py-f90wrap -c -m _mycode --debug f90wrap_*.f90 *.o

Typical Workflow

The standard f90wrap workflow combines all three tools:

# Step 1: Generate wrappers
f90wrap -m mycode --constructor init_mytype source.f90

# Step 2: Compile with enhanced f2py
f2py-f90wrap -c -m _mycode f90wrap_*.f90 *.o

# Step 3: Generate documentation (optional)
f90doc --title "MyCode API" source.f90

# Step 4: Use in Python
python -c "import mycode; help(mycode)"

Output Files

f90wrap Output

• f90wrap_*.f90 - Fortran wrapper files (one per input file)
• f90wrap_toplevel.f90 - Wrapper for top-level procedures (if any)
• Python wrapper files with Pythonic interface

f90doc Output

• .tex files - LaTeX documentation
• Associated image and style files

f2py-f90wrap Output

• Compiled Python extension modules (.so, .dll, .pyd)
• Signature files (.pyf) if requested

Configuration Files

f90wrap supports various configuration files for customization:

• Kind map files: Python dictionaries mapping Fortran kinds to C types
• String length files: Definitions for Fortran string parameter lengths
• Initialization files: Code to be included in wrapper initialization
• Documentation plugins: Custom documentation extraction and formatting

Environment Variables

• F90 - Fortran compiler to use (default: gfortran)
• F2PY_REPORT_ON_ARRAY_COPY - Controls f2py array copy reporting
• Standard f2py environment variables are supported