Module builder

Function index
Exported functions

Description

OTP release script builder.

This program compiles .rel, .script, .boot and sys.config files for erlang applications. It supports incremental and recursive builds, and is intended to be (much) easier and safer to use than doing it all manually. This program does not generate beam code from Erlang source files.

The program makes some assumptions:

The application is store in a directory whose name is composed with the name of the application '-' the version number of the application (i.e. myapp-1.0)
The release and app file used in input are simplified subset of the final Erlang release and app file. Some differences: Versions are handled automatically; You do not need to add the erts version tuple in the rel.src file; the application, currently being built is mandatory in the list of apps in the rel.src file; etc.

The program (henceforth called 'builder') can be customized using a number of options. The options are prioritized in the following order: (1) those given as arguments to the builder:go/1 function, those in the BUILD_OPTIONS file, and (3) the hard-coded defaults.

Valid options are

{app_dir, dirname()}

The application directory of the application being built. The default value is Current Working Directory.

{build_options, filename()}

A filename pointing to a BUILD_OPTIONS file. This is a file containing erlang expressions, each terminated by "." -- just like a file processed using file:eval/1. The last expression in the file should result in a list of {Key,Value} options. If this option is not given, builder will look in [AppDir] and [AppDir]/src for a file called BUILD_OPTIONS.
Pre-bound variables are:

ScriptName : filename(), the name of the script file.

{report, Level : atom()}

Specifies the reporting level. The following levels are recognized: none, progress, verbose, debug.

{out_dir, dirname()}

Specifies where [AppName].script, [AppName].boot, and sys.config should be written. Default is [AppDir]/priv.

{sys_config, filename()}

Specifies the location of the sys.config file. Default is [OutDir]/sys.config.

{rel_file, filename()}

Specifies which .rel file should be used as input for the build process. Default is [AppDir]/src/[AppName].rel.src.

{rel_name, string()}

This option can be used if the release should be called something other than [AppName] or whatever is in the .rel file.

{app_vsn, string()}

This option can be used to assign a version to the current application. If the application directory has a version suffix, the version suffix will override this option. If the directory has no suffix, the default vsn will be "BLDR", unless 'app_vsn' has been specified.

{apps, [App : AppName | {AppName,Vsn} | {AppName,Vsn,EbinDir}]}

This is a way to identify which applications should be included in the build. The way builder determines which applications should be included is this:

If there is a .rel.src file, the applications listed in this file are included first, in the order in which they are listed.
After this, all applications listed in the 'applications' attribute of the .app.src file are added (if not already listed), also in the order in which they are listed.
Then, all remaining applications in the 'apps' list are added in order.
Finally, any included applications listed in the .rel.src file, not already listed, are added. (note that applications listed in 'included_applications' of the .app.src file are not included here. The .rel file can be used to override this definition, so it would be an error to include it at this point.)

{path, [PathExpr]}

Specifies the search path when locating applications. Default is code:get_path(). PathExpr can contain wildcards, e.g. "/OTP/lib/kernel*/ebin" (basically anything that regexp:sh_to_awk/1 understands.)

{skip, [ModuleName : atom()]}

Lists modules that should not be included in the generated .app file for the current application. If not specified, builder will locate all modules under [AppDir]/src, extract their module names, and include these module names in the 'modules' list of the .app file.

{make_app, true | false | auto}

If true, builder will generate an .app file from an .app.src file; if false, it will try to use an existing .app file; if auto, it will build an .app file if no .app file exists Default is 'auto'.

{make_rel, true | false}

If true, builder will generate a .rel file from a .rel.src file; if false, it will assume that there is a working .rel file. Default: false if the rel_file option has been specified; true otherwise.

{make_boot, true | false}

If true, builder will run systools:make_script() to generate .script and .boot files in [OutDir]. If false, it will assume that there is a working .boot file. Default is true.

{systools, Options : [Opt]}

If specified, Options will be passed to the systools:make_script() command for building the .boot script. Note that the 'path' option is generated by builder. It cannot be overridden. See erl -man systools for available options.

{sh_script, auto | none}

If 'auto', builder will generate a small sh script that makes it easier to start the system; If 'none', no script will be generated. Default is 'none' on non-UNIX systems and 'auto' on UNIX systems.

{erl_opts, Opts : string()}

If specified, and if a sh_script is generated (see above), Opts will be appended to the erl command line. The builder will automatically put in options to identify the boot script, sys.config, and possible boot variables.

{config, Config : {file, filename()} | {M,F,A} | Data}

If present, this option should either point to a file that contains a subset of data for a sys.config file (same format as sys.config), or give a {M,F,A} tuple, where apply(M,F,A) results in a list, [{AppName, [{Key, Value}]}], or finally just specify the data in place. The builder will look for similar config directives in any BUILD_OPTIONS files of other applications that are part of the build, and all inputs will be merged into a common sys.config.

{{config,OtherApp}, Config}

This is a way to specify environment variables for another application in the build options. Config in this case is the same as Config above. The difference between this option and specifying environment variables for the other application using the above option, is that with a simple {config, ...} directive, builder will also check for a similar directive in the other application, and all different inputs will be merged. Using a {{config,App},...} option, builder will not look into that application further.

Function Index

Exported Functions
early_debug_on/0
find_app/2
go/0
go/1

Module builder

Description

Function Index

Exported Functions

early_debug_on/0

find_app/2

go/0

go/1