0
# Groovy Compilation
1

2
The Groovyc Ant task provides comprehensive compilation of Groovy and Java source files with support for joint compilation, extensive configuration options, and integration with existing Java build processes.
3

4
## Capabilities
5

6
### Groovyc Task
7

8
Compiles Groovy source files with full support for Java integration, classpath management, and build customization.
9

10
```java { .api }
11
/**
12
 * Compiles Groovy source files using Ant, supporting both standalone Groovy
13
 * compilation and joint compilation with Java sources.
14
 */
15
public class Groovyc extends org.apache.tools.ant.taskdefs.MatchingTask {
16
    /** Add a path for source compilation */
17
    public Path createSrc();
18
    
19
    /** Set the source directories to find source files */
20
    public void setSrcdir(Path srcDir);
21
    
22
    /** Get the source directories */
23
    public Path getSrcdir();
24
    
25
    /** Set the extension for Groovy source files (*.groovy, .groovy, or groovy) */
26
    public void setScriptExtension(String scriptExtension);
27
    
28
    /** Get the Groovy source file extension */
29
    public String getScriptExtension();
30
    
31
    /** Set bytecode compatibility level (1.8, 11, 17, etc.) */
32
    public void setTargetBytecode(String version);
33
    
34
    /** Get bytecode compatibility level */
35
    public String getTargetBytecode();
36
    
37
    /** Set destination directory for compiled classes */
38
    public void setDestdir(File destDir);
39
    
40
    /** Get destination directory */
41
    public File getDestdir();
42
    
43
    /** Set the sourcepath for compilation */
44
    public void setSourcepath(Path sourcepath);
45
    
46
    /** Get the sourcepath */
47
    public Path getSourcepath();
48
    
49
    /** Create nested sourcepath element */
50
    public Path createSourcepath();
51
    
52
    /** Set sourcepath using reference */
53
    public void setSourcepathRef(Reference r);
54
    
55
    /** Set compilation classpath */
56
    public void setClasspath(Path classpath);
57
    
58
    /** Get compilation classpath */
59
    public Path getClasspath();
60
    
61
    /** Create nested classpath element */
62
    public Path createClasspath();
63
    
64
    /** Set classpath using reference */
65
    public void setClasspathRef(Reference r);
66
    
67
    /** List source files being compiled */
68
    public void setListfiles(boolean list);
69
    
70
    /** Check if listing files */
71
    public boolean getListfiles();
72
    
73
    /** Continue build even if compilation errors occur */
74
    public void setFailonerror(boolean fail);
75
    
76
    /** Inverse of failonerror - proceed on errors */
77
    public void setProceed(boolean proceed);
78
    
79
    /** Get failonerror setting */
80
    public boolean getFailonerror();
81
    
82
    /** Set initial memory size for forked JVM */
83
    public void setMemoryInitialSize(String memoryInitialSize);
84
    
85
    /** Get initial memory size */
86
    public String getMemoryInitialSize();
87
    
88
    /** Set maximum memory size for forked JVM */
89
    public void setMemoryMaximumSize(String memoryMaximumSize);
90
    
91
    /** Get maximum memory size */
92
    public String getMemoryMaximumSize();
93
    
94
    /** Set file encoding for source files */
95
    public void setEncoding(String encoding);
96
    
97
    /** Get file encoding */
98
    public String getEncoding();
99
    
100
    /** Enable verbose compilation output */
101
    public void setVerbose(boolean verbose);
102
    
103
    /** Check verbose setting */
104
    public boolean getVerbose();
105
    
106
    /** Include Ant's classpath in compilation */
107
    public void setIncludeantruntime(boolean include);
108
    
109
    /** Check if including Ant runtime classpath */
110
    public boolean getIncludeantruntime();
111
    
112
    /** Include Java runtime libraries in classpath */
113
    public void setIncludejavaruntime(boolean include);
114
    
115
    /** Check if including Java runtime */
116
    public boolean getIncludejavaruntime();
117
    
118
    /** Fork compilation into separate JVM */
119
    public void setFork(boolean f);
120
    
121
    /** Set JDK home for forked compilation */
122
    public void setJavaHome(File home);
123
    
124
    /** Set executable for forked compilation */
125
    public void setExecutable(String forkExecPath);
126
    
127
    /** Get executable path */
128
    public String getExecutable();
129
    
130
    /** Set property name to set on successful compilation */
131
    public void setUpdatedProperty(String updatedProperty);
132
    
133
    /** Set property name to set on compilation failure */
134
    public void setErrorProperty(String errorProperty);
135
    
136
    /** Include destination classes directory in classpath */
137
    public void setIncludeDestClasses(boolean includeDestClasses);
138
    
139
    /** Check if including destination classes */
140
    public boolean isIncludeDestClasses();
141
    
142
    /** Get compilation success status */
143
    public boolean getTaskSuccess();
144
    
145
    /** Add nested javac task for joint compilation */
146
    public void addConfiguredJavac(org.apache.tools.ant.taskdefs.Javac javac);
147
    
148
    /** Enable stack trace reporting on compilation errors */
149
    public void setStacktrace(boolean stacktrace);
150
    
151
    /** Enable invokedynamic support */
152
    public void setIndy(boolean useIndy);
153
    
154
    /** Check invokedynamic setting */
155
    public boolean getIndy();
156
    
157
    /** Set base class for scripts */
158
    public void setScriptBaseClass(String scriptBaseClass);
159
    
160
    /** Get base class for scripts */
161
    public String getScriptBaseClass();
162
    
163
    /** Set configuration script path */
164
    public void setConfigscript(String configscript);
165
    
166
    /** Get configuration script path */
167
    public String getConfigscript();
168
    
169
    /** Set directory for Java stub generation */
170
    public void setStubdir(File stubDir);
171
    
172
    /** Get stub generation directory */
173
    public File getStubdir();
174
    
175
    /** Keep generated stub files for debugging */
176
    public void setKeepStubs(boolean keepStubs);
177
    
178
    /** Check if keeping stubs */
179
    public boolean getKeepStubs();
180
    
181
    /** Force lookup of unnamed files on classpath */
182
    public void setForceLookupUnnamedFiles(boolean forceLookupUnnamedFiles);
183
    
184
    /** Check force lookup setting */
185
    public boolean getForceLookupUnnamedFiles();
186
    
187
    /** Generate parameter metadata for reflection */
188
    public void setParameters(boolean parameters);
189
    
190
    /** Check parameter metadata setting */
191
    public boolean getParameters();
192
    
193
    /** Enable preview Java features (JDK 12+) */
194
    public void setPreviewFeatures(boolean previewFeatures);
195
    
196
    /** Check preview features setting */
197
    public boolean getPreviewFeatures();
198
    
199
    /** Execute compilation */
200
    public void execute() throws BuildException;
201
    
202
    /** Get list of files to compile */
203
    public File[] getFileList();
204
}
205
```
206

