Skip to content

Layerapi2

1. General

The layerapi2 library is the heart of mfext layers system.

You should read the layerapi2 reference documentation.

2. How we use layerapi2 in MetWork?

2.1 Layer names

We use the following convention for layer names:

name@module_name_in_lowercase

For example: python3@mfserv.

2.2 LAYERAPI2_LAYERS_PATH

First of all, we set in LAYERAPI2_LAYERS_PATH:

  • ${MFEXT_HOME}
  • ${MFEXT_HOME}/opt
  • ${MFMODULE_HOME} (if the current module is not mfext)
  • ${MFMODULE_HOME}/opt (if the current module is not mfext)
  • ${MFMODULE_RUNTIME_HOME}/var/plugins (if the current module is mfserv, mfbase or mfdata)

So we have a kind of layers inheritance. For example: mfserv => mfext.

2.3 Special layers

In each module, we have two special layers:

  • root@module_name_in_lowercase (example: root@mfext)
  • default@module_name_in_lowercase) (example: default@mfdata)

The first one is special because of its "layer home" (see next paragraph). And the second is mainly an empty layer with dependencies. This layer is loaded by default when you "source" the corresponding module (or when you log in as mfxxx user).

So this "default" layer is used to select (with its dependencies) which layers are loaded by default (have a look at its .layerapi2_dependencies file).

In mfserv, mfdata and mfbase modules, we have some other special layers:

plugin_foo@module_name_in_lowercase

For user-provided plugins (which are regular layers but with a custom "layer_home" (see next paragraph).

2.4 Layer homes

The layer home of foo@mfserv (for example) is always:

${MFSERV_HOME}/opt/foo

There are two exceptions:

  • one for root@module_name_in_lowercase (see "special layers") (for this one, its layer home is : ${MFMODULE_HOME})
  • one for plugin_foo@module_name_in_lowercase (see "special layers") (for these layers, their layer home is ${MFMODULE_RUNTIME_HOME}/var/plugins/foo)

2.5 Real example

When we log in as mfserv on a machine with a lot of layers, you can have something like this:

$ layers

- plugin_welcome@mfserv [/home/fab/metwork/mfserv/var/plugins/welcome]
- (*) default@mfserv [/home/fab/metwork/mfserv/build/opt/default]
- python2@mfserv [/home/fab/metwork/mfserv/build/opt/python2]
- nodejs@mfserv [/home/fab/metwork/mfserv/build/opt/nodejs]
- (*) python3@mfserv [/home/fab/metwork/mfserv/build/opt/python3]
- (*) root@mfserv [/home/fab/metwork/mfserv/build]
- (*) python3_vim@mfext [/home/fab/metwork/mfext/build/opt/python3_vim]
- python2_devtools@mfext [/home/fab/metwork/mfext/build/opt/python2_devtools]
- (*) core@mfext [/home/fab/metwork/mfext/build/opt/core]
- (*) tcltk@mfext [/home/fab/metwork/mfext/build/opt/tcltk]
- (*) default@mfext [/home/fab/metwork/mfext/build/opt/default]
- (*) devtools@mfext [/home/fab/metwork/mfext/build/opt/devtools]
- (*) openresty@mfext [/home/fab/metwork/mfext/build/opt/openresty]
- python2@mfext [/home/fab/metwork/mfext/build/opt/python2]
- (*) nodejs@mfext [/home/fab/metwork/mfext/build/opt/nodejs]
- (*) python3_core@mfext [/home/fab/metwork/mfext/build/opt/python3_core]
- python2_core@mfext [/home/fab/metwork/mfext/build/opt/python2_core]
- (*) scientific_core@mfext [/home/fab/metwork/mfext/build/opt/scientific_core]
- (*) python3_devtools@mfext [/home/fab/metwork/mfext/build/opt/python3_devtools]
- python3_circus@mfext [/home/fab/metwork/mfext/build/opt/python3_circus]
- (*) monitoring@mfext [/home/fab/metwork/mfext/build/opt/monitoring]
- python2_vim@mfext [/home/fab/metwork/mfext/build/opt/python2_vim]
- (*) python3@mfext [/home/fab/metwork/mfext/build/opt/python3]
- (*) java@mfext [/home/fab/metwork/mfext/build/opt/java]
- (*) vim@mfext [/home/fab/metwork/mfext/build/opt/vim]
- (*) root@mfext [/home/fab/metwork/mfext/build]

Note: you have (*) before the layer label if the corresponding layer is already loaded

We can see various layers of various modules installed. A lot of them are loaded. You can also see a mfserv plugins (of course not loaded).

2.6 Tools

Have a look at layerapi2 reference documentation for details but main tools available around layer system are:

2.6.1 layers

$ layers --help
Usage:
  layers [OPTION?] - list installed layers

Help Options:
  -h, --help              Show help options

Application Options:
  -r, --raw               raw output
  -m, --loaded-filter     Loaded layer filter (default: no filter, possible values: yes, no)

2.6.2 is_layer_installed, is_layer_loaded

$ is_layer_installed --help
Usage:
  is_layer_installed [OPTION?] LAYER LABEL - output 1 is the given layer is installed

Help Options:
  -h, --help       Show help options

$ is_layer_loaded --help
Usage:
  is_layer_loaded [OPTION?] LAYER LABEL OR LAYER HOME - output 1 is the given layer is already loaded

Help Options:
  -h, --help       Show help options

2.6.3 layer_wrapper

$ layer_wrapper --help
Usage:
  layer_wrapper [OPTION?] -- COMMAND [COMMAND_ARG1] [COMMAND_ARG2] [...] - wrapper to execute the given command in a process with some specific layers loaded

Help Options:
  -h, --help                 Show help options

Application Options:
  -d, --debug                debug mode
  -e, --empty                unload all layers before
  -c, --cwd                  change working directory to the last layer home
  -x, --extra-env-prefix     if set, add three environnement variables {PREFIX}_NAME, {PREFIX}_LABEL and {PREFIX}_DIR containing the last layer name, label and the last layer home 
  -E, --empty-env            empty environnement (imply --empty)
  -k, --empty-env-keeps      coma separated list of env var to keep with --empty-env
  -l, --layers               coma separated list of layers labels/homes ('-' before the name of the layer means 'optional dependency')
  -p, --prepend-env          ENV_VAR,VALUE string to prepend VALUE in : separated ENV_VAR (like PATH) (can be used multiple times)
  -f, --force-prepend        do not check existing paths in prepend
  --dont-load-optional       don't load optional layers

2.6.4 layer_load, layer_unload

layer_load and layer_unload are two bash functions to load or unload an installed layer.

For example:

layer_load python2@mfext