A gradle plugin for convenient use of elm.
If you are looking for documentation for a different version, please select the corresponding branch/tag in GitHub.
This plugin can be used with elm 0.19.
If you want to use elm-platform 0.18, please use version 1.0.0 of this plugin.
The plugin can use a provided elm
installation or download a platform-specific version on the fly.
When you want to use the elmTest
task, you need a working installation of the node-test-runner elm-test
.
Apply the plugin using standard Gradle procedure.
For Groovy:
plugins {
id 'org.mohme.gradle.elm-plugin' version '<current version>'
}
For Kotlin:
plugins {
id("org.mohme.gradle.elm-plugin" ) version "<current version>"
}
If you are confused about what the tasks are doing, try running gradle with --info
. Then the tasks will produce log
output showing the actual call to the underlying functionality.
The plugin supports the elm
extension with the following properties:
Name | default | type | description |
---|---|---|---|
buildDir |
${project.buildDir.path}/elm |
File | The name of the directory in which we place the output. |
debug |
true |
boolean | Determines whether elm make will run with the --debug -flag. |
executable |
Provided | org.mohme.gradle.Executable | The executable to use. |
executionDir |
. |
String | The name of the working directory for the execution of elm make . |
mainModuleName |
Main.elm |
String | The name of the main module to give to elm make . |
optimize |
true |
boolean | Determines whether elm make will run with the the --optimize -flag. |
sourceDir |
src/elm |
File | The name of the directory in which the main module will be searched. |
targetModuleName |
elm.js |
String | The name of the output file to produce. |
testExecutable |
elm-test |
String | The name of the executable to use. |
testExecutionDir |
. |
String | The name of the working directory for the execution of elm-test . |
The property executable
accepts values of type org.mohme.gradle.Executable
for which there are multiple instances:
org.mohme.gradle.Executable.Provided
- specifies that theelm
executable is provided by a local installation and reachable via the system's executable search path under the nameelm
.org.mohme.gradle.Executable.Download.V_0_19_0
- specifies to download and use the elm-compiler in the corresponding version. The downloaded artifact will be store in the./build/gradle-elm
directory for future reuse.org.mohme.gradle.Executable.Download.V_0_19_1
- specifies to download and use the elm-compiler in the corresponding version. The downloaded artifact will be store in the./build/gradle-elm
directory for future reuse.
Of course you can use regular import
statements to avoid littering your build-file with fully qualified class names.
By using dedicated classes/objects, at least Kotlin build script users get the advantage of editor-support for
auto-completion. Also it is impossible to specify an unsupported version for download.
For the download there's a connect timeout of 10s and a read timeout of 30s.
elm {
sourceDir = file('src/main/elm')
executable = org.mohme.gradle.Executable.Provided.INSTANCE
targetModuleName = 'main.js'
debug = true
optimize = false
}
elm {
sourceDir.set(project.file("src/main/elm"))
executable = org.mohme.gradle.Executable.Provided
targetModuleName.set("main.js")
debug.set(true)
optimize.set(false)
}
This plugin adds a elmMake
task to the build.
It does not make any other task depend on elmMake
, thus you might want to add such a dependency yourself.
The task has the same configurable properties as the above mentioned elm
extension (except for the "test*" properties).
When the property on the task is not set, it defaults to the value of the corresponding property of the elm
extension.
This task is just a thin wrapper around the elm
executable and as such "inherits" all assumptions/restrictions
about the directory layout of the project:
- The
elm.json
file is expected in the current working directory, which can be specified asexecutionDir
(see "Extension" above). - Within the
elm.json
, you have to specifysource-directories
in whichelm
will look for modules. - The task property
sourceDir
only impacts the creation of the full path to the mainModule for the underlying "elm make" call.
This plugin adds a elmTest
task to the build.
It does not make any other task depend on elmTest
, thus you might want to add such a dependency yourself.
The tasks only configurable properties are executable
and executionDir
, which correspond to the elm
extension
properties testExecutable
resp. testExecutionDir
.
Effectively, the elmTest
task is nothing more than a simple mechanism to integrate the node-test-runner
into the
build. As such the same restrictions and assumptions apply. The most obvious one is, that the tests have to be placed
in a directory named tests
immediately below the execution directory.
For other restrictions / assumptions please have a look at it's documentation.
If you need more configurability, please let me know.
This plugin is versioned according to the Semantic Versioning rules.
- Versions >=4.0.0 are compatible with elm 0.19 and Gradle >=5.1 (tested with 5.1.1 .. 6.0)
- Version 3.3.0 is compatible with elm 0.19 and Gradle 4.9 .. 5.6.4
- Versions 3.2.0 .. 3.2.2 are compatible with elm 0.19 and Gradle 4.4.1 .. 5.6
- Versions 2.0.3 .. 3.1.2 are compatible with elm 0.19 and Gradle 5.0 .. 5.1.1
- Versions 2.0.0 .. 2.0.2 are compatible with elm 0.19 and Gradle 4.10
- Version 1.0.0 is compatible with elm 0.18 and Gradle 4.6
. . . can be found here
Running elm
might be incredibly slow on some CI-platforms.
This is not a problem of this plugin, but kind of a misunderstanding between elm make
and what the underlying platform
tells the elm compiler about the platform's capabilities.
Be careful with the workarounds that are described in various discussions (e.g. in
this elm-discuss thread). They typically wrap the
original elm
executable in a small script (which is OK) without ensuring that the script returns with elm
's original
return code (which causes trouble).
When you are using this kind of wrapper-script and have trouble with this plugin, have a look at this project's
.travis.yml
.
I'm happy about contributions of all sorts.
Before you actually do work on the project, please read the contribution guide.
This plugin is made available under the Apache 2.0 License.