Groovyc (Groovy 5.1.0)

Package: org.codehaus.groovy.ant

## [Java] Class Groovyc

- org.codehaus.groovy.ant.Groovyc

-     public class Groovyc
      extends MatchingTask

  Compiles Groovy source files using Ant.

  Typically involves using Ant from the command-line and an Ant build file such as:

       <?xml version="1.0"?>
       <project name="MyGroovyBuild" default="compile">
         <property name="groovy.home" location="/Path/To/Groovy"/>
         <property name="groovy.version" value="X.Y.Z"/>

         <taskdef name="groovyc" classname="org.codehaus.groovy.ant.Groovyc">
           <classpath>
             <fileset file="${groovy.home}/lib/groovy-${groovy.version}.jar"/>
             <fileset file="${groovy.home}/lib/groovy-ant-${groovy.version}.jar"/>
           </classpath>
         </taskdef>

         <target name="compile" description="compile groovy sources">
           <groovyc srcdir="src" destdir="bin" fork="true" listfiles="true" includeantruntime="false">
             <classpath>
               <fileset dir="${groovy.home}/lib" includes="groovy-*${groovy.version}.jar" excludes="groovy-ant-${groovy.version}.jar"/>
             </classpath>
           </groovyc>
         </target>
       </project>

  This task can take the following arguments:

  - srcdir
  - destdir
  - sourcepath
  - sourcepathRef
  - classpath
  - classpathRef
  - scriptExtension
  - targetBytecode
  - listfiles
  - failonerror
  - proceed
  - memoryInitialSize
  - memoryMaximumSize
  - encoding
  - verbose
  - includeantruntime
  - includejavaruntime
  - fork
  - javaHome
  - executable
  - updatedProperty
  - errorProperty
  - includeDestClasses
  - jointCompilationOptions
  - stacktrace
  - scriptBaseClass
  - stubdir
  - keepStubs
  - forceLookupUnnamedFiles
  - configscript
  - parameters
  And these nested tasks:
  - javac
  Of these arguments, the srcdir and destdir are required.

  When this task executes, it will recursively scan srcdir and destdir looking for Groovy source files to compile. This task makes its compile decision based on timestamp.

  A more elaborate build file showing joint compilation:

       <?xml version="1.0"?>
       <project name="MyJointBuild" default="compile">
         <property name="groovy.home" location="/Path/To/Groovy"/>
         <property name="groovy.version" value="X.Y.Z"/>

         <path id="classpath.main">
           <fileset dir="${groovy.home}/lib">
             <include name="groovy-*${groovy.version}.jar"/>
             <exclude name="groovy-ant-${groovy.version}.jar"/>
           </fileset>
         </path>

         <taskdef name="groovyc" classname="org.codehaus.groovy.ant.Groovyc">
           <classpath>
             <fileset file="${groovy.home}/lib/groovy-${groovy.version}.jar"/>
             <fileset file="${groovy.home}/lib/groovy-ant-${groovy.version}.jar"/>
           </classpath>
         </taskdef>

         <target name="clean">
           <delete dir="bin" failonerror="false"/>
         </target>

         <target name="compile" depends="clean" description="compile java and groovy sources">
           <mkdir dir="bin"/>

           <groovyc srcdir="src" destdir="bin" stubdir="stubs" keepStubs="true"
            fork="true" includeantruntime="false" classpathref="classpath.main">
             <javac debug="true" source="1.8" target="1.8"/>
           </groovyc>
         </target>
       </project>

  Based on the implementation of the Javac task in Apache Ant.

  Can also be used from AntBuilder to allow the build file to be scripted in Groovy.

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected File[]` | `compileList` |
    `protected CompilerConfiguration` | `configuration` |
    `protected boolean` | `failOnError` |
    `protected boolean` | `listFiles` |

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `addConfiguredJavac(Javac javac)` Add the configured nested javac task if present to initiate joint compilation.
    `` | `protected void` | `addToCompileList(File[] newFiles)`
    `` | `protected GroovyClassLoader` | `buildClassLoaderFor()`
    `` | `protected void` | `checkParameters()`
    `` | `protected void` | `compile()`
    `` | `public Path` | `createClasspath()` Adds a path to the classpath.
    `` | `public Path` | `createSourcepath()` Adds a path to sourcepath.
    `` | `public Path` | `createSrc()` Adds a path for source compilation.
    `` | `public void` | `execute()` Executes the task.
    `` | `public Path` | `getClasspath()` Gets the classpath to be used for this compilation.
    `` | `public String` | `getConfigscript()` Get the configuration file used to customize the compilation configuration.
    `` | `public File` | `getDestdir()` Gets the destination directory into which the java source files should be compiled.
    `` | `public String` | `getEncoding()` Returns the encoding to be used when creating files.
    `` | `public String` | `getExecutable()` The value of the executable attribute, if any.
    `` | `public boolean` | `getFailonerror()` Gets the failonerror flag.
    `` | `public File[]` | `getFileList()` Gets the list of files to be compiled.
    `` | `public boolean` | `getForceLookupUnnamedFiles()` Gets the forceLookupUnnamedFiles flag.
    `` | `public boolean` | `getIncludeantruntime()` Gets whether the ant classpath is to be included in the classpath.
    `` | `public boolean` | `getIncludejavaruntime()` Gets whether the java runtime should be included in this task's classpath.
    `` | `public boolean` | `getIndy()` Get the value of the indy flag (always true).
    `` | `public boolean` | `getKeepStubs()` Gets the keepStubs flag.
    `` | `public boolean` | `getListfiles()` Get the listfiles flag.
    `` | `public String` | `getMemoryInitialSize()` Gets the memoryInitialSize flag.
    `` | `public String` | `getMemoryMaximumSize()` Gets the memoryMaximumSize flag.
    `` | `public boolean` | `getParameters()` Returns true if parameter metadata generation has been enabled.
    `` | `public boolean` | `getPreviewFeatures()` Returns true if preview features has been enabled.
    `` | `public String` | `getScriptBaseClass()` Get the base script class name for the scripts (must derive from Script)
    `` | `public String` | `getScriptExtension()` Get the extension to use when searching for Groovy source files.
    `` | `public Path` | `getSourcepath()` Gets the sourcepath to be used for this compilation.
    `` | `public Path` | `getSrcdir()` Gets the source dirs to find the source java files.
    `` | `public File` | `getStubdir()` Gets the stub directory into which the Java source stub files should be generated
    `` | `public String` | `getTargetBytecode()` Retrieves the compiler bytecode compatibility level.
    `` | `public boolean` | `getTaskSuccess()` Get the result of the groovyc task (success or failure).
    `` | `public boolean` | `getVerbose()` Gets the verbose flag.
    `` | `public boolean` | `isIncludeDestClasses()` Get the value of the includeDestClasses property.
    `` | `protected CompilationUnit` | `makeCompileUnit()` deprecated: This method is not in use anymore.
    `` | `protected CompilationUnit` | `makeCompileUnit(GroovyClassLoader loader)`
    `` | `protected Path` | `recreateSrc()` Recreate src.
    `` | `protected void` | `resetFileLists()` Clears the list of files to be compiled and copied.
    `` | `protected void` | `scanDir(File srcDir, File destDir, String[] files)` Scans the directory looking for source files to be compiled.
    `` | `public void` | `setClasspath(Path classpath)` Set the classpath to be used for this compilation.
    `` | `public void` | `setClasspathRef(Reference r)` Adds a reference to a classpath defined elsewhere.
    `` | `public void` | `setConfigscript(String configscript)` Set the configuration file used to customize the compilation configuration.
    `` | `public void` | `setDestdir(File destDir)` Set the destination directory into which the Java source files should be compiled.
    `` | `public void` | `setEncoding(String encoding)` Sets the file encoding for generated files.
    `` | `public void` | `setErrorProperty(String errorProperty)` The property to set on compilation failure.
    `` | `public void` | `setExecutable(String forkExecPath)` Sets the name of the java executable to use when invoking the compiler in forked mode, ignored otherwise.
    `` | `public void` | `setFailonerror(boolean fail)` Indicates whether the build will continue even if there are compilation errors; defaults to true.
    `` | `public void` | `setForceLookupUnnamedFiles(boolean forceLookupUnnamedFiles)` Set the forceLookupUnnamedFiles flag.
    `` | `public void` | `setFork(boolean f)` If true forks the Groovy compiler.
    `` | `public void` | `setIncludeDestClasses(boolean includeDestClasses)` This property controls whether to include the destination classes directory in the classpath given to the compiler.
    `` | `public void` | `setIncludeantruntime(boolean include)` If true, includes Ant's own classpath in the classpath.
    `` | `public void` | `setIncludejavaruntime(boolean include)` If true, includes the Java runtime libraries in the classpath.
    `` | `public void` | `setIndy(boolean indy)` Legacy method to set the indy flag (only true is allowed)
    `` | `public void` | `setJavaHome(File home)` The JDK Home to use when forked.
    `` | `public void` | `setKeepStubs(boolean keepStubs)` Set the keepStubs flag.
    `` | `public void` | `setListfiles(boolean list)` If true, list the source files being handed off to the compiler.
    `` | `public void` | `setMemoryInitialSize(String memoryInitialSize)` The initial size of the memory for the underlying VM if javac is run externally; ignored otherwise.
    `` | `public void` | `setMemoryMaximumSize(String memoryMaximumSize)` The maximum size of the memory for the underlying VM if javac is run externally; ignored otherwise.
    `` | `public void` | `setParameters(boolean parameters)` If true, generates metadata for reflection on method parameter names (jdk8+ only).
    `` | `public void` | `setPreviewFeatures(boolean previewFeatures)` If true, enable preview Java features (JEP 12) (jdk12+ only).
    `` | `public void` | `setProceed(boolean proceed)` Parameters: `proceed` - inverse of failonerror
    `` | `public void` | `setScriptBaseClass(String scriptBaseClass)` Set the base script class name for the scripts (must derive from Script)
    `` | `public void` | `setScriptExtension(String scriptExtension)` Set the extension to use when searching for Groovy source files.
    `` | `public void` | `setSourcepath(Path sourcepath)` Set the sourcepath to be used for this compilation.
    `` | `public void` | `setSourcepathRef(Reference r)` Adds a reference to a source path defined elsewhere.
    `` | `public void` | `setSrcdir(Path srcDir)` Set the source directories to find the source Java files.
    `` | `public void` | `setStacktrace(boolean stacktrace)` Enable compiler to report stack trace information if a problem occurs during compilation.
    `` | `public void` | `setStubdir(File stubDir)` Set the stub directory into which the Java source stub files should be generated.
    `` | `public void` | `setTargetBytecode(String version)` Sets the bytecode compatibility level.
    `` | `public void` | `setUpdatedProperty(String updatedProperty)` The property to set on compilation success.
    `` | `public void` | `setVerbose(boolean verbose)` Enable verbose compiling which will display which files are being compiled.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class MatchingTask` | `XsetIgnore, XsetItems, add, addAnd, addContains, addContainsRegexp, addCustom, addDate, addDepend, addDepth, addDifferent, addFilename, addMajority, addModified, addNone, addNot, addOr, addPresent, addSelector, addSize, addType, appendSelector, bindToOwner, clone, createExclude, createExcludesFile, createInclude, createIncludesFile, createPatternSet, equals, execute, getClass, getDescription, getLocation, getOwningTarget, getProject, getRuntimeConfigurableWrapper, getSelectors, getTaskName, getTaskType, hasSelectors, hashCode, init, log, log, log, log, maybeConfigure, notify, notifyAll, perform, reconfigure, selectorCount, selectorElements, setCaseSensitive, setDefaultexcludes, setDescription, setExcludes, setExcludesfile, setFollowSymlinks, setIncludes, setIncludesfile, setLocation, setOwningTarget, setProject, setRuntimeConfigurableWrapper, setTaskName, setTaskType, toString, wait, wait, wait`

