0
# Command-Line Tools
1

2
Console commands for transpiling Python files and managing Pyccel projects from the command line, supporting batch processing and integration with build systems.
3

4
## Capabilities
5

6
### Main Transpilation Command
7

8
The primary command-line interface for transpiling Python files to optimized compiled code.
9

10
```bash { .api }
11
pyccel filename.py [options]
12
```
13

14
#### Positional Arguments
15

16
```bash { .api }
17
filename.py         # Path to Python file to transpile
18
```
19

20
#### Basic Options
21

22
```bash { .api }
23
-h, --help          # Show help message and exit
24
-V, --version       # Show version and exit
25
-v, --verbose       # Increase verbosity (use -v, -vv, -vvv)
26
--time-execution    # Print time spent in each execution section
27
--developer-mode    # Enable developer error mode
28
```
29

30
#### Compilation Stages
31

32
```bash { .api }
33
-x, --syntax-only    # Stop after syntactic parsing
34
-e, --semantic-only  # Stop after semantic analysis  
35
-t, --convert-only   # Stop after translation, before build
36
```
37

38
#### Backend Selection
39

40
```bash { .api }
41
--language {fortran,c,python}    # Target language (default: fortran)
42
```
43

44
#### Compiler Configuration
45

46
```bash { .api }
47
--compiler-family {GNU,intel,PGI,nvidia,LLVM}  # Compiler family (default: GNU)
48
--compiler-config CONFIG.json                  # Load compiler config from JSON file
49
```
50

51
#### Additional Compiler Options
52

53
```bash { .api }
54
--flags FLAGS                    # Additional compiler flags
55
--wrapper-flags FLAGS            # Additional wrapper compiler flags
56
--debug / --no-debug            # Compile with debug flags
57
--include DIR [DIR ...]         # Additional include directories
58
--libdir DIR [DIR ...]          # Additional library directories  
59
--libs LIB [LIB ...]           # Additional libraries to link
60
--output DIR                    # Output folder (default: input file's folder)
61
```
62

63
#### Accelerator Options
64

65
```bash { .api }
66
--mpi              # Enable MPI support
67
--openmp           # Enable OpenMP support
68
```
69

70
#### Other Options
71

72
```bash { .api }
73
--conda-warnings {off,basic,verbose}  # Conda warning level (default: basic)
74
```
75

76
Usage examples:
77

78
```bash
79
# Basic transpilation to Fortran
80
pyccel my_script.py
81

82
# Transpile to C with debug mode
83
pyccel my_script.py --language c --debug
84

85
# Transpile with OpenMP support
86
pyccel compute.py --openmp --verbose
87

88
# Transpile with custom compiler and flags
89
pyccel simulation.py --compiler-family intel --flags "-O3 -march=native"
90

91
# Stop after semantic analysis for debugging
92
pyccel test.py --semantic-only --developer-mode
93

94
# Transpile with MPI and custom output directory
95
pyccel parallel_code.py --mpi --output ./build --verbose
96
```
97

98
### Project Cleanup Command
99

100
Removes generated Pyccel files and build artifacts from the current directory or specified paths.
101

102
```bash { .api }
103
pyccel-clean [options]
104
```
105

106
Usage examples:
107

108
```bash
109
# Clean current directory
110
pyccel-clean
111

112
# Clean with verbose output
113
pyccel-clean --verbose
114
```
115

116
### Testing Command  
117

118
Runs Pyccel's test suite or tests specific Python files for transpilation compatibility.
119

120
```bash { .api }
121
pyccel-test [options] [files...]
122
```
123

124
#### Test Options
125

126
```bash { .api }
127
--language {fortran,c,python}     # Test with specific target language
128
--mpi                             # Test with MPI support
129
--openmp                          # Test with OpenMP support
130
--verbose                         # Verbose test output
131
```
132

133
Usage examples:
134

135
```bash
136
# Run all tests
137
pyccel-test
138

139
# Test specific files
140
pyccel-test my_module.py another_file.py
141

142
# Test with Fortran backend and MPI
143
pyccel-test --language fortran --mpi test_parallel.py
144

145
# Run tests with verbose output
146
pyccel-test --verbose
147
```
148

149
## Command Implementation Functions
150

151
### Console Command Function
152

153
```python { .api }
154
from pyccel.commands.console import pyccel
155

156
def pyccel():
157
    """
158
    Main Pyccel console command function.
159
    
160
    Parses command-line arguments and executes the transpilation pipeline
161
    with the specified options. Handles all stages from syntax parsing
162
    through compilation and executable generation.
163
    """
164
```
165

166
### Cleanup Command Function
167

168
```python { .api }
169
from pyccel.commands.pyccel_clean import pyccel_clean_command
170

171
def pyccel_clean_command():
172
    """
173
    Clean generated Pyccel files command function.
174
    
175
    Removes __epyccel__ directories, compiled extensions, and other
176
    build artifacts created during transpilation process.
177
    """
178
```
179

180
### Test Command Function
181

182
```python { .api }
183
from pyccel.commands.pyccel_test import pyccel_test_command
184

185
def pyccel_test_command():
186
    """
187
    Pyccel test execution command function.
188
    
189
    Runs transpilation tests on specified files or the full test suite,
190
    validating correct behavior across different backends and options.
191
    """
192
```
193

194
### Custom Argument Parser
195

196
```python { .api }
197
import argparse
198
from pyccel.commands.console import MyParser
199

200
class MyParser(argparse.ArgumentParser):
201
    """
202
    Custom argument parser that displays help on error.
203
    
204
    Extends ArgumentParser to automatically show help message
205
    when invalid arguments are provided.
206
    """
207
    
208
    def error(self, message):
209
        """Display error message and help, then exit."""
210
```
211

212
## Environment Variables
213

214
```bash { .api }
215
PYCCEL_DEBUG_MODE        # Default debug mode (True/False)
216
PYCCEL_ERROR_MODE        # Error reporting mode (user/developer)
217
PYTEST_XDIST_WORKER      # Parallel test worker ID (used internally)
218
```
219

220
## Configuration Files
221

222
### Compiler Configuration JSON
223

224
```json { .api }
225
{
226
  "family": "GNU",
227
  "fortran": {
228
    "compiler": "gfortran", 
229
    "flags": ["-O3", "-fPIC"],
230
    "libs": ["gfortran"]
231
  },
232
  "c": {
233
    "compiler": "gcc",
234
    "flags": ["-O3", "-fPIC"], 
235
    "libs": ["m"]
236
  }
237
}
238
```
239

240
## Output Files
241

242
### Generated Files Structure
243

244
```bash { .api }
245
original_file.py                    # Original Python file
246
__epyccel__/                       # Build directory
247
├── mod_<random>.py               # Generated Python module
248
├── mod_<random>.f90              # Generated Fortran code  
249
├── mod_<random>.so               # Compiled shared library
250
└── mod_<random>.lock            # File lock for parallel builds
251
```
252

253
### Executable Generation
254

255
When the input file contains `if __name__ == '__main__':`, Pyccel generates:
256

257
```bash { .api }
258
filename                          # Executable binary (Unix)
259
filename.exe                      # Executable binary (Windows)
260
```