Lua version management is a pretty small niche. The most popular Lua version manager on GitHub has only 91 stars. asdf-lua isn’t a self-contained Lua version manager but rather a plugin for asdf, and extendable version manager with support for over a dozen languages. Unless you are already using asdf chances are you have several version managers already installed. Rather than installing yet another version manager you can use asdf to manage all the languages you rely on in development. But asdf will work fine with your existing version managers too so you don’t need to worry about uninstalling anything to use asdf-lua. While it might seem like asdf-lua is more complex than other version managers it’s really not. asdf-lua itself is only two short Bash scripts and both asdf and asdf-lua are easy to install and configure as we will see.
If you don’t have asdf installed already you will need to install it. It’s easy:
# Clone the repo, currently the latest release is 0.2.1 git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.2.1 # Then add two lines to your bashrc or bash_profile if you are on OSX echo -e '\n. $HOME/.asdf/asdf.sh' >> ~/.bashrc echo -e '\n. $HOME/.asdf/completions/asdf.bash' >> ~/.bashrc
That’s it. After reloading your
.bashrc you should be able to run
asdf in your shell and see the help printed out. Next install asdf-lua:
asdf plugin-add lua https://github.com/Stratus3D/asdf-lua.git
You will also need a C compiler to compile Lua. Refer to the readme for instructions on getting gcc installed on your OS.
Now that we have asdf-lua and it’s dependencies installed using it to install Lua versions is easy.
To see the Lua versions that are available to install run:
asdf list-all lua
This command will print out a list of all the Lua versions. Find one you want to install and run the installation command. I’ve chosen to install lua 5.3.2:
asdf install lua 5.3.2
After Lua is compiled you can run
asdf list lua and you should see the Lua version you just installed. Now that you have a Lua version installed you just need to tell asdf when to use it.
Specifying Lua Versions
asdf looks for a
.tool-version file in the current directory and reads it to figure out which version should be used when
luac is invoked in that directory. If the file doesn’t exist in the current directory asdf navigates up to the parent directory and checks for it again. This is repeated until a
.tool-version file is found on the root directory is reached. Typically you want to set the Lua version on a per-project basis, but you may also want to set a global Lua version so it is available everywhere.
Setting the Lua version for a project
To set a Lua version for a project
cd into the project’s root directory and create the tool version file:
echo "lua 5.3.2" > .tool-version
You should now be able to run
lua -v in the directory to see the Lua version being set. You can also use
asdf current lua to see the Lua version as well as the path to the
.tool-version file that set it. Rather than creating a
.tool-version file manually for every project you can the
asdf local command to create it for you:
asdf local lua 5.3.2
Setting a global Lua version
Since asdf is relying on the presence of a
.tool-version file in the current directory or one of the parent directories all you need to do to set a global Lua version is to create
.tool-version file in your home directory. There is a command that makes this easy:
asdf global lua 5.3.2
This command works just like
asdf local only it creates a
.tool-version file in your home directory. You can see what it’s written by running
less ~/.tool-version. You should now be able to use Lua in any directory under your home directory.
asdf-lua is comparable to other version managers in many ways. The real benefit to asdf-lua is asdf itself. With asdf there is no need to learn the quirks of yet another version manager just to be able to install multiple versions of Lua. The commands I’ve shown here are the exact same for asdf-ruby, asdf-elixir, and all the other asdf plugins.
Feedback is always welcome so if you have any questions about asdf-lua or this blog post feel free to contact me. I’m always looking for ways of improving asdf-lua and asdf so don’t hesitate to contact me if you have any suggestions.