Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
360 lines (135 sloc) 9.47 KB

Module setup

Setup utility for erlang applications.

Behaviours: application.

Function Index

data_dir/0Returns the configured data dir, or a best guess (home()/data.Node).
find_app/1Equivalent to find_app(A, lib_dirs()).
find_app/2Locates application A along LibDirs (see lib_dirs/0 and lib_dirs/1) or under the OTP root, returning all found candidates.
find_env_vars/1Searches all loaded apps for instances of the Env environment variable.
home/0Returns the configured home directory, or a best guess ($CWD).
lib_dirs/0Equivalent to lib_dirs(concat("ERL_SETUP_LIBS", "ERL_LIBS")).
lib_dirs/1Returns an expanded list of application directories under a lib path.
log_dir/0Returns the configured log dir, or a best guess (home()/log.Node).
patch_app/1Adds an application's "development" path to a target system.
pick_vsn/3Picks the specified version out of a list returned by find_app/1
read_config_script/3
reload_app/1Equivalent to reload_app(AppName, latest).
reload_app/2Equivalent to reload_app(AppName, latest, lib_dirs()).
reload_app/3Loads or upgrades an application to the specified version.
start/2Application start function.
stop/1Application stop function end.
verify_dir/1Ensures that the directory Dir exists and is writable.
verify_directories/0Ensures that essential directories exist and are writable.

Function Details

data_dir/0

data_dir() -> Directory



Returns the configured data dir, or a best guess (home()/data.Node).

find_app/1

find_app(A::atom()) -> [{Vsn, Dir}]



Equivalent to find_app(A, lib_dirs()).

find_app/2

find_app(A::atom(), LibDirs::[string()]) -> [{Vsn, Dir}]



Locates application A along LibDirs (see lib_dirs/0 and lib_dirs/1) or under the OTP root, returning all found candidates. The version is extracted from the .app file; thus, no version suffix in the path name is required.

find_env_vars/1

find_env_vars(Env) -> [{AppName, Value}]



Searches all loaded apps for instances of the Env environment variable.

The environment variables may contain instances of $APP, $PRIV_DIR, $LIB_DIR, $DATA_DIR, $LOG_DIR, $HOME, inside strings or binaries, and these will be replaced with actual values for the current system ($APP simply expands to the name of the current application).

home/0

home() -> Directory



Returns the configured home directory, or a best guess ($CWD)

lib_dirs/0

lib_dirs() -> [string()]



Equivalent to lib_dirs(concat("ERL_SETUP_LIBS", "ERL_LIBS")).

lib_dirs/1

lib_dirs(Env::string()) -> [string()]



Returns an expanded list of application directories under a lib path

This function expands the (ebin/) directories under e.g. $ERL_SETUP_LIBS or $ERL_LIBS. $ERL_SETUP_LIB has the same syntax and semantics as $ERL_LIBS, but is (hopefully) only recognized by the setup application. This can be useful e.g. when keeping a special 'extensions' or 'plugin' root that is handled via setup, but not treated as part of the normal 'automatic code loading path'.

log_dir/0

log_dir() -> Directory



Returns the configured log dir, or a best guess (home()/log.Node)

patch_app/1

patch_app(AppName::atom()) -> true | {error, Reason}



Adds an application's "development" path to a target system

This function locates the given application (AppName) along the $ERL_LIBS
path, and prepends it to the code path of the existing system. This is useful
not least when one wants to add e.g. a debugging or trace application to a
target system.

The function will not add the same path again, if the new path is already the 'first' path entry for the application A.

pick_vsn/3

pick_vsn(App::atom(), Dirs::[{Vsn::string(), Dir::string()}], Vsn::Which) -> {Vsn, Dir}
  • Which = latest | next | Regexp

Picks the specified version out of a list returned by find_app/1

  • If Which is a string, it will be used as a re regexp pattern, and the
    first matching version will be returned.

  • If Which = latest, the last entry in the list will be returned (assumes
    that the list is sorted in ascending version order).

  • If Which = next, the next version following the current version of the application A is returned, assuming A is loaded; if A is not loaded,
    the first entry in the list is returned.

If no matching version is found, the function raises an exception.

read_config_script/3

read_config_script(F, Name, Opts) -> any()

reload_app/1

reload_app(AppName::atom()) -> {ok, NotPurged} | {error, Reason}



Equivalent to reload_app(AppName, latest).

reload_app/2

reload_app(AppName::atom(), ToVsn) -> {ok, UnPurged} | {error, Reason}



Equivalent to reload_app(AppName, latest, lib_dirs()).

reload_app/3

reload_app(AppName::atom(), ToVsn0::ToVsn, LibDirs) -> {ok, Unpurged} | {error, Reason}
  • ToVsn = latest | next | Vsn
  • LibDirs = [string()]
  • Vsn = string()

Loads or upgrades an application to the specified version

This function is a convenient function for 'upgrading' an application. It locates the given version (using find_app/1 and pick_vsn/3)
and loads it in the most appropriate way:

  • If the application isn't already loaded, it loads the application and
    all its modules.

  • If the application is loaded, it generates an appup script and performs a soft upgrade. If the new version of the application has an .appup script
    on-disk, that script is used instead.

The application is searched for along the existing path (that is, under the roots of the existing code path, allowing for e.g. $ROOT/lib/app-1.0 and $ROOT/lib/app-1.2 to be found and tested against the version condition), and also along LibDirs (see lib_dirs/0 an lib_dirs/1).

The generated appup script is of the form:

  • add modules not present in the previous version of the application

  • do a soft upgrade on pre-existing modules, using suspend-code_change-resume

  • delete modules that existed in the old version, but not in the new.

The purge method used is brutal_purge - see //sasl/appup.

For details on how the new version is chosen, see find_app/1 and pick_vsn/3.

start/2

start(X1::Type, Args) -> {ok, pid()}



Application start function.

stop/1

stop(X1::State) -> ok



Application stop function end

verify_dir/1

verify_dir(Directory::Dir) -> Dir



Ensures that the directory Dir exists and is writable.

verify_directories/0

verify_directories() -> ok



Ensures that essential directories exist and are writable. Currently, only the log directory is verified.

Jump to Line
Something went wrong with that request. Please try again.