Using Ant

Getting the Ant Tasks

Kotlin provides three tasks for Ant:

  • kotlinc: Kotlin compiler targeting the JVM;
  • kotlin2js: Kotlin compiler targeting JavaScript;
  • withKotlin: Task to compile Kotlin files when using the standard javac Ant task.

These tasks are defined in the kotlin-ant.jar library which is located in the lib folder for the Kotlin Compiler Ant version 1.8.2+ is required.

Targeting JVM with Kotlin-only source

When the project consists of exclusively Kotlin source code, the easiest way to compile the project is to use the kotlinc task:

  1. <project name="Ant Task Test" default="build">
  2. <typedef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <kotlinc src="hello.kt" output="hello.jar"/>
  5. </target>
  6. </project>

where ${kotlin.lib} points to the folder where the Kotlin standalone compiler was unzipped.

Targeting JVM with Kotlin-only source and multiple roots

If a project consists of multiple source roots, use src as elements to define paths:

  1. <project name="Ant Task Test" default="build">
  2. <typedef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <kotlinc output="hello.jar">
  5. <src path="root1"/>
  6. <src path="root2"/>
  7. </kotlinc>
  8. </target>
  9. </project>

Targeting JVM with Kotlin and Java source

If a project consists of both Kotlin and Java source code, while it is possible to use kotlinc, to avoid repetition of task parameters, it is recommended to use withKotlin task:

  1. <project name="Ant Task Test" default="build">
  2. <typedef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <delete dir="classes" failonerror="false"/>
  5. <mkdir dir="classes"/>
  6. <javac destdir="classes" includeAntRuntime="false" srcdir="src">
  7. <withKotlin/>
  8. </javac>
  9. <jar destfile="hello.jar">
  10. <fileset dir="classes"/>
  11. </jar>
  12. </target>
  13. </project>

You can also specify the name of the module being compiled as the moduleName attribute:

  1. <withKotlin moduleName="myModule"/>

Targeting JavaScript with single source folder

  1. <project name="Ant Task Test" default="build">
  2. <typedef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <kotlin2js src="root1" output="out.js"/>
  5. </target>
  6. </project>

Targeting JavaScript with Prefix, PostFix and sourcemap options

  1. <project name="Ant Task Test" default="build">
  2. <taskdef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <kotlin2js src="root1" output="out.js" outputPrefix="prefix" outputPostfix="postfix" sourcemap="true"/>
  5. </target>
  6. </project>

Targeting JavaScript with single source folder and metaInfo option

The metaInfo option is useful, if you want to distribute the result of translation as a Kotlin/JavaScript library. If metaInfo was set to true, then during compilation additional JS file with binary metadata will be created. This file should be distributed together with the result of translation:

  1. <project name="Ant Task Test" default="build">
  2. <typedef resource="org/jetbrains/kotlin/ant/antlib.xml" classpath="${kotlin.lib}/kotlin-ant.jar"/>
  3. <target name="build">
  4. <!-- out.meta.js will be created, which contains binary metadata -->
  5. <kotlin2js src="root1" output="out.js" metaInfo="true"/>
  6. </target>
  7. </project>

References

Complete list of elements and attributes are listed below:

Attributes common for kotlinc and kotlin2js

NameDescriptionRequiredDefault Value
srcKotlin source file or directory to compileYes 
nowarnSuppresses all compilation warningsNofalse
noStdlibDoes not include the Kotlin standard library into the classpathNofalse
failOnErrorFails the build if errors are detected during the compilationNotrue

kotlinc Attributes

NameDescriptionRequiredDefault Value
outputDestination directory or .jar file nameYes 
classpathCompilation class pathNo 
classpathrefCompilation class path referenceNo 
includeRuntimeIf output is a .jar file, whether Kotlin runtime library is included in the jarNotrue
moduleNameName of the module being compiledNoThe name of the target (if specified) or the project

kotlin2js Attributes

NameDescriptionRequired
outputDestination fileYes
librariesPaths to Kotlin librariesNo
outputPrefixPrefix to use for generated JavaScript filesNo
outputSuffixSuffix to use for generated JavaScript filesNo
sourcemapWhether sourcemap file should be generatedNo
metaInfoWhether metadata file with binary descriptors should be generatedNo
mainShould compiler generated code call the main functionNo

Passing raw compiler arguments

To pass custom raw compiler arguments, you can use <compilerarg> elements with either value or line attributes. This can be done within the <kotlinc>, <kotlin2js>, and <withKotlin> task elements, as follows:

  1. <kotlinc src="${test.data}/hello.kt" output="${temp}/hello.jar">
  2. <compilerarg value="-Xno-inline"/>
  3. <compilerarg line="-Xno-call-assertions -Xno-param-assertions"/>
  4. <compilerarg value="-Xno-optimize"/>
  5. </kotlinc>

The full list of arguments that can be used is shown when you run kotlinc -help.