Skip to main content

Multiple Project Sandboxes

Sometimes it is useful to configure multiple sandboxes per project:

  • to build a project with a different compiler version
  • to try a project with a different set of dependencies installed
  • to build a project using differeng settings configured via environment variables

It is inconvenient to modify package.json and reinstall dependencies each time you want to work in a different sandbox configuration.

To streamline this esy provides an ability to have multiple sandbox configurations per project.

Configure multiple sandboxes​

Put ocaml-4.6.json file into the project directory.

ocaml-4.6 can be any other name you like for your sandbox config:

  • with-ocaml-4.6.json
  • debug-build.json

ocaml-4.6.json file should have the same format as package.json but can have different configuration for dependencies, devDependencies, esy.build or other fields described in Project Configuration.

For example:

{
  ...
  "devDependencies": {
    "ocaml": "~4.6.0"
  }
  ...
}

To instruct esy to work with ocaml-4.6.json sandbox configuration (instead of default package.json) you can use @ocaml-4.6 sandbox selector:

  • Install the dependencies of the ocaml-4.6 sandbox:

    esy @ocaml-4.6 install

  • Build the ocaml-4.6 sandbox:

    esy @ocaml-4.6 build

  • Run a command with the ocaml-4.6 sandbox environment:

    esy @ocaml-4.6 which ocaml

Note that sandbox selector @<sandbox-name> should be the first argument to esy command, otherwise it is treated as an option to a subcommand and won't have the desired effect.

Sandbox configuration overrides​

When sandbox configurations differ just by few configuration parameters it is too much boilerplate to copy over all package.json fields to a new sandbox configuration.

It is possible to use sandbox configuration overrides to aleviate the need in such boilerplate.

Overrides have the following format:

{
  "source": "./package.json",
  "override": {
    <override-fields>
  }
}

Where source key defines the origin configuration which is being overriden with the fields from override key.

Not everything can be overriden and <override-fields> can contain one or more of the following keys.

build​

This replaces esy.build commands of the origin sandbox configuration:

"override": {
  "build": "dune build"
}

install​

This replaces esy.install commands of the origin configuration.

"override": {
  "install": "esy-installer project.install"
}

exportedEnv​

This replaces esy.exportedEnv set of exported environment variables of the origin configuration.

"exportedEnv": {
  "NAME": {"val": "VALUE", "scope": "global"}
}

If you need to add to a set of exported environment variables rather than replace the whole set use exportedEnvOverride key instead.

exportedEnvOverride​

This overrides esy.exportedEnv set of exported environment variables of the origin configuration.

Environment variables specified using this key are being added instead of replacing the entire set. If a declaration for an environment variable is set to null then the variable is removed from the set.

"exportedEnvOverride": {
  "VAR_TO_ADD": {"val": "VALUE", "scope": "global"},
  "VAR_TO_REMOVE": null
}

buildEnv​

This replaces esy.buildEnv set of build environment variables of the origin configuration.

"buildEnv": {
  "NAME": "VALUE"
}

If you need to add to a set of build environment variables rather than replace the whole set use buildEnvOverride key instead.

buildEnvOverride​

This overrides esy.buildEnv set of build environment variables of the origin configuration.

Environment variables specified using this key are being added instead of replacing the entire set. If a declaration for an environment variable is set to null then the variable is removed from the set.

"buildEnvOverride": {
  "VAR_TO_ADD": "VALUE",
  "VAR_TO_REMOVE": null
}

dependencies​

This overrides dependencies set of dependency declaraations of the origin configuration.

"dependencies": {
  "dependency-to-add": "^1.0.0",
  "dependency-to-remove": null
}

devDependencies​

This overrides devDependencies set of dev dependencies of the origin configuration.

"devDependencies": {
  "dependency-to-add": "^1.0.0",
  "dependency-to-remove": null
}

resolutions​

This replaces resolutions set of dependency resolutions.