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