0
# Command-line Tools
1

2
Console scripts providing command-line access to compilation, optimization, and import functionality. These tools serve as the primary interface for batch processing, CI/CD integration, and interactive development workflows.
3

4
## Console Scripts
5

6
The iree-base-compiler package provides five main command-line tools installed as console scripts.
7

8
### iree-compile
9

10
Primary compiler tool for converting MLIR to IREE VM modules.
11

12
```bash { .api }
13
iree-compile input.mlir -o output.vmfb [OPTIONS]
14

15
# Core options:
16
--iree-hal-target-backends=BACKEND    # Target backend (llvm-cpu, cuda, vulkan-spirv, etc.)
17
--iree-input-type=TYPE               # Input type (auto, stablehlo, tosa, torch, etc.)
18
--iree-vm-bytecode-module-output-format=FORMAT  # Output format (flatbuffer-binary, etc.)
19
-o, --output=FILE                    # Output file path
20

21
# Optimization options:
22
--iree-opt-level=LEVEL              # Optimization level (0-3)
23
--iree-flow-enable-fusing           # Enable operation fusion
24
--iree-llvmcpu-target-cpu=CPU       # Target CPU architecture
25

26
# Debug options:
27
--mlir-print-debuginfo              # Include debug information
28
--mlir-print-ir-after-all           # Print IR after each pass
29
--mlir-print-op-on-diagnostic       # Print operations on diagnostic
30
```
31

32
**Entry Point**: `iree.compiler.tools.scripts.iree_compile.__main__:main`
33

34
### iree-opt
35

36
MLIR optimization tool for applying transformation passes.
37

38
```bash { .api }
39
iree-opt input.mlir [OPTIONS]
40

41
# Pass options:
42
--pass-pipeline=PIPELINE            # Specify pass pipeline
43
--print-ir-after-all               # Print IR after each pass
44
--print-ir-before-all              # Print IR before each pass
45
--verify-each                      # Verify IR after each pass
46

47
# Common passes:
48
--iree-flow-transformation-pipeline # Flow dialect transformations
49
--iree-stream-transformation-pipeline # Stream dialect transformations
50
--canonicalize                     # Canonicalization pass
51

52
# Output options:
53
-o, --output=FILE                  # Output file path
54
--emit=FORMAT                      # Output format
55
```
56

57
**Entry Point**: `iree.compiler.tools.scripts.iree_opt.__main__:main`
58

59
### iree-import-onnx
60

61
ONNX model import tool for converting ONNX models to IREE-compatible MLIR.
62

63
```bash { .api }
64
iree-import-onnx model.onnx -o model.mlir [OPTIONS]
65

66
# Import options:
67
-o, --output=FILE                   # Output MLIR file
68
--upgrade                          # Upgrade ONNX model to latest version
69
--input-name=NAME                  # Input tensor name
70
--output-name=NAME                 # Output tensor name
71
```
72

73
**Entry Point**: `iree.compiler.tools.import_onnx.__main__:_cli_main`
74

75
### iree-ir-tool
76

77
MLIR IR manipulation and analysis tool.
78

79
```bash { .api }
80
iree-ir-tool [COMMAND] input.mlir [OPTIONS]
81

82
# Commands:
83
print                              # Print IR in various formats
84
verify                            # Verify IR validity
85
transform                         # Apply transformations
86
analyze                          # Analyze IR structure
87

88
# Options:
89
--output-format=FORMAT            # Output format (text, bytecode)
90
--print-generic                  # Use generic operation format
91
--print-debuginfo               # Include debug information
92
```
93

94
**Entry Point**: `iree.compiler.tools.ir_tool.__main__:_cli_main`
95

96
### iree-build
97

98
Build system command-line interface for complex compilation workflows.
99

