Writing and Publishing Elixir Libraries

In this talk, we’ll walk through the process of writing and publishing an Elixir library from scratch. Along the way, we’ll discover a handful of Elixir features such as: Mix, Documentation, Doctests, Typespecs, and Hex.

Transcript

1. A practical guide to
   Writing & Publishing Elixir Libraries
   Yos Riady
   yos.io
   goo.gl/PVekCF
   

   View Slide

2. View Slide

3. At this moment, there are more than 7100 gems
   hosted on Rubygems.org.
   Hex.pm has 1455 packages.
   

   View Slide

4. View Slide

5. Introduction to Elixir
   Elixir’s build tool
   Background Mix Docs Types Conclusion
   Docstrings and
   Doctests
   Summary and further
   learning
   Introduction to
   Typespecs
   

   View Slide

6. What is Elixir?
   ● Language that compiles to Erlang
   ● Built on top of the famed Erlang VM (“nine 9s of reliability”)
   ○ Traditionally used for telecommunications by Ericsson
   ○ WhatsApp, Facebook Messenger, Riot Games, RabbitMQ, Riak
   

   View Slide

7. Features of Elixir
   ● A pleasant, modern syntax similar to Ruby
   ● Immutable
   ● Pattern Matching
   ● Gradual types with Typespecs
   ● First-class documentation
   ● Metaprogramming through Macros
   ● Concurrency abstractions (Actor model and OTP)
   ● Interop with Erlang
   

   View Slide

8. Introduction to Elixir
   Elixir’s build tool
   Background Mix Docs Types Conclusion
   Docstrings and
   Doctests
   Summary and further
   learning
   Introduction to
   Typespecs
   

   View Slide

9. Mix is Elixir’s build tool
   

   View Slide

10. Use Mix to generate an Elixir project
    > mix new simple_statistics
    > cd simple_statistics
    

    View Slide

11. Elixir project structure
    |-- _build
    |-- config/
    |-- config.exs
    |-- lib/
    |-- simple_statistics.ex
    |-- test/
    |-- simple_statistics_test.exs
    |-- test_helper.exs
    |-- mix.exs
    |-- mix.lock
    |-- README.md
    |-- .gitignore
    

    View Slide

12. defmodule SimpleStatistics.Mixfile do
    use Mix.Project
    def project do
    [app: :simple_statistics,
    deps: deps]
    end
    defp deps do
    [{:ex_doc, "~> 0.11", only: :dev},
    {:dialyxir, "~> 0.3", only: [:dev]}]
    end
    end
    Mix.exs defines our project metadata
    

    View Slide

13. Write code in lib/
    # lib/simple_statistics/mean.ex
    defmodule SimpleStatistics.Mean do
    def mean(list) do
    Enum.sum(list) / Kernel.length(list)
    end
    end
    

    View Slide

14. Introduction to Elixir
    Elixir’s build tool
    Background Mix Docs Types Conclusion
    Docstrings and
    Doctests
    Summary and further
    learning
    Introduction to
    Typespecs
    

    View Slide

15. First-class documentation
    

    View Slide

16. Document with Docstrings
    # lib/simple_statistics/mean.ex
    defmodule SimpleStatistics.Mean do
    @doc ~S"""
    The mean is the sum of all values over the number of values.
    """
    def mean([]), do: nil
    ...
    end
    

    View Slide

17. # test/simple_statistics_test.ex
    defmodule SimpleStatisticsTest do
    use ExUnit.Case
    test "the truth" do
    assert 1 + 1 == 2
    end
    end
    Write unit tests in test/ with ExUnit
    

    View Slide

18. Show examples with Doctests
    @doc ~S"""
    The mean is the sum of all values over the number of values.
    ## Examples
    iex> SimpleStatistics.Mean.mean([])
    nil
    iex> SimpleStatistics.Mean.mean([1,2,3,4,5])
    3.0
    iex> SimpleStatistics.Mean.mean([1.5,-2.1,3,4.5,5])
    2.38
    """
    

    View Slide

19. # test/simple_statistics_test.ex
    defmodule SimpleStatisticsTest do
    use ExUnit.Case
    doctest SimpleStatistics.Mean
    end
    Doctests can be run as tests
    

    View Slide

20. Run tests with Mix
    > mix test
    .
    Finished in 0.07 seconds (0.07s on load, 0.00s on tests)
    1 test, 0 failures
    

    View Slide

21. Introduction to Elixir
    Elixir’s build tool
    Background Mix Docs Types Conclusion
    Docstrings and
    Doctests
    Summary and further
    learning
    Introduction to
    Typespecs
    

    View Slide

22. Types
    

    View Slide

23. Typespecs
    @spec add(number, number) :: number
    def add(x, y) do
    x + y
    end
    @spec mean(nonempty_list(number)) :: float()
    def mean(list) do
    Enum.sum(list) / Kernel.length(list)
    end
    

    View Slide

24. Typespecs
    ● Scalars: integer(), float(), pos_integer()
    ● Lists: list(type), non_empty_list(type), [type]
    ● Functions: (type1, type2 -> type)
    ● Create your own types:
    @type t :: %ECS.Entity{
    id: String.t,
    components: [ECS.Component]
    }
    

    View Slide

25. Generate web-ready documentation with ex_doc
    # mix.exs
    defp deps do
    [{:ex_doc, "~> 0.11", only: :dev},
    {:earmark, "~> 0.1", only: :dev}]
    end
    

    View Slide

26. mix docs to generate documentation
    

    View Slide

27. View Slide

28. Introduction to Elixir
    Elixir’s build tool
    Background Mix Docs Types Conclusion
    Docstrings and
    Doctests
    Summary and further
    learning
    Introduction to
    Typespecs
    

    View Slide

29. Summary
    ● Mix
    ● Documentation & Docstrings
    ● Tests & Doctests
    ● Typespecs
    ● Hex
    

    View Slide

30. Thanks
    Yos Riady
    yos.io
    

    View Slide

31. A practical guide to
    Writing & Publishing Elixir Libraries
    Yos Riady
    yos.io
    goo.gl/PVekCF
    

    View Slide