howl.ci

Getting started

Before we do anything else you'll need to create a repository for your code on GitHub if you haven't got one already.

Enabling your build on Travis

howl.ci uses Travis.org to execute your code. So first we need to setup Travis. You can find more detailed instructions and further documentation on the Travis website.

• Sign in to Travis with your GitHub account
• Go to your profile page and find the repository you want to build.
• Enable building for that repository. You should just be able to flip the green switch.

That's it: you've setup Travis to build your code! However Travis doesn't know anything about ComputerCraft, so we need to configure that next.

Adding the howl.ci runner

Travis uses a .travis.yml file to change how your build works. To execute within ComputerCraft's environment we need to download an emulator and execute your code in there. This is known as the howl.ci runner. Let's take a look:

jdk:
  - oraclejdk8
install:
  - wget -O howlci.jar https://dl.bintray.com/squiddev/maven/org/squiddev/howl.ci//howl.ci-.jar
script:
  - java -jar howlci.jar

Making your builds do something

The issue here is that the howl.ci runner, and so Travis has no way of telling if your build has succeeded or not. To do this you should use the howlci API. This is like any other ComputerCraft API (like os or fs), it is just a normal Lua table with some functions inside. The howlci API provides a howlapi.status(status:string, message:string) that sets the status of your build.

Builds have three states: "success" for when everything went OK, "failure" for when your tests didn't go right and "error" for when something unexpected that you were not expecting: such as everything crashing. If you don't terminate with a status then the howl.ci runner will presume the build errored.

local success, err = pcall(myTest)
if success then
	howlci.status("success", "Everything passed!")
else
	howlci.status("failure", "Something failed: " .. tostring(err))
end

howlci.close()

Running your build

You should now be able to commit and push your code. The howl.ci runner will look for a startup file and execute it. Make sure you have one before you push!

You can visit your repository's builds by using the textbox in the page header. Click on the latest build, it should be a pleasant green colour. If not: go back and check you've got everything right.

You should now see a log and a ComputerCraft terminal displaying the results of your build. You can use the playback bar to go through your build and see what the was output when.

Moving on

Of course the capabilities of howl.ci don't stop there. If you wish you can add tweak the runner to execute in different versions of ComputerCraft, with or without CCTweaks or using different monitor resolutions. This can be done through the .howl.ci.properties file which is discussed in detail on another page.