0
# Command-line Tools
1

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

4
## Capabilities
5

6
### f90wrap - Main Wrapper Generator
7

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

10
```bash { .api }
11
f90wrap -m MODULE F90_FILES [OPTIONS]
12
```
13

14
**Parameters:**
15
- `-m, --module MODULE` - Name of the Python module to generate
16
- `F90_FILES` - List of Fortran 90/95/2003/2008 source files to wrap
17

18
**Key Options:**
19
- `--prefix PREFIX` - Prefix for generated wrapper files
20
- `--only ONLY` - Comma-separated list of items to wrap exclusively  
21
- `--skip SKIP` - Comma-separated list of items to skip
22
- `--callback CALLBACK` - Comma-separated list of callback routines
23
- `--constructor CONSTRUCTOR` - Comma-separated list of constructor routines
24
- `--destructor DESTRUCTOR` - Comma-separated list of destructor routines
25
- `--kind-map KIND_MAP` - Python file containing Fortran kind to C type mappings
26
- `--string-lengths STRING_LENGTHS` - File with string length definitions
27
- `--init-lines INIT_LINES` - File with initialization code lines
28
- `--package` - Generate package instead of module
29
- `--package-name PACKAGE_NAME` - Name for generated package
30
- `--documentation-plugin PLUGIN` - Python file with documentation plugin
31
- `--abort-func ABORT_FUNC` - Name of abort function for error handling
32
- `--line-length LINE_LENGTH` - Maximum line length for generated code (default: 80)
33
- `--default-to-inout` - Treat scalars without intent as intent(inout)
34
- `--type-check` - Enable type checking during generation (default: False)
35
- `--relative` - Use relative imports in generated Python code
36
- `--force-public NAMES` - Force specified names to be public
37
- `--skip-types TYPES` - Exclude specified types from wrapping
38
- `--default-string-length LENGTH` - Default string length (default: 1024)
39
- `--short-names` - Use short names for generated wrappers
40
- `--move-methods` - Move type-bound procedures to class methods
41
- `--shorten-routine-names` - Shorten long routine names
42
- `--joint-modules` - Join multiple modules into single wrapper
43
- `--py-max-line-length LENGTH` - Maximum Python line length (default: 80)
44
- `--f90-max-line-length LENGTH` - Maximum Fortran line length (default: 72)
45
- `--conf-file FILE` - Use Python configuration script for options
46
- `-v, --verbose` - Enable verbose output
47
- `-V, --version` - Show version information
48
- `-h, --help` - Show help message
49

50
**Usage Examples:**
51

52
```bash
53
# Basic usage
54
f90wrap -m mycode source1.f90 source2.f90
55

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

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

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

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

68
# Generate package with initialization
69
f90wrap -m mycode --package --init-lines init.txt source.f90
70
```
71

72
### f90doc - Documentation Generator
73

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

76
```bash { .api }
77
f90doc F90_FILES [OPTIONS]
78
```
79

80
**Parameters:**
81
- `F90_FILES` - List of Fortran source files to document
82

83
**Key Options:**
84
- `-t, --title TITLE` - Title for generated documentation
85
- `-a, --author AUTHOR` - Author name for documentation
86
- `-d, --doc-filename DOC_FILENAME` - Output documentation filename
87
- `--short-doc` - Generate short-form documentation
88
- `--intro INTRO` - Introduction text file
89
- `--header HEADER` - Header text file
90
- `-v, --verbose` - Enable verbose output
91
- `-h, --help` - Show help message
92

93
**Usage Examples:**
94

95
```bash
96
# Basic documentation generation
97
f90doc source.f90
98

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

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

105
# With introduction and header files
106
f90doc --intro intro.txt --header header.txt source.f90
107
```
108

109
### f2py-f90wrap - Enhanced f2py
110

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

113
```bash { .api }
114
f2py-f90wrap [F2PY_OPTIONS]
115
```
116

117
**Enhanced Features:**
118

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

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

123
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.
124

125
**Standard f2py Options:**
126
- `-c` - Compile extension module
127
- `-m MODULE` - Name of extension module
128
- `--verbose` - Verbose output
129
- `--debug` - Debug mode
130
- `--help` - Show help
131

132
**Usage Examples:**
133

134
```bash
135
# Compile f90wrap-generated wrappers
136
f2py-f90wrap -c -m _mycode f90wrap_*.f90 *.o
137

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

141
# Debug compilation
142
f2py-f90wrap -c -m _mycode --debug f90wrap_*.f90 *.o
143
```
144

145
## Typical Workflow
146

147
The standard f90wrap workflow combines all three tools:
148

149
```bash
150
# Step 1: Generate wrappers
151
f90wrap -m mycode --constructor init_mytype source.f90
152

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

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

159
# Step 4: Use in Python
160
python -c "import mycode; help(mycode)"
161
```
162

163
## Output Files
164

165
### f90wrap Output
166

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

171
### f90doc Output
172

173
- `.tex` files - LaTeX documentation
174
- Associated image and style files
175

176
### f2py-f90wrap Output
177

178
- Compiled Python extension modules (`.so`, `.dll`, `.pyd`)
179
- Signature files (`.pyf`) if requested
180

181
## Configuration Files
182

183
f90wrap supports various configuration files for customization:
184

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

190
## Environment Variables
191

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