How to contribute to Elixir

By: Brian Cardarella

I just got my first commit accepted into the Elixir programming language. Here are some notes on how to build and test Elixir on your machine to help you make your own contributions.

Up and running

After you’ve cloned Elixir you’ll need to ensure that the state of your copy builds properly and all the tests pass. To do this you’ll need to use Make. Simply run the following:

$ make compile
$ make test

Hopefully the purpose of each command should be obvious. The entire test suite for the language doesn’t take too long to complete. Once all the tests pass you can start. In the event that any of the two steps fail I would recommend getting help in the #elixir-lang IRC channel on Freenode.

You’ve made your changes

Assuming you’ve made your changes you’ll need to test them. For any changes that you’ve made to the language you’ll need to recompile. You can re-run the commands from above in the root directory of the project.

Elixir itself is made up of several packages. They’re all listed in the lib/ directory:

lib
├── eex
├── elixir
├── ex_unit
├── iex
├── logger
└── mix

Depending upon the package you are making changes to you may not want to run the entire test suite. For example, to compile and run the tests for ex_unit only you can run:

$ make test_ex_unit

Check out the Makefile in Elixir for the available commands for testing individual packages.

Even this can be tedious. If you really want to move fast you can target a specific test file to run. Let’s say you want to target the test file for ExUnit.Case:

$ make compile
$ bin/elixir -r lib/ex_unit/test/test_helper.exs lib/ex_unit/test/ex_unit/case_test.exs

The second command will use the custom build of Elixir that is the result from make compile. The option -r will run the specific file at that path.

This should get you into a faster feed-back loop to ensure that your tests for the changes you’ve made are passing.

Real-world testing

It could be that you are making a commit to scratch an itch in an app you’re building. In that event it would be great to ensure that the changes you’re making in the language actually work for you. We can easily test this by using the custom build of Elxiir with your application.

In a Linux-based shell you can prepend the bin/ path of the custom Elixir build onto $PATH so it takes precedence:

$ export PATH=/home/yourname/elixir/bin:$PATH

Replace /home/yourname/elixir/bin with whatever the path is for your machine. If you really want to live on the edge you can add this to your Bash or Zsh config, but I wouldn’t recommend it.

You should confirm that your custom build is the one found. You can do this by running: which elixir and which mix. If it doesn’t return the path for the custom build you should revisit the steps above and see why not.

You will likely need to recompile the dependencies for the custom build of Elixir:

$ mix do deps.clean, deps.get, deps.install

Assume your application is using the changes you’ve made just run mix test as normal to confirm that your changes work.

Documentation

You may have to document your changes. Please see the Elixir guide on writing good documentation.

Bad builds

Sometimes there may be a bad build during compilation. In this event you can just run:

$ make clean

This will reset the project to a clean state. You can now try to re-compile.

Finish up

I think you’ll be surprised how easy and straight forward it is to contribute back to Elixir. Hopefully these tips have made it a bit smoother for you.