BINETIX NETWORK

The MAKE_APP tool-set is using ASCII-based configuration file to describe how to process single software solution.

This configuration file MUST be named as make_app.config (lower-case only!) and maintained into the root-directory of your solution. The root-directory is used by MAKE_APP to calculate other relative to the project sub-directories, and to keep also the portability of the entire solution - for example, you can move the solution to another file system tree branching and the configuration should not be changed and MAKE_APP will work in the same way.

The configuration file consists of well-formed sets of Erlang terms and data types encoded in ISO-8859-1 (Latin-1) characters called configuration elements. Each configuration element MUST end with a single dot. Do not forget this DOT after each element, otherwise your configuration shall be misspelled and rejected. Take into consideration that MAKE_APP is interpreting only particular subset of terms required for configuration purposes, therefore the current documentation covers only this subset of terms.

Last but not least, the configuration elements can be used in different order. You can assemble and organize your configuration at your own style and convenience.

Complete example of simple configuration file is published on page "First Steps".

The following configuration elements are supported by MAKE_APP and can be used in make_app.config file:

•{include, <extension>}. - used to activate particular configuration extension;

•{solution, <solution_id>, <solution_properties>}. - used to define your software solution;

•{project, <project_id>, <project_properties>}. - used to define one or more projects that could be used by the solution;

•{task, <task_id>, <task_properties>}. - used to define one or more configuration tasks that could be used by your projects.

The configuration extensions are external modules used by the MAKE_APP tool-set to add specific functionality to your task activities.

You can activate this functionality by adding one or more extensions using the include configuration element with the following notation:

{include, <extension>}.

where <extension> is an Erlang atom and refers to the Extension's identifier.

For example, to activate extension for Erlang projects with support of additional file system operations you have to add into your make_app.config file the following two lines:

{include, files}.

{include, erlang}.

These lines require the following extensions to be available for MAKE_APP in order to be activated:

✓make_app_files.beam

✓make_app_erlang.beam

The software solution is the generic definition of your work as a developer.

MAKE_APP supports one or more software solutions in the same make_app.config file. In this way you could organize the resources from your configuration file differently and you can perform group activities from the command line using the respective solution identifiers. One software solution is defined by one solution configuration element.

The solution configuration element has the following notation:

{solution, <solution_id>, <solution_properties>}.

where:

•<solution_id> - Atom. Defines a unique solution identifier;

•<solution_properties> - Map #{}. Describes the solution properties as a set of key-value items. The following key-names of this map are supported:

oname - String. Defines the name of the solution that will be printed-out when performing activities from the command line.

oprojects - Prioritized list of project identifiers (atoms) that shall be processed.

olibs - Optional list of items describing external libraries used by particular extension for the current solution. The format depends on the used extension.

ospec - Optional solution-specific definitions required by extensions. Usually this is a list of terms or tuples with solution-related data, parameters and other settings.

Example of software solution definition ready to be managed by the Erlang extension:

{solution, my_solution, #{
  name     => "My new AGE App",
  projects => [myapp_2019],
  spec     => [{id, "MY_APP"}, {vsn, "1.0"}, {description, "My new AGE application on Erlang"}]
}}.

The software project definition, as a part of the overall configuration, encapsulate particular file system resources (like source code files, directories and directory trees and other files) and project-related tasks into one bundle of activities that could be invoked with parameters by project identifier.

The software projects are virtual and shared resource of the configuration file. They cannot be invoked without some context defined by a software solution. In other words, one or more project definitions can be used by one or more software solutions described into the same configuration file. One software project is defined by one project configuration element.

The project configuration element has the following notation:

{project, <project_id>, <project_properties>}.

where:

•<project_id> - Atom. Defines a unique project identifier;

•<project_properties> - Map #{}. Describes the project properties as a set of key-value items. The following key-names of this map are supported:

oname - String. Defines the name of the project that will be printed-out when performing activities.

osource - Prioritized list of items with file-system resources planned to be used by this project. The following notations are supported for the items:

▪"<directory>" - String with the relative path to directory. By default, the directories are processed recursively with all files and sub-directories.

▪"<file>" - String with relative path to file. Note that MAKE_APP automatically recognizes and differs files from directories.

▪{"<directory>", <item_options>}, or

▪{"<file>", <item_options>}, where item_options is a list of configuration terms. The following terms are supported:

✓non_recursive - suppress any directory recursive processing. Only the files on first-level shall be processed. This option is supported by Files extension.

✓skip - the file or directory is explicitly selected to be skipped on processing.

✓skip_app - this is an Erlang-specific option that tells MAKE_APP not to include the compiled module into the App specification when it is (re)generated. This option is supported by the Erlang extension.

otasks - List of tasks to be performed by this project. The invocation of single task has the following notation:

▪{<task_id>, <task_properties>}, where:

✓task_id - refers to task identifier defined by task configuration element. More details are provided below.

✓task_properties - list of properties supported by the selected task. Usually the list contains atoms, tuples or other task-specific configuration terms.

Example of software project definition with 3 tasks to be performed recursively on directory with relative path "<config_root>/src":

{project, myapp_2019, #{
  name   => "My New App Project",
  source => ["src"],
  tasks  => [
    {debug,  [{outdir, "ebin"}, {i, "include"}, {d, '_DEBUG'}]},
    {make,   [local]},
    {run,    [{sname, myapp@localhost}, {setcookie, binetix_age}]}
  ]
}}.

Task is a virtual operation that can be performed by some software project. One or more task definitions can be used by one or more software projects described into the same configuration file. One task is defined by one task configuration element.

The task configuration element has the following notation:

{task, <task_id>, <task_properties>}.

where:

•<task_id> - Atom. Defines a unique task identifier;

•<task_properties> - Map #{}. Describes the task properties as a set of key-value items. The following key-names of this map are supported:

olabel - Optional string. Describes in short what the task shall do;

ocall - Atom or list of atoms. This key consists one or more custom-defined identifiers that can be invoked by the command line <call> parameter in order to perform one or more tasks relevant to the command line invocation. More information with examples is provided on page "First Steps";

ocommand - Atom. This identifier refers to particular command exported by some of the activated extensions within the configuration file. This command shall be executed in case relevant command line invocation;

oargs - List of terms. The list contains terms provided as arguments to the Extension's command;

oapps - List of terms. This is an Erlang specific key-name supported by the Erlang extension. It specifies the task-specific system applications to be initiated by the BEAM virtual machine on application start-up.

As you can see, the tasks are fully customizable and can be used in different variation and context. Using the call key-name you can define your own invocations from the command line. For example, the following command line invocation shall perform run task on my_solution with default arguments (args):

$ escript make_app.beam my_solution run

In this BASH invocation the call parameter run matches with the task identifier run, shown on the example below, which is fully allowed by the MAKE_APP tool-set. However, the call and the task identifiers are usually different.

Examples of task definitions:

{task, run, #{
  label   => "Erlang: RUN (shell)",
  call    => run,
  command => eshell,
  args    => ["+W w +A 100"]
}}.
 
{task, make, #{
  label   => "Erlang: Generate boot script",
  call    => [build, deploy],
  command => emake,
  args    => [no_warn_sasl],
  apps    => [
    {kernel, permanent},
    {stdlib, permanent},
    {sasl,   permanent}
  ]
}}.