207
### Joint Compilation Support
208

209
Integration with Java compilation through nested javac task configuration.
210

211
```java { .api }
212
/**
213
 * Nested Javac task for joint Java/Groovy compilation.
214
 * Supports all standard javac attributes and nested elements.
215
 */
216
public class Javac extends org.apache.tools.ant.taskdefs.Javac {
217
    /** Enable debug information in compiled classes */
218
    public void setDebug(boolean debug);
219
    
220
    /** Set debug level (lines, vars, source) */
221
    public void setDebugLevel(String level);
222
    
223
    /** Show deprecation warnings */
224
    public void setDeprecation(boolean deprecation);
225
    
226
    /** Disable all warnings */
227
    public void setNowarn(boolean nowarn);
228
    
229
    /** Enable verbose output */
230
    public void setVerbose(boolean verbose);
231
    
232
    /** Set source compatibility level */
233
    public void setSource(String source);
234
    
235
    /** Set target bytecode level */
236
    public void setTarget(String target);
237
    
238
    /** Set release version (JDK 9+) */
239
    public void setRelease(String release);
240
    
241
    /** Set file encoding */
242
    public void setEncoding(String encoding);
243
    
244
    /** Set bootstrap classpath */
245
    public void setBootclasspath(Path bootclasspath);
246
    
247
    /** Set module path */
248
    public void setModulepath(Path modulepath);
249
    
250
    /** Set module source path */
251
    public void setModulesourcepath(Path modulesourcepath);
252
    
253
    /** Set upgrade module path */  
254
    public void setUpgrademodulepath(Path upgrademodulepath);
255
}
256
```
257

258
## Usage Examples
259

260
### Basic Groovy Compilation
261
```xml
262
<groovyc srcdir="src/main/groovy" 
263
         destdir="build/classes"
264
         includeantruntime="false">
265
    <classpath>
266
        <fileset dir="lib" includes="*.jar"/>
267
    </classpath>
268
</groovyc>
269
```
270

271
### Joint Java/Groovy Compilation
272
```xml
273
<groovyc srcdir="src" 
274
         destdir="build/classes"
275
         stubdir="build/stubs"
276
         keepStubs="false"
277
         fork="true"
278
         includeantruntime="false">
279
    <classpath>
280
        <path refid="compile.classpath"/>
281
    </classpath>
282
    
283
    <!-- Configure Java compilation -->
284
    <javac debug="true" 
285
           source="1.8" 
286
           target="1.8"
287
           encoding="UTF-8">
288
        <compilerarg value="-Xlint:unchecked"/>
289
    </javac>
290
</groovyc>
291
```
292