100
```bash { .api }
101
iree-build [ENTRYPOINT] [OPTIONS]
102

103
# Build commands:
104
list                               # List available build entrypoints
105
run ENTRYPOINT                     # Run specific build entrypoint
106
clean                              # Clean build artifacts
107

108
# Common options:
109
--build-dir=DIR                    # Build directory path
110
--verbose                          # Verbose output
111
--parallel=N                       # Parallel execution limit
112
--config=FILE                      # Configuration file
113

114
# Entrypoint-specific options vary by entrypoint
115
```
116

117
**Entry Point**: `iree.build.__main__:main`
118

119
## Tool Implementation
120

121
### Core Tool Functions
122

123
Base functions for implementing command-line tool functionality.
124

125
```python { .api }
126
def find_tool(tool_name: str) -> str:
127
    """
128
    Find the path to a compiler tool executable.
129
    
130
    Parameters:
131
    - tool_name: Name of the tool to find
132
    
133
    Returns:
134
    str: Full path to tool executable
135
    
136
    Raises:
137
    FileNotFoundError: If tool is not found
138
    """
139

140
def invoke_immediate(
141
    command_line: List[str],
142
    immediate_input: bytes = None
143
) -> bytes:
144
    """
145
    Invoke a command-line tool and return output.
146
    
147
    Parameters:
148
    - command_line: Command and arguments to execute
149
    - immediate_input: Optional stdin input
150
    
151
    Returns:
152
    bytes: Tool output
153
    
154
    Raises:
155
    CompilerToolError: If tool execution fails
156
    """
157

158
def build_compile_command_line(
159
    input_file: str,
160
    temp_file_saver: TempFileSaver,
161
    options: CompilerOptions
162
) -> List[str]:
163
    """
164
    Build command line for iree-compile tool.
165
    
166
    Parameters:
167
    - input_file: Input file path
168
    - temp_file_saver: Temporary file manager
169
    - options: Compilation options
170
    
171
    Returns:
172
    List[str]: Command line arguments
173
    """
174
```
175

176
### Binary Management
177

178
Functions for locating and managing compiler tool binaries.
179

180
```python { .api }
181
def get_tool_path(tool_name: str) -> str:
182
    """
183
    Get the full path to a compiler tool.
184
    
185
    Parameters:
186
    - tool_name: Tool name
187
    
188
    Returns:
189
    str: Full path to tool executable
190
    """
191

192
def verify_tool_availability(tool_name: str) -> bool:
193
    """
194
    Check if a compiler tool is available.
195
    
196
    Parameters:
197
    - tool_name: Tool name to check
198
    
199
    Returns:
200
    bool: True if tool is available
201
    """
202

203
class ToolEnvironment:
204
    """
205
    Manager for compiler tool environment and paths.
206
    
207
    Handles tool discovery, path management, and environment
208
    setup for compiler tool execution.
209
    """
210
    
211
    def __init__(self, tool_search_paths: List[str] = None): ...
212
    
213
    def find_tool(self, tool_name: str) -> str: ...
214
    
215
    def setup_environment(self) -> Dict[str, str]: ...
216
```
217

218
### Error Handling
219

220
Exception classes and error handling for command-line tool failures.
221

222
```python { .api }
223
class CompilerToolError(Exception):
224
    """
225
    Exception raised when a compiler tool fails.
226
    
227
    Provides access to tool output, error messages, and exit codes
228
    for debugging compilation failures.
229
    """
230
    
231
    def __init__(
232
        self,
233
        tool_name: str,
234
        command_line: List[str],
235
        exit_code: int,
236
        stdout: bytes = None,
237
        stderr: bytes = None
238
    ): ...
239
    
240
    @property
241
    def tool_name(self) -> str: ...
242
    
243
    @property
244
    def exit_code(self) -> int: ...
245
    
246
    @property
247
    def stdout_text(self) -> str: ...
248
    
249
    @property
250
    def stderr_text(self) -> str: ...
251
```
252

253
## Usage Examples
254

255
### Basic Compilation Workflow
256

