0
# Core Compilation Functions
1

2
High-level compilation functions that provide the primary interface for compiling MLIR code to IREE VM modules. These functions support various input formats, target backends, and compilation options for ML model deployment workflows.
3

4
## Capabilities
5

6
### String Compilation
7

8
Compiles MLIR assembly provided as a string or bytes object directly to VM bytecode.
9

10
```python { .api }
11
def compile_str(input_str: Union[str, bytes], **kwargs) -> Optional[bytes]:
12
    """
13
    Invokes the IREE compiler with an input string.
14

15
    Parameters:
16
    - input_str: MLIR assembly to parse/compile (str or bytes)
17
    - **kwargs: Keyword arguments corresponding to CompilerOptions
18

19
    Returns:
20
    Optional[bytes]: Compiled binary content, or None if output_file was specified
21
    """
22
```
23

24
### File Compilation
25

26
Compiles MLIR assembly from a file to VM bytecode.
27

28
```python { .api }
29
def compile_file(input_file: str, **kwargs) -> Optional[bytes]:
30
    """
31
    Invokes the IREE compiler on an input file.
32

33
    Parameters:
34
    - input_file: File containing MLIR assembly to compile
35
    - **kwargs: Keyword arguments corresponding to CompilerOptions
36

37
    Returns:
38
    Optional[bytes]: Compiled binary content, or None if output_file was specified
39
    """
40
```
41

42
### Target Backend Query
43

44
Queries available target backends for hardware-specific compilation.
45

46
```python { .api }
47
def query_available_targets() -> List[str]:
48
    """
49
    Returns a collection of target names that are registered.
50

51
    Returns:
52
    List[str]: Available target backend names
53
    """
54
```
55

56
### Compiler Options
57

58
Configuration object for controlling compilation behavior and output format.
59

60
```python { .api }
61
class CompilerOptions:
62
    """
63
    Options to the compiler backend.
64

65
    Attributes:
66
    - output_file: Optional[str], save compiled binary to file instead of returning
67
    - target_backends: Sequence[str], list of target backends to compile for
68
    - input_type: Union[InputType, str], input legalization type (default: AUTO)
69
    - output_format: Union[OutputFormat, str], output format (default: FLATBUFFER_BINARY)
70
    - extra_args: Sequence[str], additional compiler arguments
71
    - optimize: bool, apply default optimizations (default: True)
72
    - output_mlir_debuginfo: bool, include debuginfo in MLIR (default: True)
73
    - output_generic_mlir: bool, use generic MLIR formatting (default: False)
74
    - extended_diagnostics: bool, output verbose diagnostics (default: False)
75
    - strip_debug_ops: bool, strip debug operations (default: False)
76
    - strip_source_map: bool, strip source map information (default: False)
77
    - crash_reproducer_path: Optional[str], crash dump output path
78
    - enable_tflite_bindings: bool, support TFLite runtime API (default: False)
79
    - enable_benchmark: bool, generate instrumented binaries (default: False)
80
    """
81
    
82
    def __init__(self, **kwargs): ...
83
```
84

85
### Input Types
86

87
Enumeration of supported input format types for model compilation.
88

89
```python { .api }
90
class InputType(Enum):
91
    """
92
    Enumeration of allowable input types to the compiler.
93
    """
94
    NONE = "none"
95
    AUTO = "auto"
96
    STABLEHLO = "stablehlo"
97
    STABLEHLO_XLA = "stablehlo_xla"
98
    TOSA = "tosa"
99
    TM_TENSOR = "tm_tensor"
100
    TORCH = "torch"
101
    ONNX = "onnx"
102
    
103
    @staticmethod
104
    def parse(spec: Union[str, InputType]) -> InputType: ...
105
```
106

107
### Output Formats
108

109
Enumeration of supported output formats for compiled modules.
110

111
```python { .api }
112
class OutputFormat(Enum):
113
    """
114
    The output format of the compiler.
115
    """
116
    FLATBUFFER_BINARY = "flatbuffer-binary"
117
    FLATBUFFER_TEXT = "flatbuffer-text"
118
    MLIR_TEXT = "mlir-text"
119
    
120
    @staticmethod
121
    def parse(spec: Union[str, OutputFormat]) -> OutputFormat: ...
122
```
123

