ASDF

asdf is a language version manager which supports not only Ruby, but NodeJS, Python, and a host of other languages, thereby reducing the need for all the language version managers you may have already installed.

Installation

For macOS users, we strongly recommend installing ASDF through Homebrew:

brew install asdf

If you are not on macOS or prefer to install without Homebrew follow the installation instructions here.

Either of the instructions will end up asking you to place a configuration in your ~/.zshrc or ~/.bashrc file, which will initialize ASDF’s plumbing when starting your shell. Humbly, we ask that you skip that directive and use the following:

export ASDF_DATA_DIR=${HOME}/.asdf
if command -v brew > /dev/null; then
  if [[ $(uname) == 'Darwin' ]]; then
    [[ $(sysctl -n machdep.cpu.brand_string) =~ ^Apple ]] && \
      [ $(sysctl -n sysctl.proc_translated) -eq 1 ] && \
        export ASDF_DATA_DIR=${HOME}/.asdf-rosetta2
  fi
fi
export PATH=${ASDF_DATA_DIR}/shims:${PATH}

This augmentation will allow users who will be using ASDF for older Rubies on Apple Silicon to choose the proper ASDF installation based on their use case.

Before proceeding, we recommend closing your current shell and opening up a new one, assuming you skipped that in the instructions above.

After that, you can execute

asdf plugin list all

to see the list of plugins you can install. We recommend installing:

While we recommend checking the links above for dependencies or other gotchas, you can normally install plugins with the command

asdf plugin add [plugin name]

Basic Commands

asdf plugin add [name]
  # Install a plugin
asdf install [language/plugin] [version]
  # Install a particular version of a language
asdf plugin update [plugin | --all]
  # Update asdf's plugins. One or many.
asdf reshim [language/plugin]
  # After installing language libraries which have binary components (e.g. 'gem install' or 'npm (or yarn) install'), you may need to regenerate the shim scripts in order to execute them.

Installing Ruby

As a large majority of our projects utilize Ruby on Rails, you will likely need to install the Ruby language at some point. As a base starting point, make sure you install the Ruby plugin from the recommended plugins above.

NOTE: These instructions are current as of macOS Sequoia (15.x) and Xcode 18. Every time Xcode upgrades (about the time a new macOS is released) we have issues with older Rubies being unable to be compiled. Please check with our DevOps team if you are having issues.

Only install as needed. Please upgrade when new minor releases are made.

Ruby >= 2.6

brew install openssl@3
asdf install ruby 3.3.6
asdf install ruby 3.2.6
asdf install ruby 3.1.6

The following Rubies have reached their terminal version

asdf install ruby 3.0.7
asdf install ruby 2.7.8
asdf install ruby 2.6.10

Running Ruby < 2.6 on Apple Silicon

Note that while all Ruby versions that Mission Data projects use can be installed under a normal Apple Silicon ASDF install, you may find that certain gems are too old to be appropriately installed using such installs. The following instructions are not recommended, but included here solely to retain the knowledge.

RUBY_CFLAGS="-Wno-implicit-function-declaration" asdf install ruby 2.4.10

Running Ruby < 2.6 on Rosetta 2

NOTE: If you are on Apple Silicon, check our Homebrew post for instructions on setting up an alternative Intel Homebrew setup, then come back here. Put your shell into Rosetta mode (we're assuming your shell is set up the way we've prescribed above and in the Homebrew post): 
arch -x86_64 /bin/zsh -l
brew install asdf
This will provide an alternative ASDF install, managed by the Intel-Rosetta Homebrew you installed above. You will want to install other necessary Homebrew-provided libraries. PLEASE RESTART YOUR SHELL AT THIS POINT, or simply restart the Rosetta shell by exiting and reentering the shell.

Install versions ONLY AS NECESSARY (the following were tested 2024-04-29):

asdf install ruby 2.5.9
asdf install ruby 2.4.10

These we cannot currently install using any of our normal techniques:

asdf install ruby 2.3.8
asdf install ruby 2.2.10
asdf install ruby 2.1.10
asdf install ruby 2.0.0-p648
asdf install ruby 1.9.3-p551

Note that you may need to manually install Bundler (gem install bundler:1.17.3) for many of these as Bundler does not come included in older Ruby versions.

Restart your shell after the first Ruby installation to pick up the newly created shims.

Things to Remember

  • asdf likes to set its versions in a file called .tool-versions where it lists all the plugins and their versions which have been set for a project. You will find this file in most of our projects.

Updated: