Mix will generate the following directory structure:
You can create a new folder in lib/ with the name of your package (simple_statistics) to place other modules. It’s a good idea to split code to different modules for modularity. We’ll create a new lib/simple_statistics/mean.ex module.
Use @moduledoc and @doc to specify module and function docstrings. You should ideally document every major public function in your modules.
You can add doctests in your docstrings like so:
Let’s add these doctests to our main test suite.
We can now run our tests with mix test.
Add Type Annotations
We can use Typespecs to utilize static type checking for our functions.
Typespecs helps ensure that there’s no discrepancy between differing types of our program’s constants, variables, and functions.
You can then perform static analysis by using dialyzer. First, update your mix.exs to add dialyxir as a dependency:
Then, run dialyzer - Erlang’s static analysis tool:
Update your mix.exs to add the following dependencies:
Run mix deps.get and mix deps.compile to retrieve and install those dependencies. Finally, we can generate our documentation using mix docs:
Here is the live documentation, hosted on Github Pages. Our documentation also displays docstring examples as well as any type annotations. Cool!
Publishing your Library
We’re now ready to start publishing our library.
Register with Hex
First, set up an account on Hex, Erlang and Elixir’s package manager if you haven’t already.
Click on the email confirmation link to activate your Hex.pm acccount.
Set your project’s metadata
Update your mix.exs with description and package:
After the package metadata and dependencies have been added to mix.exs, we are ready to publish the package with the mix hex.publish command:
Note that our library will be published as the version specified in mix.exs.
A published version can be amended or reverted with --revert up to one hour after its publication. If you want to revert a publication that is more than one hour old you need to contact an administrator.
You can publish your documentation to Hex Docs. The documentation will be generated by running the mix docs task.
This documentation will be accessible at https://hexdocs.pm/my_package/1.0.0. In addition, https://hexdocs.pm/my_package will always redirect to the latest published version. Instead of Hex.pm, you can alternatively host the documentation at docs/ yourself or on Github Pages.
Note that mix hex.publish will by default build and publish your library’s documentation as well.
You can publish a new version by updating the version value in mix.exs and running mix hex.publish.
Also, remember to use Git tags to annotate version changes!
We’ve succesfully written and published an Elixir library! Writing and publishing libraries in Elixir is easy and straightforward. Other developers can now add your library into their deps and start using it in their projects.
Thanks for reading! Let me know if you have any feedback in the comments below.
Interested in Serverless? Here's a book written just for you!
Going Serverless teaches you how to build scalable applications with the Serverless framework and AWS Lambda. You'll learn how to design, develop, test, deploy, and secure Serverless applications from planning to production.