enso/docs/distribution/distribution.md

layout	title	category	tags	order
developer-doc	The Enso Distribution	distribution	distribution layout	1

The Enso Distribution

This document provides a specification of how the Enso distribution should be structured and how it should behave.

• Universal Launcher
• Enso Distribution Layout
  • Portable Enso Distribution Layout
  • Installed Enso Distribution Layout
  • Installing from a Portable Distribution
• Layout of an Enso Version Package
  • Standard Library
• Enso Home Layout

Universal Launcher

The universal launcher should be able to launch the proper version of Enso executable based on the version specified in the project being run, or use the default version if none specified. It should also be able to launch other Enso components, provided as plugins.

This launcher is under development. Until it is in a ready-to-use state, the Enso version packages provide simple launcher scripts in the bin directory of that package. They are a temporary replacement for the launcher functionality, so once the universal launcher matures, they will be removed. The universal launcher will not call the components through these scripts, as it must have full control over which JVM is chosen and its parameters.

Enso Distribution Layout

Enso is distributed as a portable package that can be extracted anywhere on the system and run. It can also be installed for the local user into system-defined directories, as explained below.

Portable Enso Distribution Layout

All files in the directory structure, except for the configuration, can be safely removed, and the launcher will re-download them if needed.

The directory structure is as follows:

extraction-location
├── bin
│   └── enso                # The universal launcher, responsible for choosing the appropriate compiler version.
├── config
│   └── global-config.yaml  # Global user configuration.
├── dist                    # Per-compiler-version distribution directories.
│   ├── 1.0.0               # A full distribution of given Enso version, described below.
│   │   └── <truncated>
│   └── 1.2.0               # A full distribution of given Enso version, described below.
│       └── <truncated>
├── runtime                 # A directory storing distributions of the JVM used by the Enso distributions.
│   └── graalvm-ce-java11-27.1.1
├── lib                     # Contains sources of downloaded libraries.
│   └── Standard            # Each prefix (usually corresponding to the author) is placed in a separate directory.
│       └── Dataframe       # Each library may be stored in multiple versions.
│           └── 1.7.0       # Each version contains a standard Enso package.
│               ├── package.yaml
│               └── src
│                   ├── List.enso
│                   ├── Number.enso
│                   └── Text.enso
├── editions                # Contains Edition specifications.
│   ├── 2021.4.yaml
│   └── nightly-2021-06-31.yaml
├── README.md               # Information on layout and usage of the Enso distribution.
├── .enso.portable          # A file that allows the universal launcher to detect that if it is run from this directory, it should run in portable distribution mode.
└── THIRD-PARTY             # Contains licences of distributed components, including the NOTICE file.

Installed Enso Distribution Layout

After installation, the directory structure is following:

ENSO_DATA_DIRECTORY
├── dist                    # Per-compiler-version distribution directories.
│   ├── 1.0.0               # A full distribution of given Enso version, described below.
│   │   └── <truncated>
│   └── 1.2.0               # A full distribution of given Enso version, described below.
│       └── <truncated>
├── runtime                 # A directory storing (optional) distributions of the JVM used by the Enso distributions.
│   └── graalvm-ce-java11-27.1.1
├── lib                     # Contains sources of downloaded libraries.
│   └── Standard            # Each prefix (usually corresponding to the author) is placed in a separate directory.
│       └── Dataframe       # Each library may be stored in multiple versions.
│           └── 1.7.0       # Each version contains a standard Enso package.
│               ├── package.yaml
│               └── src
│                   ├── List.enso
│                   ├── Number.enso
│                   └── Text.enso
└── editions                # Contains Edition specifications.
    ├── 2021.4.yaml
    └── nightly-2021-06-31.yaml

ENSO_CONFIG_DIRECTORY
└── global-config.yaml      # Global user configuration.

ENSO_BIN_DIRECTORY
└── enso                    # The universal launcher, responsible for choosing the appropriate compiler version.

Where ENSO_DATA_DIRECTORY, ENSO_CONFIG_DIRECTORY and ENSO_BIN_DIRECTORY are environment variables that define the directory structure. They can be used to override placement of the components listed above. However, most of the time they do not have to be set, as they use system-specific defaults.

If not set, each of these three environment variables defaults to the following value, depending on the system:

	Linux	macOS	Windows