257
```bash
258
# Compile MLIR to VM module for CPU
259
iree-compile model.mlir \
260
  --iree-hal-target-backends=llvm-cpu \
261
  --iree-input-type=auto \
262
  -o model.vmfb
263

264
# Compile for GPU with optimization
265
iree-compile model.mlir \
266
  --iree-hal-target-backends=cuda \
267
  --iree-opt-level=3 \
268
  --iree-llvmgpu-enable-prefetch \
269
  -o model_gpu.vmfb
270
```
271

272
### ONNX Import and Compilation Pipeline
273

274
```bash
275
# Import ONNX model to MLIR
276
iree-import-onnx model.onnx \
277
  --output-names=output \
278
  --optimize \
279
  -o model.mlir
280

281
# Optimize MLIR representation
282
iree-opt model.mlir \
283
  --iree-flow-transformation-pipeline \
284
  --canonicalize \
285
  -o model_opt.mlir
286

287
# Compile optimized MLIR
288
iree-compile model_opt.mlir \
289
  --iree-hal-target-backends=vulkan-spirv \
290
  -o model_vulkan.vmfb
291
```
292

293
### Advanced Multi-Target Build
294

295
```bash
296
# Build for multiple targets using build system
297
iree-build compile_multi_target \
298
  --model-path=./model.onnx \
299
  --targets=llvm-cpu,cuda,vulkan-spirv \
300
  --optimize \
301
  --output-dir=./outputs
302

303
# Custom build with configuration
304
iree-build custom_build \
305
  --config=build_config.yaml \
306
  --build-dir=./build \
307
  --parallel=4 \
308
  --verbose
309
```
310

311
### Development and Debugging
312

313
```bash
314
# Debug compilation with IR dumps
315
iree-compile model.mlir \
316
  --iree-hal-target-backends=llvm-cpu \
317
  --mlir-print-ir-after-all \
318
  --mlir-print-debuginfo \
319
  -o model_debug.vmfb
320

321
# Analyze IR structure
322
iree-ir-tool analyze model.mlir \
323
  --show-stats \
324
  --show-dialects \
325
  --verify
326

327
# Compare two MLIR files
328
iree-ir-tool diff model1.mlir model2.mlir \
329
  --ignore-debug-info
330
```
331

332
### Programmatic Tool Usage
333

334
```python
335
from iree.compiler.tools.binaries import find_tool, invoke_immediate
336

337
# Find compiler tool
338
iree_compile = find_tool("iree-compile")
339

340
# Build command line
341
command = [
342
    iree_compile,
343
    "model.mlir",
344
    "--iree-hal-target-backends=llvm-cpu",
345
    "-o", "model.vmfb"
346
]
347

348
# Execute compilation
349
try:
350
    output = invoke_immediate(command)
351
    print("Compilation successful")
352
except CompilerToolError as e:
353
    print(f"Compilation failed: {e}")
354
    print(f"Exit code: {e.exit_code}")
355
    print(f"Error output: {e.stderr_text}")
356
```
357

358
### Batch Processing Script
359

360
```python
361
import os
362
import subprocess
363
from pathlib import Path
364

365
def batch_compile_models(input_dir: str, output_dir: str, target: str = "llvm-cpu"):
366
    """Batch compile all MLIR files in a directory."""
367
    input_path = Path(input_dir)
368
    output_path = Path(output_dir)
369
    output_path.mkdir(exist_ok=True)
370
    
371
    mlir_files = list(input_path.glob("*.mlir"))
372
    
373
    for mlir_file in mlir_files:
374
        output_file = output_path / f"{mlir_file.stem}.vmfb"
375
        
376
        cmd = [
377
            "iree-compile",
378
            str(mlir_file),
379
            f"--iree-hal-target-backends={target}",
380
            "-o", str(output_file)
381
        ]
382
        
383
        try:
384
            result = subprocess.run(cmd, check=True, capture_output=True, text=True)
385
            print(f"✓ Compiled {mlir_file.name}")
386
        except subprocess.CalledProcessError as e:
387
            print(f"✗ Failed to compile {mlir_file.name}: {e.stderr}")
388

389
# Usage
390
batch_compile_models("./models", "./compiled", "cuda")
391
```