Generating umbrella applications

The "Erlang way" is to name each self-contained unit of code as an app. Sometimes, an app may be what is referred to as a library in other languages. This is a great way to achieve code reusability and modularity, but sometimes, it is convenient to treat all the apps in a project as a single entity, committing them as a whole to version control, to allow running tests, and so on. Think of an umbrella application as a container used to hold one or more applications and to make them behave as a single application.

This recipe shows how to create umbrella applications with Mix.

How to do it…

1. Generate an umbrella application to contain other applications:

   mix new --umbrella container
   

   What happens next is shown in the following screenshot:

   
2. Generate application_one and application_two inside the container/apps directory:

   > cd container/apps
   > mix new application_one
   > mix new application_two
   

3. Modify the tests in the applications as follows:
   • Change the test in container/apps/application_one/application_one_test.exs like this:

     test "the truth on application one" do
       IO.puts "Running Application One tests"
       assert 1 + 1 == 2
     end

   • Change the test in container/apps/application_two/application_two_test.exs as shown here:

     test "the truth on application two" do
       IO.puts "Running Application Two tests"
       assert 2 - 1 == 1
     end

4. Run the tests in all applications (inside the container directory):

   > mix test
   

   The result of these tests is shown here:

   
5. Now run the tests individually. Firstly, run them for application_one as follows:

   > cd apps/application_one
   > mix test
   

   The outcome of these tests is shown in the following screenshot:

   

   For application_two , run them like this:

   > cd ../application_two
   > mix test
   

   The result of these tests is shown in this screenshot:

   

How it works…

By generating this structure of the application with subprojects under the apps directory, Elixir makes dependency management, compilation, and testing easier. It is possible to perform these tasks at the umbrella application level, affecting all the subprojects, or at each subproject level, allowing a high level of granularity.

See also

• The Elixir Getting Started guide on dependencies and umbrella projects is available at http://elixir-lang.org/getting_started/mix_otp/7.html. It says the following:

  Remember that the runtime and the Elixir ecosystem already provide the concept of applications. As such, we expect you to frequently break your code into applications that can be organized logically, even within a single project. However, if you push every application as a separate project to a Git repository, your projects can become very hard to maintain, because now you will have to spend a lot of time managing those Git repositories rather than writing your code.

  For this reason, Mix supports "umbrella projects." Umbrella projects allow you to create one project that hosts many applications and push all of them to a single Git repository. That is exactly the style we are going to explore in the next sections.