Chapter 2. Innards of an Elixir Project

After looking at the building blocks in the past chapter, we will now explore the fundamental aspects of any Elixir project. There are a few rules that need to be followed, but fortunately every one of them is simple to adopt and contributes to an understandable project structure. An application that doesn't get in the way of the evolution and maintenance tasks during all its years in production is a joy for the people who work with it, and this is exactly what we aim for.

We will start by learning what an Elixir application is and how we can structure an Elixir project, along with some of the existing good practices that you can leverage. We will introduce Umbrella applications and how they can help you to define more rigid boundaries between your project's components. When creating our umbrella project, we will use some common scaffolding mix tasks, which let you quickly create an Elixir project from scratch. Afterward, we'll talk about ElixirDrip...

Elixir applications

Elixir inherits a lot of concepts from Erlang/OTP, and the application's behaviour is one of those concepts. For the Erlang VM, an application is a component that can be started and stopped as a single unit, and is described by an .app file (for example, hello_world.app) that defines, among other things, the Application Module Callback. This is a module that needs to implement a  start/2 function that's responsible for kickstarting the application, usually by spawning its top-level supervisor (in the next chapter, you'll learn all about supervisors). In a way, you can think about the start/2 function as the common main entry point on applications developed with other programming languages.

Because we're using Elixir, we don't need to explicitly specify the .app file. The Elixir compiler will find the correct application module callback by looking for a module using the Application behaviour and will then generate the .app file for us.

Let's use mix to generate a sample...

Elixir project structure

In the previous section, we created a sample project with Mix, but we didn't explore it thoroughly. Despite not enforcing a rigid structure and looking really simple, the Elixir project structure sets the baseline of every project, enabling you to get up to speed when facing a new codebase.

Let's create a simpler project, using mix new simple_project to generate the initial folder structure for us. Besides creating the .gitignore and README.md files, it also created the mix.exs file and three separate folders: config, lib and test. Take a look at this:

$ mix new simple_project
* creating README.md
* creating .gitignore
* creating mix.exs
* creating config
* creating config/config.exs
* creating lib
* creating lib/simple_project.ex
* creating test
* creating test/test_helper.exs
* creating test/simple_project_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd simple_project
    mix test

Run "mix help" for...

Umbrella projects

In the previous section, we started by defining and creating a sample Elixir application with Mix. By using the application's behaviour, we were able to start and stop it as a unit, and other applications could depend on it by pointing to this application in their dependencies.

As time passes, and your application gets bigger, you start thinking about how to divide it into smaller independent components with well-defined responsibilities. At this point, will you create a project from scratch for your recently extracted logic and add it as a dependency? Probably not, since, for now, those extracted components only make sense in the context of your original application.

An umbrella project helps you in this situation, because it allows you to have more than one application under the same Elixir project. Mix lets you achieve this by placing your individual applications under an apps folder in your umbrella project, while still allowing you to run each application separately...

ElixirDrip – our showcase application

To clearly illustrate how you may incorporate the concepts and strategies in this book, we will develop a fully fledged web application named ElixirDrip, which was kick-started by the umbrella project we have just created.

ElixirDrip aims to be a fast and scalable web storage service, allowing the user to easily store and share their files living on the cloud. Our users will be able to upload files to their cloud storage and then share those files with other ElixirDrip users.

We will be adding features to the ElixirDrip umbrella application as we progress, taking it closer to our final goal with each chapter. The most important features of our application will be tackled in specific chapters throughout this book. Consider the following:

• The design and implementation of our domain model will be analyzed in Chapter 7, Persisting Data Using Ecto, when we talk about data persistence and the usage of Ecto to efficiently query and update our application data...

Adopting a consistent coding style

During your project inception, one of the most important steps is deciding on how to structure your project. The choices made here will, in the long term, affect how you maintain and evolve your application. The usage of static code analysis tools also contribute to the ease of maintenance of your project, letting you catch bugs, syntax errors and weird code style as soon as possible.

Here, we'll configure Credo to analyze our code, looking for possible refactors, common mistakes and inconsistencies and then use the Elixir 1.6 formatter to format all the code of our application.

We do not want to run our static analysis tools in production, so we will only add Credo as a dependency for the dev and test environments. We'll also make sure that Credo stays put when we run our project, by setting its runtime option as false. This way Mix knows that Credo is not a runtime application and as such it won't try to start it. Take a look at this:

$ cat mix.exs
defmodule...

Summary

In this chapter, we looked at an Elixir project from different angles. Accompanied by the versatile Mix tool that comes with Elixir, we ended the chapter by kick-starting our ElixirDrip umbrella project with two umbrella applications. These were the key ideas we addressed here:

• An Elixir application defines an application callback function that is called when the VM starts any project, such as the main entry point of other languages. If you don't need to start your application, you don't need to implement the callback function. In this case, your code will amount to a simple bundle of modules and functions without any state.
• The Mix compile task compiles our code to BEAM bytecode and places every module under a flat folder structure, automatically creating an .app file for our project, so that the VM knows how to start every needed application.
• An Elixir project is composed of a mix.exs file and three folders, config, lib and test. After creating your project, you get an out-of-the...