Executables

Mix.install([
  {:jason, "~> 1.4"},
  {:kino, "~> 0.9", override: true},
  {:youtube, github: "brooklinjazz/youtube"},
  {:hidden_cell, github: "brooklinjazz/hidden_cell"}
])

Navigation

Review Questions

Upon completing this lesson, a student should be able to answer the following questions.

• How do you configure a project as an executable script?

Executables

We can configure mix projects to run as an executable script using escript.

Once configured, we can run a mix project using an executable file inside of the project folder.

./project_name

To demonstrate how to configure an executable, We’re going to create a simple greeting executable which prints a good morning message.

Create a new mix project.

$ mix new greeting

First, we need to define a module with a main/1 function. This function will be what’s triggered by the executable. We can modify the existing Greeting module in lib/greeting.ex.

defmodule Greeting do
  def main(_args) do
    IO.puts("Good morning!")
  end
end

Remove doctests and the existing test macros to ensure all tests pass when you run mix test.

Executable Configuration

In any mix project, we can configure an executable using the :escript option in the mix.exs file. Add the :escript configuration to the existing project/0 function.

We’ve defined our main/1 function in the Greeting module, so we provide that as our :main_module.

def project do
  # make sure you keep existing configuration
  escript: [main_module: Greeting]
end

Now we have to build the executable script from the greeting folder.

$ mix escript.build

Execute the script to see the good morning message.

$ ./greeting
Good morning!

Parsing Arguments

We can provide arguments to executable scripts using --arg_name flags. A flag can be empty, or it can have a value --arg_name=true.

Elixir provides an OptionParser module to parse arguments provided to the script into Elixir terms.

OptionParser.parse(["--flag=true"], switches: [flag: :boolean])

If the :boolean type is given, flags are true by default when provided.

OptionParser.parse(["--flag=true"], switches: [flag: :boolean])

Or we can set them to false.

OptionParser.parse(["--flag=false"], switches: [flag: :boolean])

Arguments may have different types such as :boolean, :count, :integer, :float, and :string.

OptionParser.parse(["--time=hello"], switches: [time: :string])

OptionParser.parse(["--name=hello"], switches: [name: :string])

For example, we can use a --time flag to change the greeting based on the time of day.

defmodule Greeting do
  def main(args) do
    {opts, _word, _errors} = OptionParser.parse(args, switches: [time: :string])
    IO.puts("Good #{opts[:time] || "morning"}!")
  end
end

Now rebuild the script, and you can customize the message using the --time flag.

$ mix escript.build
$ ./greeting --time="evening"
Good evening!

Your Turn

Create an --upcase flag, which upcases the greeting so "Good morning! becomes GOOD MORNING!.

Commit Your Progress

DockYard Academy now recommends you use the latest Release rather than forking or cloning our repository.

Run git status to ensure there are no undesirable changes. Then run the following in your command line from the curriculum folder to commit your progress.

$ git add .
$ git commit -m "finish Executables reading"
$ git push

We’re proud to offer our open-source curriculum free of charge for anyone to learn from at their own pace.

We also offer a paid course where you can learn from an instructor alongside a cohort of your peers. We will accept applications for the June-August 2023 cohort soon.

Navigation