Library guidelines — Elixir v1.18.3 (original) (raw)

This document outlines general guidelines for those writing and publishing Elixir libraries meant to be consumed by other developers.

Getting started

You can create a new Elixir library by running the mix new command:

$ mix new my_library

The project name is given in the snake_case convention where all letters are lowercase and words are separate with underscores. This is the same convention used by variables, function names and atoms in Elixir. See the Naming Conventions document for more information.

Every project has a mix.exs file, with instructions on how to build, compile, run tests, and so on. Libraries commonly have a lib directory, which includes Elixir source code, and a test directory. A src directory may also exist for Erlang sources.

The mix new command also allows the --sup option to scaffold a new project with a supervision tree out of the box. For more information on running your project, see the official Mix & OTP guide or Mix documentation.

Publishing

Writing code is only the first of many steps to publish a package. We strongly recommend developers to:

• Choose a versioning schema. Elixir requires versions to be in the format MAJOR.MINOR.PATCH but the meaning of those numbers is up to you. Most projects choose Semantic Versioning.
• Choose a license. The most common licenses in the Elixir community are the MIT License and the Apache License 2.0. The latter is also the one used by Elixir itself.
• Run the code formatter. The code formatter formats your code according to a consistent style shared by your library and the whole community, making it easier for other developers to understand your code and contribute.
• Write tests. Elixir ships with a test-framework named ExUnit. The project generated by mix new includes sample tests and doctests.
• Write documentation. The Elixir community is proud of treating documentation as a first-class citizen and making documentation easily accessible. Libraries contribute to the status quo by providing complete API documentation with examples for their modules, types and functions. See the Writing documentation chapter of the Getting Started guide for more information. Projects like ExDoc can be used to generate HTML and EPUB documents from the documentation. ExDoc also supports "extra pages", like this one that you are reading. Such pages augment the documentation with tutorials, guides, references, and even cheat-sheets.
• Follow best practices. The Elixir project documents a series of anti-patterns that you may want to avoid in your code. The process-related anti-patterns and meta-programming anti-patterns are of special attention to library authors.

Projects are often made available to other developers by publishing a Hex package. Hex also supports private packages for organizations. If ExDoc is configured for the Mix project, publishing a package on Hex will also automatically publish the generated documentation to HexDocs.

Dependency handling

When your library is used as a dependency, it runs by default in the :prod environment. Therefore, if your library has dependencies that are only useful in development or testing, you want to specify those dependencies with the :only option. You can also specify :optional dependencies in your library, which are not enforced upon users of your library. In such cases, you should also consider compiling your projects with the mix compile --no-optional-deps --warnings-as-errors in your test environments, to ensure your library compiles without warnings even if optional dependencies are missing. See mix deps for all available options.

Keep in mind your library's lockfile (usually named mix.lock) is ignored by the host project. Running mix deps.get in the host project attempts to get the latest possible versions of your library’s dependencies, as specified by the requirements in the deps section of your mix.exs. These versions might be greater than those stored in your mix.lock (and hence used in your tests / CI).

On the other hand, contributors of your library, need a deterministic build, which implies the presence of mix.lock in your Version Control System (VCS), such as git.

If you want to validate both scenarios, you should check the mix.lock into version control and run two different Continuous Integration (CI) workflows: one that relies on the mix.lock for deterministic builds, and another one, that starts with mix deps.unlock --all and always compiles your library and runs tests against latest versions of dependencies. The latter one might be even run nightly or otherwise recurrently to stay notified about any possible issue in regard to dependencies updates.