Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
171 lines (122 sloc) 5.74 KB
id title
environment
Environment

<AUTOGENERATED_TABLE_OF_CONTENTS>

For each project esy manages:

  • build environment — an environment which is used to build the project

  • command environment — an environment which is used running text editors/IDE and for general testing of the built artfiacts

  • test environment — an environment which includes the current package's installation directories and expored environment. This is useful if you need an environment in which the current application appears installed.

Each environment consists of two parts:

  1. Base environment provided by esy.

  2. Environment exported from the sandbox dependencies. There are several types of dependencies esy can understand:

    1. Regular dependencies are dependencies which are needed at runtime. They are listed in "dependencies" key of the package.json.

    2. Development time dependencies are dependencies which are needed only during development. They are listed in "devDependencies" key of the package.json. Examples: @opam/merlin, @opam/ocamlformat and so on.

    3. Build time dependencies (NOT IMPLEMENTED) are dependencies which are only needed during the build of the project. Support for those is not implemented currently. The workaround is to declare such dependencies as regular dependencies for the time being.

Build Environment

The following environment is provided by esy:

  • $SHELL is set to env -i /bin/bash --norc --noprofile so each build is executed in an environment clear from user customizations usually found in .profile or other configuration files.

  • $PATH contains all regular dependencies' bin/ directories.

  • $MAN_PATH contains all regular dependencies' man/ directories.

  • $OCAMLPATH contains all regular dependencies' lib/ directories.

Each regular dependency of the project can also contribute to the environment through "esy.exportedEnv" key in package.json. See Project Configuration for details.

Command Environment

The following environment is provided by esy:

  • $PATH contains all regular and development time dependencies' bin/ directories.

  • $MAN_PATH contains all regular and development dependencies' man/ directories.

  • $OCAMLPATH contains all regular and development dependencies' lib/ directories.

Each regular and development dependency of the project can also contribute to the environment through "esy.exportedEnv" key in package.json. See Project Configuration for details.

Test Environment

The following environment is provided by esy:

  • $PATH contains all regular time dependencies' bin/ directories and project's own bin/ directory.

  • $MAN_PATH contains all regular dependencies' man/ directories and project's own man/ directory.

  • $OCAMLPATH contains all regular dependencies' lib/ directories and project's own lib/ directory.

Each regular dependency of the project and the project itself can also contribute to the environment through "esy.exportedEnv" key in package.json. See Project Configuration for details.

Variable substitution syntax

Your package.json's esy configuration can include "interpolation" regions written as #{ }, where esy "variables" can be used which will automatically be substituted with their corresponding values.

For example, if you have a package named @company/widget-factory at version 1.2.0, then its esy.build field in package.json could be specified as:

   "build": "make #{@company/widget-factory.version}",

and esy will ensure that the build command is interpreted as "make 1.2.0". In this example the interpolation region includes just one esy variable @company/widget-factory.version - which is substituted with the version number for the @company/widget-factory package.

Package specific variables are prefixed with their package name, followed by an esy "property" of that package such as .version or .lib.

esy also provides some other built in variables which help with path and environment manipulation in a cross platform manner.

Supported Variable Substitutions:

Those variables refer to the values defined for the current package:

  • self.bin
  • self.sbin
  • self.lib
  • self.man
  • self.doc
  • self.stublibs
  • self.toplevel
  • self.share
  • self.etc
  • self.install
  • self.target_dir
  • self.root
  • self.name
  • self.version
  • self.depends

You can refer to the values defined for other packages by using the respective package-name prefix:

  • package-name.bin
  • package-name.sbin
  • package-name.lib
  • package-name.man
  • package-name.doc
  • package-name.stublibs
  • package-name.toplevel
  • package-name.share
  • package-name.etc
  • package-name.install
  • package-name.target_dir
  • package-name.root
  • package-name.name
  • package-name.version
  • package-name.depends

The following constructs are also allowed inside "interpolation" regions:

  • $PATH, $cur__bin : environment variable references
  • 'hello', 'lib' : string literals
  • / : path separator (substituted with the platform's path separator)
  • : : env var value separator (substituted with platform's env var separator :/;).

You can join many of these esy variables together inside of an interpolation region by separating the variables with spaces. The entire interpolation region will be substituted with the concatenation of the space separated esy variables.

White space separating the variables are not included in the concatenation, If you need to insert a literal white space, use ' ' string literal.

Examples:

  • "#{pkg.bin : $PATH}"

  • "#{pkg.lib / 'stublibs' : $CAML_LD_LIBRARY_PATH}"