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:
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. Commands 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 Versions 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
exarefers to your local debug version of exa, andrexato the local release version of exa. - The shells
bash,zsh, andfishare 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.