124
### Error Handling
125

126
Exception raised when compiler tools encounter errors during execution.
127

128
```python { .api }
129
class CompilerToolError(Exception):
130
    """
131
    Exception raised when a compiler tool fails.
132
    """
133
```
134

135
### Debugging Support
136

137
File management utility for preserving intermediate compilation artifacts during debugging.
138

139
```python { .api }
140
class TempFileSaver:
141
    """
142
    Utility for managing temporary files during compilation with optional retention.
143
    """
144
    
145
    @staticmethod
146
    def implicit() -> TempFileSaver: ...
147
    
148
    def alloc_optional(self, name: str, export_as: Optional[str] = None) -> Optional[str]: ...
149
```
150

151
### Default Testing Configuration
152

153
Default backend and driver constants for testing and development workflows.
154

155
```python { .api }
156
DEFAULT_TESTING_BACKENDS: List[str] = ["llvm-cpu"]
157
DEFAULT_TESTING_DRIVER: str = "local-task"
158
```
159

160
### Binary Utilities
161

162
Utilities for locating and invoking compiler tool binaries.
163

164
```python { .api }
165
def find_tool(exe_name: str) -> str:
166
    """
167
    Finds a tool by its executable name.
168
    
169
    Parameters:
170
    - exe_name: Name of the executable (extension-less)
171
    
172
    Returns:
173
    str: Absolute path to the tool
174
    
175
    Raises:
176
    ValueError: If the tool is not known or not found
177
    """
178

179
def get_tool_path() -> List[str]:
180
    """
181
    Returns list of paths to search for tools.
182
    
183
    Returns:
184
    List[str]: List of tool search paths
185
    """
186

187
def invoke_immediate(command_line: List[str], *, input_file: Optional[bytes] = None, immediate_input=None):
188
    """
189
    Invokes an immediate command.
190
    
191
    Parameters:
192
    - command_line: Command line arguments as list
193
    - input_file: Optional input file path
194
    - immediate_input: Optional immediate input data
195
    
196
    Returns:
197
    bytes: Command output
198
    
199
    Raises:
200
    CompilerToolError: If command fails
201
    """
202

203
def build_compile_command_line(input_file: str, tfs: TempFileSaver, options: CompilerOptions) -> List[str]:
204
    """
205
    Builds a command line for invoking the compiler.
206
    
207
    Parameters:
208
    - input_file: Input file name
209
    - tfs: TempFileSaver instance
210
    - options: Compiler options
211
    
212
    Returns:
213
    List[str]: Command line arguments
214
    """
215
```
216

217
## Usage Examples
218

219
### Basic Compilation
220

221
```python
222
import iree.compiler.tools
223

224
# Compile MLIR string for CPU target
225
mlir_code = """
226
func.func @add(%arg0: tensor<4xf32>, %arg1: tensor<4xf32>) -> tensor<4xf32> {
227
    %0 = arith.addf %arg0, %arg1 : tensor<4xf32>
228
    return %0 : tensor<4xf32>
229
}
230
"""
231

232
binary = iree.compiler.tools.compile_str(
233
    mlir_code,
234
    target_backends=["llvm-cpu"],
235
    input_type="auto"
236
)
237
```
238

239
### Advanced Compilation with Options
240

241
```python
242
from iree.compiler.tools import CompilerOptions, compile_file
243

244
# Configure detailed compilation options
245
options = CompilerOptions(
246
    target_backends=["llvm-cpu", "cuda"],
247
    output_file="model.vmfb",
248
    optimize=True,
249
    output_mlir_debuginfo=True,
250
    extra_args=["--iree-flow-enable-fusing", "--mlir-print-ir-after-all"]
251
)
252

253
# Compile from file
254
compile_file("input_model.mlir", **options.__dict__)
255
```
256

257
### Target Backend Discovery
258

259
```python
260
# Query available hardware targets
261
available_targets = iree.compiler.tools.query_available_targets()
262
print("Available targets:", available_targets)
263
# Output: ['llvm-cpu', 'cuda', 'vulkan-spirv', 'rocm', ...]
264
```