So Eric Meadows-Jönsson has been working on a package manager for Elixir and other BEAM languages, called hex. With Elixir 0.13, hex was officially released, so I wanted to walk through using it as well as explore the API a bit. Let's get started.

Project

We're going to make a new project for playing with this:

mix new hex_play
cd hex_play

Installation

You install hex locally by running the following command:

mix local.install https://hex.pm/installs/hex.ez

With that, hex is available to any project. Next, you have to enable it in your project. Open up mix.exs and add this line to the top:

Code.ensure_loaded?(Hex) and Hex.start

Usage

OK, now let's look at what commands hex gives you. You can list your local package mix tasks by using mix local:

mix.local

Let's learn about the exactor package:

mix hex.info exactor

Alright, so now let's add the exactor library to our project. This consists of a 2-element tuple in the dependencies list. Open up mix.exs:

  defp deps do
    [{:exactor, "~> 0.3.0"}]
  end

Now you can just fetch it like normal:

mix deps.get

Let's explore a bit more about the hex mix tasks. List them out again:

mix local

Now let's find out about search:

mix help hex.search

Let's use it:

mix hex.search actor

So right now it seems to only be searching the names of the packages, but I'd expect this to be expanded to cover the descriptions later.

Anyway, let's move on to using Hex programmatically, because we're going to want to do this from BEAM Toolbox later.

Using the Hex API

Fire up an iex session:

iex -S mix

Now, there are a lot of functions on the Hex.API module. Let's alias it so we don't have to type so much:

alias Hex.API, as: H

Now let's look at the functions provided. First, we can get a package's information:

H.get_package("exactor")

Next, you could get some information on a particular release:

H.get_release("exactor", "0.3.0")

You can also fetch the gzipped copy of the current registry:

{200, data} = H.get_registry
File.write!("/tmp/hexreg.gz", data)

There's no good reason for you to have to do that, but I thought I'd point out that this is just a gzipped ets table. That's pretty neat.

All of the other API calls require authentication, so I won't go into them yet. You can find them in the API module in hex's source if you'd like to dive in further.

Plans for BEAM Toolbox

So BEAM Toolbox will use the API to fetch data on various packages, such as the number of downloads and the license, in order to provide a fuller picture of a given project's metadata. I'm really looking forward to getting this data into the toolbox.

Overview of HexWeb code

I also thought I'd just very briefly point out that the hex_web code is an unbelievably attractive bit of Elixir code, and is an excellent way to structure an API. I've linked to it in the episode resources.

Summary

Alright, so this was just a brief look at Elixir's new package manager, Hex. I'm extremely glad this was finally shipped. See you soon!

Resources