- - ### Field Detail

    - #### protected File[] compileList

    - #### protected CompilerConfiguration configuration

    - #### protected boolean failOnError

    - #### protected boolean listFiles

  - ### Method Detail

    - #### public void addConfiguredJavac(Javac javac)

      Add the configured nested javac task if present to initiate joint compilation.

    - #### protected void addToCompileList(File[] newFiles)

    - #### protected GroovyClassLoader buildClassLoaderFor()

    - #### protected void checkParameters()

    - #### protected void compile()

    - #### public Path createClasspath()

      Adds a path to the classpath.

      Returns:
        a class path to be configured

    - #### public Path createSourcepath()

      Adds a path to sourcepath.

      Returns:
        a sourcepath to be configured

    - #### public Path createSrc()

      Adds a path for source compilation.

      Returns:
        a nested src element.

    - #### @Override
      public void execute()

      Executes the task.

      throws:
        BuildException if an error occurs

    - #### public Path getClasspath()

      Gets the classpath to be used for this compilation.

      Returns:
        the class path

    - #### public String getConfigscript()

      Get the configuration file used to customize the compilation configuration.

      Returns:
        a path to a configuration script

    - #### public File getDestdir()

      Gets the destination directory into which the java source files should be compiled.

      Returns:
        the destination directory

    - #### public String getEncoding()

      Returns the encoding to be used when creating files.

      Returns:
        the file encoding to use

    - #### public String getExecutable()

      The value of the executable attribute, if any.

      Returns:
        the name of the java executable
      Since:
        Groovy 1.8.7

    - #### public boolean getFailonerror()

      Gets the failonerror flag.

      Returns:
        the failonerror flag

    - #### public File[] getFileList()

      Gets the list of files to be compiled.

      Returns:
        the list of files as an array

    - #### public boolean getForceLookupUnnamedFiles()

      Gets the forceLookupUnnamedFiles flag.

      Returns:
        the forceLookupUnnamedFiles flag

    - #### public boolean getIncludeantruntime()

      Gets whether the ant classpath is to be included in the classpath.

      Returns:
        whether the ant classpath is to be included in the classpath

    - #### public boolean getIncludejavaruntime()

      Gets whether the java runtime should be included in this task's classpath.

      Returns:
        the includejavaruntime attribute

    - #### @Deprecated
      public boolean getIndy()

      Get the value of the indy flag (always true).

    - #### public boolean getKeepStubs()

      Gets the keepStubs flag.

      Returns:
        the keepStubs flag

    - #### public boolean getListfiles()

      Get the listfiles flag.

      Returns:
        the listfiles flag

    - #### public String getMemoryInitialSize()

      Gets the memoryInitialSize flag.

      Returns:
        the memoryInitialSize flag

    - #### public String getMemoryMaximumSize()

      Gets the memoryMaximumSize flag.

      Returns:
        the memoryMaximumSize flag

    - #### public boolean getParameters()

      Returns true if parameter metadata generation has been enabled.

    - #### public boolean getPreviewFeatures()

      Returns true if preview features has been enabled.

    - #### public String getScriptBaseClass()

      Get the base script class name for the scripts (must derive from Script)

      Returns:
        Base class name for scripts (must derive from Script)

    - #### public String getScriptExtension()

      Get the extension to use when searching for Groovy source files.

      Returns:
        the extension of Groovy source files

    - #### public Path getSourcepath()

      Gets the sourcepath to be used for this compilation.

      Returns:
        the source path

    - #### public Path getSrcdir()

      Gets the source dirs to find the source java files.

      Returns:
        the source directories as a path

    - #### public File getStubdir()

      Gets the stub directory into which the Java source stub files should be generated

      Returns:
        the stub directory

    - #### public String getTargetBytecode()

      Retrieves the compiler bytecode compatibility level.

      Returns:
        bytecode compatibility level. Can be one of the values in CompilerConfiguration.ALLOWED_JDKS.

    - #### public boolean getTaskSuccess()

      Get the result of the groovyc task (success or failure).

      Returns:
        true if compilation succeeded, or was not necessary, false if the compilation failed.

    - #### public boolean getVerbose()

      Gets the verbose flag.

      Returns:
        the verbose flag

    - #### public boolean isIncludeDestClasses()

      Get the value of the includeDestClasses property.

      Returns:
        the value.

    - #### @Deprecated
      protected CompilationUnit makeCompileUnit()

      deprecated:
        This method is not in use anymore. Use Groovyc.makeCompileUnit instead.

    - #### protected CompilationUnit makeCompileUnit(GroovyClassLoader loader)

    - #### protected Path recreateSrc()

      Recreate src.

      Returns:
        a nested src element.

    - #### protected void resetFileLists()

      Clears the list of files to be compiled and copied.

    - #### protected void scanDir(File srcDir, File destDir, String[] files)

      Scans the directory looking for source files to be compiled. The results are returned in the class variable compileList

      Parameters:
        `srcDir` - The source directory
        `destDir` - The destination directory
        `files` - An array of filenames

    - #### public void setClasspath(Path classpath)

      Set the classpath to be used for this compilation.

      Parameters:
        `classpath` - an Ant Path object containing the compilation classpath.

    - #### public void setClasspathRef(Reference r)

      Adds a reference to a classpath defined elsewhere.

      Parameters:
        `r` - a reference to a classpath

    - #### public void setConfigscript(String configscript)

      Set the configuration file used to customize the compilation configuration.

      Parameters:
        `configscript` - a path to a configuration script

    - #### public void setDestdir(File destDir)

      Set the destination directory into which the Java source files should be compiled.

      Parameters:
        `destDir` - the destination director

    - #### public void setEncoding(String encoding)

      Sets the file encoding for generated files.

      Parameters:
        `encoding` - the file encoding to be used

    - #### public void setErrorProperty(String errorProperty)

      The property to set on compilation failure. This property will be set if the compilation fails.

      Parameters:
        `errorProperty` - the property name to use.

    - #### public void setExecutable(String forkExecPath)

      Sets the name of the java executable to use when invoking the compiler in forked mode, ignored otherwise.

      Parameters:
        `forkExecPath` - the name of the executable
      Since:
        Groovy 1.8.7

    - #### public void setFailonerror(boolean fail)

      Indicates whether the build will continue even if there are compilation errors; defaults to true.

      Parameters:
        `fail` - if true halt the build on failure

    - #### public void setForceLookupUnnamedFiles(boolean forceLookupUnnamedFiles)

      Set the forceLookupUnnamedFiles flag. Defaults to false.

      The Groovyc Ant task is frequently used in the context of a build system that knows the complete list of source files to be compiled. In such a context, it is wasteful for the Groovy compiler to go searching the classpath when looking for source files and hence by default the Groovyc Ant task calls the compiler in a special mode with such searching turned off. If you wish the compiler to search for source files then you need to set this flag to `true`.

      Parameters:
        `forceLookupUnnamedFiles` - should unnamed source files be searched for on the classpath

    - #### public void setFork(boolean f)

      If true forks the Groovy compiler. Default is false.

      Parameters:
        `f` - "true|false|on|off|yes|no"

    - #### public void setIncludeDestClasses(boolean includeDestClasses)

      This property controls whether to include the destination classes directory in the classpath given to the compiler. The default value is "true".

      Parameters:
        `includeDestClasses` - the value to use.

    - #### public void setIncludeantruntime(boolean include)

      If true, includes Ant's own classpath in the classpath. Default is true. If setting to false and using groovyc in conjunction with AntBuilder you might need to explicitly add the Groovy jar(s) to the groovyc classpath using a nested classpath task.

      Parameters:
        `include` - if true, includes Ant's own classpath in the classpath

    - #### public void setIncludejavaruntime(boolean include)

      If true, includes the Java runtime libraries in the classpath. Default is false.

      Parameters:
        `include` - if true, includes the Java runtime libraries in the classpath

    - #### @Deprecated
      public void setIndy(boolean indy)

      Legacy method to set the indy flag (only true is allowed)

      Parameters:
        `indy` - true means invokedynamic support is active

    - #### public void setJavaHome(File home)

      The JDK Home to use when forked. Ignored if "executable" is specified.

      Parameters:
        `home` - the java.home value to use, default is the current JDK's home

    - #### public void setKeepStubs(boolean keepStubs)

      Set the keepStubs flag. Defaults to false. Set to true for debugging. Ignored when forked.

      Parameters:
        `keepStubs` - should stubs be retained

    - #### public void setListfiles(boolean list)

      If true, list the source files being handed off to the compiler. Default is false.

      Parameters:
        `list` - if true list the source files

    - #### public void setMemoryInitialSize(String memoryInitialSize)

      The initial size of the memory for the underlying VM if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)

      Parameters:
        `memoryInitialSize` - string to pass to VM

    - #### public void setMemoryMaximumSize(String memoryMaximumSize)

      The maximum size of the memory for the underlying VM if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. (Examples: 83886080, 81920k, or 80m)

      Parameters:
        `memoryMaximumSize` - string to pass to VM

    - #### public void setParameters(boolean parameters)

      If true, generates metadata for reflection on method parameter names (jdk8+ only). Defaults to false.

      Parameters:
        `parameters` - set to true to generate metadata.

    - #### public void setPreviewFeatures(boolean previewFeatures)

      If true, enable preview Java features (JEP 12) (jdk12+ only).

      Parameters:
        `previewFeatures` - set to true to enable preview features

    - #### public void setProceed(boolean proceed)

      Parameters:
        `proceed` - inverse of failonerror

    - #### public void setScriptBaseClass(String scriptBaseClass)

      Set the base script class name for the scripts (must derive from Script)

      Parameters:
        `scriptBaseClass` - Base class name for scripts (must derive from Script)

    - #### public void setScriptExtension(String scriptExtension)

      Set the extension to use when searching for Groovy source files. Accepts extensions in the form *.groovy, .groovy or groovy

      Parameters:
        `scriptExtension` - the extension of Groovy source files

    - #### public void setSourcepath(Path sourcepath)

      Set the sourcepath to be used for this compilation.

      Parameters:
        `sourcepath` - the source path

    - #### public void setSourcepathRef(Reference r)

      Adds a reference to a source path defined elsewhere.

      Parameters:
        `r` - a reference to a source path

    - #### public void setSrcdir(Path srcDir)

      Set the source directories to find the source Java files.

      Parameters:
        `srcDir` - the source directories as a path

    - #### public void setStacktrace(boolean stacktrace)

      Enable compiler to report stack trace information if a problem occurs during compilation. Default is false.

    - #### public void setStubdir(File stubDir)

      Set the stub directory into which the Java source stub files should be generated. The directory need not exist and will not be deleted automatically - though its contents will be cleared unless 'keepStubs' is true. Ignored when forked.

      Parameters:
        `stubDir` - the stub directory

    - #### public void setTargetBytecode(String version)

      Sets the bytecode compatibility level. The parameter can take one of the values in CompilerConfiguration.ALLOWED_JDKS.

      Parameters:
        `version` - the bytecode compatibility level

    - #### public void setUpdatedProperty(String updatedProperty)

      The property to set on compilation success. This property will not be set if the compilation fails, or if there are no files to compile.

      Parameters:
        `updatedProperty` - the property name to use.

    - #### public void setVerbose(boolean verbose)

      Enable verbose compiling which will display which files are being compiled. Default is false.