diff --git a/_data/links_en.yml b/_data/links_en.yml index 781e72c..f754469 100644 --- a/_data/links_en.yml +++ b/_data/links_en.yml @@ -81,12 +81,16 @@ - hr: true -- title: Releasing a Mod +- title: Automatic Error Checking num: 18 + link: chapters/luacheck.html + +- title: Releasing a Mod + num: 19 link: chapters/releasing.html - title: Read More - num: 19 + num: 20 link: chapters/readmore.html - hr: true diff --git a/en/chapters/luacheck.md b/en/chapters/luacheck.md new file mode 100644 index 0000000..e398a80 --- /dev/null +++ b/en/chapters/luacheck.md @@ -0,0 +1,129 @@ +--- +title: Automatic Error Checking +layout: default +root: ../../ +--- + +## Introduction + +In this chapter you will learn how to use a tool called LuaCheck to automatically +scan your mod for any mistakes. This tool can be used in combination with your +editor to provide alerts to any mistakes. + +* [Installing LuaCheck](#installing-luacheck) + * [Windows](#windows) + * [Linux](#linux) +* [Running LuaCheck](#running-luacheck) +* [Configuring LuaCheck](#configuring-luacheck) + * [Troubleshooting](#troubleshooting) +* [Checking commits with Travis](#checking-commits-with-travis) + +## Installing LuaCheck + +### Windows + +Simply download luacheck.exe from +[the Github Releases page](https://github.com/mpeterv/luacheck/releases). + +### Linux + +First you'll need to install LuaRocks: + + sudo apt install luarocks + +You can then install LuaCheck globally: + + sudo luarocks install luacheck + +Check that it's installed with the following command: + + luacheck -v + +## Running LuaCheck + +The first time you run LuaCheck, it will probably pick up a lot of false +errors. This is because it still needs to be configured. + +On Windows, the root project folder onto the luacheck.exe executable. + +On Linux, run `luacheck .` whilst in the root folder of your project. + +## Configuring LuaCheck + +Create a file called .luacheck in the root of your project. This could be the +root of your game, modpack, or mod. + +Put the following contents in it: + +{% highlight lua %} +unused_args = false +allow_defined_top = true + +globals = { + "minetest", +} + +read_globals = { + string = {fields = {"split"}}, + table = {fields = {"copy", "getn"}}, + "vector", "default", "ItemStack", +} +{% endhighlight %} + +Next you'll need to test that it works by running LuaCheck. You should get a lot +less errors this time. Starting at the first error you get, either modify the +configuration to take it into account, or if there's a bug then fix it - take +a look at the below list. + +### Troubleshooting + +* **accessing undefined variable foobar** - If foobar is meant to be a global, + then add it to read_globals. Otherwise add any missing `local`s to the mod. +* **setting non-standard global variable foobar** - If foobar is meant to be a global, + then add it to `globals`. Remove from `read_globals` if present there. + Otherwise add any missing `local`s to the mod. +* **mutating read-only global variable 'foobar'** - Move foobar from `read_globals` to + `globals`. + +## Checking commits with Travis + +If your project is public and is on Github, you can use TravisCI - a free service +to run jobs on commits to check them. This means that every commit you push will +be checked against LuaCheck, and a green tick or red cross displayed next to them +depending on whether LuaCheck finds any mistakes. This is especially helpful for +when you project receives a pull-request - you'll be able to see the LuaCheck output +without downloading the code. + +First you should visit [travis-ci.org](https://travis-ci.org/) and sign in with +your Github account. Then find your project's repo in your Travis profile, +and enable travis by flipping the switch. + +Next, create a file called .travis.yml with the following content: + +{% highlight yml %} +language: generic +sudo: false +addons: + apt: + packages: + - luarocks +before_install: + - luarocks install --local luacheck +script: +- $HOME/.luarocks/bin/luacheck --no-color . +notifications: + email: false +{% endhighlight %} + +If your project is a game rather than a mod or mod pack, +change the line after `script:` to: + +{% highlight yml %} +- $HOME/.luarocks/bin/luacheck --no-color mods/ +{% endhighlight %} + +Now commit and push to Github. Go to your project's page on Github, and click +commits. You should see an orange disc next to the commit you just made. After +a while it should change either into a green tick or a red cross depending on the +outcome of LuaCheck. In either case, you can click the icon to see the build logs +and the output of LuaCheck.