In BlogPost, Elixir

Elixir Hex Package Tutorial

When I first started learning Elixir a few months ago, I had an itch to make my own hex package of some kind. So I started making yt_potion.

elixir logo from github

Making my own open source library like rsocialize was also a great help to me when I was first learning Ruby on Rails.

Since Elixir was so new, there wasn’t too much in the way of blog posts to help you get started. Thus, I decided to document what I did for future reference and to help others.

Preliminary Steps

If you’re coming from Ruby (or some other language) where you’re used to having an environment manager to manage different versions of Ruby and its associated libraries, check out my post Setting Up Elixir Like a Rubyist.

This will help you install Elixir if you haven’t done so yet. Mix is the build tool that ships with Elixir that has automated tasks for managing dependencies and other useful tricks when working with your Elixir application.

Step 1 – Initialize Your Package With Mix

First, you will use mix to initialize your new package. I’ll be walking you through what I did with yt_potion.

Initialize your package with the following command:

You should see output similar to the following:

Step 2 – Git init

Next, you’ll want to version control your work with Git.

Step 3 – Pick a license

GitHub has a nice way to help you choose a software license. I personally chose the MIT license as that gives permission to people to “do whatever they want” with the software and is easy to understand. You can read more about the license tool here on GitHub’s blog and if you’re ready to choose a license, you can use the tool here.

Step 4 – Register at hex.pm

Before you can start publishing your hex package, you should go over to hex.pm and register an account.

You’ll need the password you create during the registration process later to publish your package.

You’ll get a profile that looks something like the following:

a screenshot of my hex package profile

Step 5 – Add meta information to your mix.exs file

If you try to issue a mix hex.build command without properly configuring mix.exs first, you’ll end up seeing something like the below:

You’ll want to configure description, package, and dependency (or deps) information in your project function in the mix.exs file. Here’s an example mix.exs file from a hex package I published called nested_filter

You’ll notice I have package, description, and deps information setup via private functions that are passed as values to the keys in the array in the project function.

Step 6 – Build your package (and include a README)

To build your package, issue mix hex.build at the command prompt. You’ll see something like the below.

Again, don’t forget to include a README file otherwise you may get a complaint like the below when you build.

Here is what a successful build might look like:

Don’t forget to add ex-doc

If you see a message like the below, you’ll need to add :ex_doc in the deps function.

Step 7 Publish on hex.pm

Finally, you’re ready to publish.

Type mix hex.publish at the command prompt.

You should see something like the following:

If need to enter a passphrase, use the password you used when you registered with hex.pm

Summary

Publishing a hex package is relatively painless. Just follow the above 7 steps and you’ll be on your way.

Recent Posts