Contributing to exa

Want to help out with exa’s development, or just have a bug or feature you’d like to improve? That’s great! exa is open-source, and every release has had people submit code, bug fixes, and ideas.

Development takes place over at GitHub:

Vagrant, and the Extended Test Suite

exa is a system tool, and as such, it has to deal with a large number of edge cases:

  • What if a file is owned by a user that no longer exists?
  • What if a symlink just points to itself?
  • What if a file has extended attributes, but the current user isn’t allowed to view them?

These are all edge cases that exa has to handle reasonably without crashing, and it’s actually had bugs in the past for all three of these cases.

One way to solve this is to have a comprehensive test suite. But programs such as exa that are basically just interfaces to the system are notoriously difficult to test: it’s impossible to do a complete end-to-end test without mandating the current user’s name, the locale, the time zone, and having all sorts of “awkward” files with unusual names or permissions. This is how exa was tested for a long time, but it’s unreasonable to expect every developer to set up their system like this — or we’d end up with a test suite that nobody can run!

Vagrant provides a solution to this problem. By running exa inside a virtual machine, we can fake everything with no impact on your actual system: you’re free to change the time zone and introduce all sorts of awkward test cases without worrying that it’s going to impact your personal files. Although it takes a while to set up, it gives every developer the same environment to write code and test for any regressions.

Setting up the Development Environment

First, you’ll need to install Vagrant. The way to do this will vary depending on your OS.

Next, you’ll need to launch a Vagrantfile, which contains the name of the OS to download and instructions for configuring it. exa has one of these in its root directory, so after you’ve downloaded exa’s source code, navigate to the directory and run:

vagrant up

This command downloads an Ubuntu virtual machine image and boots it. It then runs a provisioning script that downloads Rust and exa’s dependencies, configures the environment, and generates the awkward files and folders to use as test subjects. This process will take some time, but it does write to output occasionally.

Once this is complete, you can SSH in:

vagrant ssh
The exa development environment!
exa's source is available at /vagrant.
Binaries get built into /home/ubuntu/target.

exa to run the built version of exa
build-exa (or b) to run cargo build
test-exa (or t) to run cargo test
run-xtests (or x) to run the extended tests
compile-exa (or c) to run the above three
debug to toggle printing logs
strict to toggle strict mode
colors to toggle custom colours
halp to show all this again

rustc 1.20.0 (f3d6973f4 2017-08-27)
cargo 0.21.0 (5b4b8b2ae 2017-08-12)
exa ~ $

Now you can build:

exa ~ $ c
   Compiling exa v0.11.0-pre (file:///vagrant)
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
   Compiling exa v0.11.0-pre (file:///vagrant)
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
    Running target/debug/deps/exa-2caa321fd65076e2

running 54 tests
test result: ok. 54 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

All the tests passed!

exa ~ $ exa
git2-rs  target

When inside the VM, you’ll have the following things available:

  • The program exa refers to your local debug version of exa, and rexa to the local release version of exa.
  • The shells bash, zsh, and fish are available, and shell completions for all three have been symlinked into place.
  • Likewise, the man page has been symlinked into place and is viewable with man exa.

What kinds of contributions are accepted?

Anything! Bug fixes, new features, new test cases, improvements to the Vagrant environment, even typo fixes.

What licence is exa under?

It uses the MIT licence.

Can I develop without using Vagrant?

Sure — the test suite gets run on each pull request and release anyway, so don’t worry about accidentally introducing any bugs by not using Vagrant. exa can still be built and compiled on any target triple that it supports, VM or no VM, with cargo build and cargo test.

There’s more information on the building from source page.

What about bugs that don’t occur on Ubuntu?

Of course, the drawback of having a standard development environment is that you stop noticing bugs that occur outside of it. For this reason, exa still gets tested outside of VMs on other platforms — the Vagrant environment is only used for testing during development, rather than for all testing.