I am setting up my new laptop (a MacBook Pro wind macOS High Sierra 10.13.4) and one of the tools I need for my day-to-day work is a Ruby installed. macOS High Sierra comes with ruby version 2.3.3. But, as I am writing this post, the latest ruby version is 2.5.1 which was released on March 28, 2018.

I could use homebrew to install the latest version of ruby with one single command. The problem is, sometimes I work with projects using old Ruby versions and sometimes I like to give a try to beta/alpha versions in order to be aware of what is coming. That said, I need a way to install two or more different versions of Ruby and the same happens with other tools or languages.

On my previous setup (macOS and Ubuntu) I was using RVM and then I pass to rbenv. Both allows you as a developer to install and switch multiple Ruby development environments. As with rbenv or RVM for Ruby, you have NVM for Node.js, virtualenv for Python, etc.

But today, for the new machine, I decided to switch to ASDF. ASDF is an extendable version manager that allows developers to install multiple Ruby versions. Moreover, with ASDF you can install and manage almost all languages you might want, even databases like Postgres, MongoDB or Redis. You can install and manage different versions of Ruby, Node.js, Elixir, dotnet-core, Python, and so on. The complete list of supported languages can be found here: https://github.com/asdf-vm/asdf-plugins.

On this post, I will show you how to install asdf and use it to install different versions of Ruby, Elixir and other tools I’ve been using.

First, we need to install the base development tools using homebrew (a macOS package manager like apt-get for Ubuntu):

$ brew install coreutils openssl libyaml libffi automake autoconf readline libxslt wxmac gpg

In fact, you don’t need to install all packages above. For example, I am installing “wxmac” because I will need it as a dependency for Erlang, which on the other hand, is also a dependency for Elixir since Elixir runs on top of Erlang’s virtual machine.

Now we can install ASDF itself. Remember, you need to have git installed. macOS 10.13.x already comes with git 2.14 installed. If you want to install the latest version, you can use brew (homebrew) for that:

$ brew install git

The command above will install the latest version of git and set it as the default one. Run on terminal “git –version” to confirm. If still getting the old version, restart your session (Terminal).

$ git clone https://github.com/asdf-vm/asdf.git ~/.asdf –branch v0.4.3

When you specify the branch, you are specifying the version to install. In this case, we are installing the latest version (0.4.3). You can check others and new versions here: https://github.com/asdf-vm/asdf/releases .

Now we need to add environment configuration for PATH and auto-completion. Depending on your OS and SHELL, the file to edit can differ. In my case, I am using macOS and oh-my-zsh framework, so I need to edit “~/.zshrc” file. On Terminal (ITerm2, my case), you can run:

$ echo -e ‘\n. $HOME/.asdf/asdf.sh’ >> ~/.zshrc
$ echo -e ‘\n. $HOME/.asdf/completions/asdf.bash’ >> ~/.zshrc

And that’s all! We are ready to start using asdf.

Installing Ruby using asdf

Now that we have asdf installed and ready for use, we can start installing our tools. The first one I choose is Ruby. To install Ruby I need a plugin for it. Plugins are how asdf understands how to handle different packages. We can find a list of all supported plugins here: https://github.com/asdf-vm/asdf-plugins and we can create our own plugins using these guidelines: https://github.com/asdf-vm/asdf/blob/master/docs/creating-plugins.md

Let’s check the installed plugins running the following command:

$ asdf plugin-list

This command should give us a list of installed plugins. But at this point, it will return a warning saying “Oohe nooes ~! No plugins installed“. The message is clear, we did not install any plugin yet. So, let’s install our first plugin. The Ruby plugin:

$ asdf plugin-add ruby

Now it’s time to install one or more Ruby versions. But first, let’s see what versions are available:

$ asdf list-all ruby

As you can see, a list of all available versions was returned, even the latest preview (2.6.0-preview1). I want to install the version 2.5.1, the latest stable one, so I run:

$ asdf install ruby 2.5.1

It will download and compile the version 2.5.1 of Ruby. It can take some time. When finished, I can start using my new Ruby. We can check if ruby was installed successfully by checking the version. If it still giving you the old (system) version, try to restart your session (Terminal):

$ ruby -v

Should return something like:

=> ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]

At this point I am ready to start using Ruby, installing gems with commands like: “gem install rails” and so on.

We need to set a specific version as the global (default) version running the following command (it will create or change a file ~/.tool-versions):

$ asdf global ruby 2.5.1

And if I want to use a different version for a specific project, I need to go to that project root folder and run (it will create or update a file PROJECT_FOLDER/.tool-versions):

$ asdf local ruby 2.5.1

The format of the content of .tool-versions file is always: [PLUGIN NAME] [VERSION]. For example, for Ruby, it will be: “ruby 2.5.1”.

Installing Other tools/languages

Adding plugins

Now it’s time to install other languages. As we did previously, we need first to add the corresponding plugin. To not be repetitive, we will add all plugins we need now. In my case, I need plugins for Ruby (already added), dotnet-core, java, kotlin, erlang, elixir, nodejs and python. Your needs can be different from mine.

$ asdf plugin-add dotnet-core
$ asdf plugin-add java
$ asdf plugin-add erlang
$ asdf plugin-add elixir
$ asdf plugin-add kotlin
$ asdf plugin-add nodejs
$ asdf plugin-add php
$ asdf plugin-add python

Note that nodejs on macOS require “coreutils” and “gpg“. And we needed to import the Node.js release team’s OpenPGP keys to the main keyring, running following command:

$ bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring

Installing a tool version.

To install a version of a tool like Elixir, we need first to confirm the available versions. Note that for all languages the process is the same, all we need to do is change the plugin name. Some lists can be long and can take time to show up.

$ asdf list-all elixir

The same we can do with other languages as I said. All we have to do is change the plugin name.

Now I will install all versions of different tools I need:

$ asdf install java 10
$ asdf install nodejs 9.10.1
$ asdf install erlang 20.3.2
$ asdf install elixir 1.6.4
$ asdf install python 3.6.5
$ asdf install dotnet-core 2.1.103
$ asdf install kotlin 1.2.31

After install each language, you need to set a global version. To do it, run (for Elixir for example):

$ asdf global elixir 1.6.4

macOS comes with python 2.7.10 even after set the global version it stil using the old (system) version. The same can happen with other languages/tools. To fix you need to restyart your session (close and open your Terminal).

Kotlin (asdf-kotlin) requires Java 6+ to be installed. And as Elixir depends on Erlang, Erlang needs to be installed first.

Managing plugins and versions

We saw how to add plugins and install versions. There are others commands we can use on asdf to perform some tasks.

To list all installed plugins we run:

$ asdf plugin-list

And to remove a plugin we run:

$ asdf plugin-remove <PLUGIN-NAME>

Example:

$ asdf plugin-remove nodejs

We can update the plugins one by one or all of them at the same time. To update all installed plugins we pass a “–all” flag; and to update a single plugin we pass the name of the plugin.

$ asdf plugin-update –all
$ asdf plugin-update elixir

If we want to see the current versions of all installed plugins, we run:

$ asdf current

and we can restrict to one plugin. Let’s say, we want to see the current version for Ruby:

$ asdf current ruby

We can unistall a version using the following command:

$ asdf uninstall <NAME> <VERSION>

Note that we need to specify the name of plugin and the version we want to uninstall. Example:

$ asdf uninstall ruby 2.4.1

We can set the current version locally or globally as we saw when we installed Ruby above:

$ asdf global <NAME> <VERSION>
$ asdf local <NAME> <VERSION>

Example:

$ asdf global elixir 1.6.4

That’s it! We did it.

Note that this is my first post written in English (more coming). So it’s easy to make mistakes. If you find an error, something I said wrong, please let me know and sorry for that.

Now join me for the PIZZA \o/