Awesome
gradle-butler-plugin
A gradle plugin for automatically installing, updating and running the itch.io butler command line tool as part of your build.
How to use
Add the following buildscript configuration to the top of your build.gradle
buildscript {
repositories {
mavenLocal()
jcenter()
mavenCentral()
}
dependencies {
classpath group: 'org.mini2Dx', name: 'butler', version: '2.1.0'
}
}
Then add the plugin configuration to your project.
project(":projectName") {
apply plugin: "org.mini2Dx.butler"
........
butler {
user = "your-itchio-user"
game = "your-itchio-game"
}
}
Then configure tasks with the channels you want to push:
project(":projectName") {
........
task butlerPush(type: org.mini2Dx.butler.task.PushTask) {
binDirectory = "/path/to/game/bin/directory"
channel = "example"
}
}
The plugin will add the following tasks to your project.
Task | Description |
---|---|
butlerUpdate | Updates butler to latest stable version or installs it if it is not present. All other tasks depend on this task so you do not need to call it explicitly. |
butlerLogin | Calls butler login |
butlerLogout | Calls butler logout |
As well as providing a task template with org.mini2Dx.butler.task.PushTask
which can be used to create tasks which push builds using butler.
You can configure multiple push tasks, only the binDirectory and channel have to be provided for each.
Push Task Property | Description |
---|---|
binDirectory | (required) The directory containing your game's build, which will be pushed by butler |
channel | (required) The channel to release your build to |
Advanced Configuration
There are several optional configuration parameters available.
Option | Type | Default | Description |
---|---|---|---|
user | String | blank | (required) Your itch.io username |
game | String | blank | (required) The itch.io game id |
updateButler | boolean | true | Set to false to disable butler updates |
userVersion | String | null | Set this if you want to override itch.io's version number |
allChannelsPostfix | String | null | Set this to append the given string to every channel name |
butlerInstallDirectory | String | null | Set if you want to override the automatic Butler install directory |
The following example shows all options in use.
project(":projectName") {
apply plugin: "org.mini2Dx.butler"
........
butler {
user = "your-itchio-user"
game = "your-itchio-game"
updateButler = true
allChannelsPostfix = "-beta"
userVersion = project.version
butlerInstallDirectory = "C:\\path\to\butler\directory"
}
}
Depending on your project build task
You will most likely want your pushTask
to depend on the gradle task that builds your game binaries. This will ensure the project is automatically build when calling the task.
This example uses the build
task, but it might be different for your project configuration.
task butlerPush(type: org.mini2Dx.butler.task.PushTask) {
dependsOn build
binDirectory = "C:\\path\to\game\bin\directory"
channel = "windows"
}
Using the butler plugin in a separate gradle script
If your project uses multiple gradle script files (e.g. LibGDX) then you will be required to add the following block of code in multiple places:
buildscript {
repositories {
mavenLocal()
jcenter()
mavenCentral()
}
dependencies {
classpath group: 'org.mini2Dx', name: 'butler', version: '2.1.0'
}
}
First it should be added to the highest level build.gradle file as described above. But it must also be added at the beginning of any other gradle scripts in which you want to declare org.mini2Dx.butler.task.PushTask
's in order for gradle to recognize the class name.
Upgrading from version 1.1.3 or earlier
If you've used the plugin before and are upgrading from 1.1.3 or an earlier version, these steps will help you port your gradle code:
1. convert any pre-defined channels (windows/osx/linux/anyOs) you used into tasks
- the binDirectory stays the same
- the channel name now always needs to be specified explicitly
- butlerInstallDirectory is now a property of the "butler" config directly
As an example:
butler {
...
windows {
butlerInstallDirectory = "C:\\path\to\butler\directory"
binDirectory = "C:\\path\to\game\bin\directory"
}
}
This would need to be changed to the following (note butlerPushWindows
is an arbitrary name, you can call your task however you like):
butler {
...
butlerInstallDirectory = "C:\\path\to\butler\directory"
}
task butlerPushWindows(type: org.mini2Dx.butler.task.PushTask) {
binDirectory = "C:\\path\to\game\bin\directory"
channel = "windows"
}
2. If you want to have just a single task to push multiple channels, you can have a task that depends on the other tasks.
E.g.
task butlerPush() {
dependsOn butlerPushWindows, butlerPushOsx, butlerPushLinux, butlerPushAnyOs
}
Given those tasks exist, the gradle task "butlerPush" will execute them all.
3. If you've previously made use of the "alphaChannel" or "betaChannel" property, you can now set the "allChannelsPostfix" property to "-alpha" or "-beta" to achieve the same effect.
butler {
...
allChannelsPostfix = "-alpha"
}
4. If you need to configure a different butlerInstallDirectory
on different machines, you can use a separate script file that you can keep outside of version control.
E.g. like so:
localproperties.gradle
ext {
BUTLER_INSTALL_DIR = '/path/to/butler'
}
build.gradle
apply from: 'localproperties.gradle'
...
butler {
...
butlerInstallDir = BUTLER_INSTALL_DIR
}
License
The code is released under the MIT License.
Contributing
Pull requests are welcome :) Any issues found please add them to the Issue Tracker.
Gradle wrapper is included in the code. The following tools were used for development:
- Gradle 5.6.4