ENSO_DATA_DIRECTORY	$XDG_DATA_HOME/enso/ which defaults to $HOME/.local/share/enso	$HOME/Library/Application Support/org.enso/	%LocalAppData%/enso
ENSO_CONFIG_DIRECTORY	$XDG_CONFIG_HOME/enso/ which defaults to $HOME/.config/enso	$HOME/Library/Preferences/org.enso/	%LocalAppData%/enso/config
ENSO_BIN_DIRECTORY	$XDG_BIN_HOME which defaults to $HOME/.local/bin	$HOME/.local/bin	%LocalAppData%/enso/bin
ENSO_RUNTIME_DIRECTORY	$XDG_RUNTIME_DIR/enso/ or if its missing, ENSO_DATA_DIRECTORY	ENSO_DATA_DIRECTORY	%LocalAppData%/enso
ENSO_LOG_DIRECTORY	$XDG_CACHE_HOME/enso or if its missing, ENSO_DATA_DIRECTORY/log	$HOME/Library/Logs/org.enso/	%LocalAppData%/enso/log

Installing from a Portable Distribution

After downloading and extracting the portable distribution, the user can run extraction-location/bin/enso install distribution to install it locally. This will copy the files from the portable distribution into the installed locations which are described above and then remove the original files.

On Linux and macOS, if ENSO_BIN_DIRECTORY (~/.local/bin by default) is not on system PATH, the installer will issue a warning, telling the user how they can add it. On Windows, the installer automatically adds ENSO_BIN_DIRECTORY to the user's PATH.

The installed distribution can be removed by running enso uninstall distribution.

Layout of an Enso Version Package

This section describes the structure of a single version distribution. This system is intended to be implemented first and used e.g. for the Enso nightly builds / releases.

Such a distribution can be used as a standalone version, assuming the required version of the JVM is installed and used.

The layout of such a distribution is as follows:

enso-1.0.0
├── manifest.yaml       # A manifest file defining metadata about this Enso version.
├── component           # Contains all the JAR modules of the dependencies.
│   ├── runner          # Nested directory to "hide" the runner JAR from the JVM's module-path.
│   │   └── runner.jar  # A Fat JAR containing almost all the dependencies of the engine runner.
│   ├── runtime.jar     # The Enso runtime's module 'org.enso.runtime'. CLI entry point.
│   ├── *.jar           # Other JAR modules that are essential for running Enso.
├── native-libraries    # Contains all shared libraries that are used by JVM components.
│   └── parser.so       # The language parser. It is loaded by the runtime component.
│                       # Alternative extensions are .dll Windows and .dylib on Mac.
└── lib          # Contains all the libraries that are pre-installed within that compiler version.
    └── Standard
        ├── Http
        │   └── 0.1.0     # Every version sub-directory is just an Enso package containing the library.
        │       ├── package.yaml
        │       ├── polyglot
        │       └── src
        │           ├── Http.enso
        │           └── Socket.enso
        └── Base
            └── 0.1.0
                ├── package.yaml
                └── src
                    ├── List.enso
                    ├── Number.enso
                    └── Text.enso

Implementation Note: This structure makes use of deep nesting, which may give some with knowledge of Windows' path-name limits pause (windows paths are historically limited to 256 characters). However, there is no special action required to handle this limit as long as we are building on top of the JVM. The JVM automatically inserts the \\?\ prefix required to bypass the windows path length limit.

Standard Library

The standard library is a set of libraries shipped with the compiler. Whether a given package belongs to standard library can be a bit of an arbitrary choice, but the following are some guidelines:

1. Fundamental packages – basic collections and utilities should be a part of standard library.
2. Packages relying on the compiler internals (e.g. the internal object representation). An example of such a package would be Generic, exposing reflective access to Enso objects.
3. Packages that the compiler relies on, e.g. compile error definitions, stack traces etc.

Enso Home Layout

The location called in some places <ENSO_HOME> is the place where user's projects and similar files are stored. Currently it is specified to always be $HOME/enso.

It has the following structure:

<ENSO_HOME>
├── projects             # Contains all user projects.
├── libraries            # Contains all local libraries that can be edited by the user.
│   └── Prefix1          # Contains libraries with the given prefix.
│       └── Library_Name # Contains a package of a local library.
└── editions             # Contains custom, user-defined editions that can be used as a base for project configurations.