293
### Advanced Configuration
294
```xml
295
<groovyc srcdir="src/main/groovy"
296
         destdir="build/classes"
297
         fork="true"
298
         memoryInitialSize="128m"
299
         memoryMaximumSize="512m"
300
         verbose="true"
301
         listfiles="true"
302
         stacktrace="true"
303
         encoding="UTF-8"
304
         targetBytecode="11"
305
         indy="true"
306
         parameters="true"
307
         scriptBaseClass="com.example.CustomScriptBase"
308
         configscript="config/compiler-config.groovy">
309
    
310
    <classpath>
311
        <path refid="compile.classpath"/>
312
        <pathelement location="build/resources"/>
313
    </classpath>
314
    
315
    <include name="**/*.groovy"/>
316
    <exclude name="**/*Test.groovy"/>
317
</groovyc>
318
```
319

320
### Forked Compilation with Custom JDK
321
```xml
322
<groovyc srcdir="src"
323
         destdir="build/classes"
324
         fork="true"
325
         javaHome="/usr/lib/jvm/java-11-openjdk"
326
         executable="java"
327
         includeantruntime="false"
328
         includejavaruntime="false">
329
    
330
    <classpath>
331
        <fileset dir="lib" includes="*.jar"/>
332
    </classpath>
333
</groovyc>
334
```
335

336
### Conditional Compilation with Properties
337
```xml
338
<groovyc srcdir="src/main/groovy"
339
         destdir="build/classes"
340
         failonerror="${compilation.strict}"
341
         verbose="${compilation.verbose}"
342
         updatedProperty="groovy.compilation.success"
343
         errorProperty="groovy.compilation.failed">
344
    
345
    <classpath refid="compile.classpath"/>
346
</groovyc>
347

348
<!-- Check compilation result -->
349
<fail if="groovy.compilation.failed" 
350
      message="Groovy compilation failed"/>
351
```
352

353
### Multi-Source Directory Compilation
354
```xml
355
<groovyc destdir="build/classes" includeantruntime="false">
356
    <src path="src/main/groovy"/>
357
    <src path="src/generated/groovy"/>
358
    <src path="build/processed-sources"/>
359
    
360
    <classpath>
361
        <path refid="compile.classpath"/>
362
    </classpath>
363
    
364
    <include name="**/*.groovy"/>
365
    <exclude name="**/internal/**"/>
366
</groovyc>
367
```
368

369
### Custom Script Extension and File Patterns
370
```xml
371
<groovyc srcdir="scripts"
372
         destdir="build/script-classes"
373
         scriptExtension="*.gvy">
374
    
375
    <include name="**/*.gvy"/>
376
    <include name="**/*.gsh"/>
377
    <exclude name="**/test/**"/>
378
    
379
    <classpath>
380
        <path refid="runtime.classpath"/>
381
    </classpath>
382
</groovyc>
383
```
384

385
## Configuration Scripts
386

387
Compiler behavior can be customized using configuration scripts:
388

389
```groovy
390
// config/compiler-config.groovy
391
import org.codehaus.groovy.control.customizers.*
392

393
// Add import customization
394
def importCustomizer = new ImportCustomizer()
395
importCustomizer.addStaticStars('java.lang.Math')
396
importCustomizer.addImports('java.util.concurrent.TimeUnit')
397
configuration.addCompilationCustomizers(importCustomizer)
398

399
// Add AST transformations
400
def astCustomizer = new ASTTransformationCustomizer(
401
    CompileStatic.class
402
)
403
configuration.addCompilationCustomizers(astCustomizer)
404

405
// Configure optimization
406
configuration.optimizationOptions.put('indy', true)
407
configuration.optimizationOptions.put('int', false)
408
```
409

410
## Error Handling and Diagnostics
411

412
### Compilation Error Information
413

414
```java { .api }
415
public class BuildException extends RuntimeException {
416
    /** Create exception with message */
417
    public BuildException(String message);
418
    
419
    /** Create exception with message and cause */
420
    public BuildException(String message, Throwable cause);
421
    
422
    /** Get the location where error occurred */
423
    public Location getLocation();
424
    
425
    /** Set the location where error occurred */
426
    public void setLocation(Location location);
427
}
428

429
public class Location {
430
    /** Get filename where error occurred */
431
    public String getFileName();
432
    
433
    /** Get line number of error */
434
    public int getLineNumber();
435
    
436
    /** Get column number of error */
437
    public int getColumnNumber();
438
}
439
```
440

441
### Debug and Verbose Output
442

443
When verbose mode is enabled, the compiler provides detailed information about:
444
- Files being processed
445
- Classpath resolution
446
- Compilation phases
447
- Stub generation (for joint compilation)
448
- Memory usage and performance metrics
449

450
### Memory Management
451

452
For large codebases, proper memory configuration is essential:
453
- `memoryInitialSize`: Starting heap size (e.g., "256m")
454
- `memoryMaximumSize`: Maximum heap size (e.g., "1g") 
455
- `fork="true"`: Required for memory settings to take effect