0
# Pantsbuild Pants Contrib Spindle
1
2
A Pants build system plugin that enables automatic generation of Scala libraries from Thrift IDL files using Foursquare's Spindle code generator. This plugin integrates Spindle's thrift-to-Scala compilation into the Pants build pipeline, providing seamless dependency management and incremental compilation for large-scale projects.
3
4
## Package Information
5
6
- **Package Name**: pantsbuild.pants.contrib.spindle
7
- **Language**: Python
8
- **Installation**: `pip install pantsbuild.pants.contrib.spindle`
9
- **Plugin Type**: Pants build system contrib plugin
10
11
## Core Imports
12
13
```python
14
from pants.contrib.spindle.register import build_file_aliases, register_goals
15
from pants.contrib.spindle.targets.spindle_thrift_library import SpindleThriftLibrary
16
from pants.contrib.spindle.tasks.spindle_gen import SpindleGen
17
```
18
19
## Basic Usage
20
21
### Plugin Registration
22
23
This plugin is typically registered automatically when installed. In Pants configuration:
24
25
```python
26
# pants.ini or pants.toml
27
[DEFAULT]
28
# The plugin provides 'spindle_thrift_library' target type and 'spindle' task
29
```
30
31
### BUILD File Usage
32
33
```python
34
# In a BUILD file
35
spindle_thrift_library(
36
name='user-service-thrift',
37
sources=['user.thrift', 'profile.thrift'],
38
dependencies=[
39
'3rdparty:spindle-runtime',
40
],
41
)
42
```
43
44
### Command Line Usage
45
46
```bash
47
# Generate Scala code from Thrift files
48
pants gen.spindle src/main/thrift:user-service-thrift
49
50
# The generated Scala and Java files will be placed in the workspace
51
# under appropriate namespace directories
52
```
53
54
### Example Thrift File
55
56
```thrift
57
namespace java com.example.user
58
59
typedef string UserId
60
61
struct User {
62
1: required UserId id
63
2: required string name
64
3: optional string email
65
}
66
67
service UserService {
68
User getUser(1: UserId userId)
69
list<User> listUsers()
70
}
71
```
72
73
## Capabilities
74
75
### Plugin Registration
76
77
Registration functions that integrate the plugin with the Pants build system.
78
79
```python { .api }
80
def build_file_aliases():
81
"""
82
Returns build file aliases for the spindle plugin.
83
84
Returns:
85
BuildFileAliases: Aliases containing the 'spindle_thrift_library' target type
86
"""
87
88
def register_goals():
89
"""
90
Registers the 'spindle' task under the 'gen' goal.
91
92
Installs the SpindleGen task to be executed when 'gen.spindle' is invoked.
93
"""
94
```
95
96
### Target Types
97
98
Target type for defining Thrift libraries that will be compiled to Scala using Spindle.
99
100
```python { .api }
101
class SpindleThriftLibrary(ExportableJvmLibrary):
102
"""
103
A Scala library generated from Spindle IDL files.
104
105
This target type represents Thrift files that should be compiled to Scala
106
using the Spindle code generator. Inherits from ExportableJvmLibrary to
107
provide JVM library capabilities.
108
"""
109
110
def __init__(self, *args, **kwargs):
111
"""
112
Initialize a SpindleThriftLibrary target.
113
114
Automatically adds 'scala', 'codegen', and 'synthetic' labels to the target.
115
116
Args:
117
*args: Variable arguments passed to parent ExportableJvmLibrary
118
**kwargs: Keyword arguments passed to parent ExportableJvmLibrary
119
"""
120
```
121
122
### Code Generation Task
123
124
The main task that performs Thrift-to-Scala code generation using Spindle.
125
126
```python { .api }
127
class SpindleGen(NailgunTask):
128
"""
129
Task that generates Scala code from Thrift files using Spindle.
130
131
This task processes SpindleThriftLibrary targets, executes the Spindle
132
code generator, and creates synthetic Scala and Java library targets
133
with the generated code.
134
"""
135
136
@classmethod
137
def product_types(cls):
138
"""
139
Returns the product types produced by this task.
140
141
Returns:
142
list: ['scala'] - indicates this task produces Scala code
143
"""
144
145
@classmethod
146
def register_options(cls, register):
147
"""
148
Register command-line options for the SpindleGen task.
149
150
Args:
151
register: Option registration function
152
153
Registers:
154
--runtime-dependency: Runtime dependencies for generated code
155
--spindle-codegen tool: Spindle code generator tool configuration
156
"""
157
158
@property
159
def spindle_classpath(self):
160
"""
161
Get the classpath for the Spindle code generator tool.
162
163
Returns:
164
list: Classpath entries for spindle-codegen tool
165
"""
166
167
@property
168
def synthetic_target_extra_dependencies(self):
169
"""
170
Get additional dependencies for synthetic targets.
171
172
Returns:
173
set: Set of dependency targets from runtime-dependency option
174
"""
175
176
@property
177
def namespace_out(self):
178
"""
179
Get the output directory for generated code.
180
181
Returns:
182
str: Path to output directory (workdir/src/jvm)
183
"""
184
185
def codegen_targets(self):
186
"""
187
Get all targets that need code generation.
188
189
Returns:
190
list: List of SpindleThriftLibrary targets
191
"""
192
193
def sources_generated_by_target(self, target):
194
"""
195
Calculate the source files that will be generated for a target.
196
197
Args:
198
target: SpindleThriftLibrary target
199
200
Returns:
201
list: List of paths to generated source files
202
"""
203
204
def execute_codegen(self, targets):
205
"""
206
Execute the Spindle code generation process.
207
208
Args:
209
targets: List of SpindleThriftLibrary targets to process
210
211
Raises:
212
TaskError: If code generation fails
213
"""
214
215
def execute(self):
216
"""
217
Main execution method for the task.
218
219
Orchestrates the entire code generation process:
220
1. Identifies targets needing generation
221
2. Executes code generation for invalid targets
222
3. Creates synthetic Scala and Java library targets
223
4. Manages dependencies and build graph updates
224
5. Updates artifact cache if enabled
225
"""
226
```
227
228
### Utility Functions
229
230
Helper functions for calculating generated file paths and parsing Thrift files.
231
232
```python { .api }
233
def calculate_genfiles(source):
234
"""
235
Calculate which files will be generated from a Thrift source file.
236
237
Parses the Thrift file to extract namespace information and determines
238
the output file paths that Spindle will generate.
239
240
Args:
241
source (str): Path to Thrift source file relative to build root
242
243
Returns:
244
list: List of generated file basenames (without .scala/.java extensions)
245
246
Raises:
247
TaskError: If no Java namespace is found in the source file
248
"""
249
250
def calculate_scala_record_genfiles(namespace, source):
251
"""
252
Calculate generated file basenames for Scala records.
253
254
Args:
255
namespace (str): Java namespace from Thrift file
256
source (str): Path to source Thrift file
257
258
Returns:
259
list: List of generated file paths (basenames, add .scala/.java for full path)
260
"""
261
```
262
263
## Types
264
265
### Build System Integration Types
266
267
```python { .api }
268
BuildFileAliases:
269
"""
270
Pants build system type for registering target aliases.
271
Contains mappings from target names to target classes.
272
"""
273
274
TaskRegistrar:
275
"""
276
Pants build system type for registering tasks under goals.
277
Provides the task() method for goal registration.
278
"""
279
280
ExportableJvmLibrary:
281
"""
282
Base class for JVM library targets that can be exported.
283
Provides standard JVM library functionality and export capabilities.
284
"""
285
286
NailgunTask:
287
"""
288
Base class for tasks that execute JVM tools via Nailgun.
289
Provides JVM tool execution and classpath management.
290
"""
291
```
292
293
### Configuration Types
294
295
```python { .api }
296
JarDependency:
297
"""
298
Represents a JAR dependency with org, name, and revision.
299
Used to specify the Spindle codegen tool dependency.
300
"""
301
302
# Default tool configuration
303
SPINDLE_CODEGEN_DEFAULT = JarDependency(
304
org='com.foursquare',
305
name='spindle-codegen-binary_2.10',
306
rev='3.0.0-M7'
307
)
308
```
309
310
## Error Handling
311
312
The plugin raises `TaskError` exceptions in the following cases:
313
314
- **Missing namespace**: When a Thrift file lacks a required Java namespace declaration
315
- **Code generation failure**: When the Spindle code generator returns a non-zero exit code
316
- **File system errors**: When output directories cannot be created or accessed
317
318
## Plugin Configuration
319
320
### Default Settings
321
322
- **Runtime dependency**: `['3rdparty:spindle-runtime']`
323
- **Spindle version**: `3.0.0-M7` (com.foursquare:spindle-codegen-binary_2.10)
324
- **Templates**:
325
- Scala: `scala/record.ssp`
326
- Java: `javagen/record.ssp`
327
328
### Options
329
330
```bash
331
# Configure runtime dependencies
332
pants gen.spindle --runtime-dependency=path/to:runtime-dep
333
334
# Configure JVM options for code generation
335
pants gen.spindle --jvm-options="-Xmx2g -XX:MaxPermSize=256m"
336
```
337
338
## Generated Output
339
340
The plugin generates:
341
342
1. **Scala files**: `.scala` files containing Scala case classes and companion objects
343
2. **Java files**: `.java` files with Java representations for interoperability
344
3. **Synthetic targets**: Scala and Java library targets with proper dependency management
345
4. **Namespace structure**: Files organized according to Thrift namespace declarations
346
347
Generated files follow the pattern:
348
- Input: `com/example/user.thrift` with `namespace java com.example.user`
349
- Output: `src/jvm/com/example/user/user.scala` and `src/jvm/com/example/user/java_user.java`