$30 off During Our Annual Pro Sale. View Details »

Writing and Publishing Elixir Libraries

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.

Yos Riady

March 16, 2017
Tweet

More Decks by Yos Riady

Other Decks in Programming

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