2020-07-08 16:54:41 +03:00
|
|
|
---
|
|
|
|
layout: developer-doc
|
|
|
|
title: Enso Launcher CLI
|
|
|
|
category: distribution
|
|
|
|
tags: [distribution, launcher, cli, command]
|
|
|
|
order: 5
|
|
|
|
---
|
|
|
|
|
|
|
|
# Enso Launcher CLI
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
This document describes available command-line options of the Enso launcher.
|
|
|
|
|
|
|
|
> The actionables for this document are:
|
|
|
|
>
|
|
|
|
> - This document is a draft. The explanations are just to give an idea of the
|
|
|
|
> commands. It will be updated with detailed explanations when the CLI is
|
|
|
|
> developed.
|
|
|
|
|
|
|
|
<!-- MarkdownTOC levels="2,3" autolink="true" -->
|
|
|
|
|
|
|
|
- [Commands](#commands)
|
2020-07-31 08:31:12 +03:00
|
|
|
- [`new`](#new)
|
|
|
|
- [`install engine`](#install-engine)
|
|
|
|
- [`uninstall engine`](#uninstall-engine)
|
|
|
|
- [`install distribution`](#install-distribution)
|
|
|
|
- [`uninstall distribution`](#uninstall-distribution)
|
|
|
|
- [`list`](#list)
|
|
|
|
- [`default`](#default)
|
|
|
|
- [`config`](#config)
|
|
|
|
- [`run`](#run)
|
|
|
|
- [`repl`](#repl)
|
|
|
|
- [`language-server`](#language-server)
|
|
|
|
- [`upgrade`](#upgrade)
|
|
|
|
- [`version`](#version)
|
|
|
|
- [`help`](#help)
|
2020-07-08 16:54:41 +03:00
|
|
|
- [General Options](#general-options)
|
2020-09-03 13:44:21 +03:00
|
|
|
- [`--use-enso-version`](#--use-enso-version)
|
2020-07-31 08:31:12 +03:00
|
|
|
- [`--use-system-jvm`](#--use-system-jvm)
|
2020-09-03 13:44:21 +03:00
|
|
|
- [`--auto-confirm`](#--auto-confirm)
|
|
|
|
- [`--hide-progress`](#--hide-progress)
|
|
|
|
- [`--ensure-portable`](#--ensure-portable)
|
|
|
|
- [Options From Newer Versions](#options-from-newer-versions)
|
2020-07-21 11:14:26 +03:00
|
|
|
- [JVM Options](#jvm-options)
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
|
|
|
|
## Commands
|
|
|
|
|
|
|
|
### `new`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
|
|
|
Create a new, empty project in a specified directory. By default uses the
|
2020-09-01 14:23:27 +03:00
|
|
|
`default` enso version, which can be overriden with `--use-enso-version`.
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso new project1 --path /somewhere/on/the/filesystem
|
2020-09-01 14:23:27 +03:00
|
|
|
# creates project called Project1 in the specified directory
|
2020-07-08 16:54:41 +03:00
|
|
|
# using the `default` Enso version
|
2020-09-01 14:23:27 +03:00
|
|
|
> enso new project2 --use-enso-version 2.0.1
|
2020-07-08 16:54:41 +03:00
|
|
|
# creates the project in the current directory, using the 2.0.1 version
|
|
|
|
```
|
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
### `install engine`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
Installs a specific version of the Enso engine.
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
2020-07-21 11:14:26 +03:00
|
|
|
> enso install engine 2.0.1
|
2020-07-08 16:54:41 +03:00
|
|
|
```
|
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
### `uninstall engine`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
Uninstalls a specific version of the Enso engine.
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
2020-07-21 11:14:26 +03:00
|
|
|
> enso uninstall engine 2.0.1
|
|
|
|
```
|
|
|
|
|
|
|
|
### `install distribution`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
Installs a portable Enso distribution into system-defined directories, as
|
|
|
|
explained in
|
|
|
|
[Installed Enso Distribution Layout](./distribution.md#installed-enso-distribution-layout).
|
2020-07-21 15:59:40 +03:00
|
|
|
By default, it asks the user for confirmation, but this can be skipped by adding
|
2020-09-01 14:23:27 +03:00
|
|
|
the `--auto-confirm` flag.
|
2020-07-21 11:14:26 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
```
|
|
|
|
> extraction-location/bin/enso install distribution
|
|
|
|
This will install Enso to ~/.local/share/enso/.
|
|
|
|
Configuration will be placed in ~/.config/enso/.
|
|
|
|
The universal `enso` launcher will be placed in ~/.local/bin/.
|
|
|
|
Do you want to continue? [Y/n]
|
|
|
|
```
|
|
|
|
|
|
|
|
### `uninstall distribution`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
Uninstalls an installed Enso distribution from the installation location
|
|
|
|
described in
|
|
|
|
[Installed Enso Distribution Layout](./distribution.md#installed-enso-distribution-layout).
|
|
|
|
It removes the universal launcher and all components. By default, it asks the
|
2020-09-01 14:23:27 +03:00
|
|
|
user for confirmation, but this can be skipped by adding a `--auto-confirm`
|
|
|
|
flag.
|
2020-07-21 11:14:26 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
```
|
|
|
|
> enso uninstall distribution
|
|
|
|
This will completely uninstall Enso from ~/.local/share/enso/,
|
|
|
|
remove configuration from ~/.config/enso/
|
|
|
|
and the launcher script from ~/.local/bin/.
|
|
|
|
Do you want to continue? [y/N]
|
2020-07-08 16:54:41 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
### `list`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Lists all installed versions of Enso and managed GraalVM distributions.
|
|
|
|
|
|
|
|
Optional arguments are `enso` to just list Enso installations or `runtime` to
|
|
|
|
list the installed runtimes.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso list
|
|
|
|
Enso 2.0.1 -> GraalVM 20.1.0-java11
|
|
|
|
Enso 2.2.3 -> GraalVM 20.1.0-java11
|
|
|
|
Enso 3.0.0 -> GraalVM 21.1.0-java14
|
|
|
|
> enso list enso
|
|
|
|
2.0.1
|
|
|
|
2.2.3
|
|
|
|
3.0.0
|
|
|
|
> enso list runtime
|
|
|
|
GraalVM 20.1.0-java11 (used by 2 Enso installations)
|
|
|
|
GraalVM 21.1.0-java14 (used by 1 Enso installation)
|
|
|
|
```
|
|
|
|
|
|
|
|
### `default`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Sets the default Enso version used outside of projects.
|
|
|
|
|
|
|
|
If run without arguments, displays currently configured `default` version.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso default 2.0.1
|
2020-07-21 15:59:40 +03:00
|
|
|
default set to version 2.0.1
|
2020-07-08 16:54:41 +03:00
|
|
|
> enso default
|
|
|
|
default version is 2.0.1
|
|
|
|
```
|
|
|
|
|
|
|
|
### `config`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-09-01 14:23:27 +03:00
|
|
|
Can be used to manage global user configuration.
|
2020-07-08 16:54:41 +03:00
|
|
|
|
2020-09-01 14:23:27 +03:00
|
|
|
If only the config path is provided, currently configured value is printed. If
|
|
|
|
the provided value is an empty string, the given key is removed from the config.
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
2020-09-01 14:23:27 +03:00
|
|
|
> enso config author.name Example User # Sets `author.name`.
|
|
|
|
> enso config author.email # Prints current value.
|
|
|
|
user@example.com
|
|
|
|
> enso config author.name "" # Removes the value from the config.
|
2020-07-21 15:59:40 +03:00
|
|
|
```
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
### `run`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Runs a project or an Enso script file.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso run script.enso # runs the file in script mode
|
|
|
|
> enso run path/to/project1 # runs the project
|
|
|
|
> enso run # runs the current project based on current directory
|
2020-07-21 15:59:40 +03:00
|
|
|
```
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
### `repl`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Launches an Enso REPL. If outside a project, it uses the `default` Enso version.
|
|
|
|
If run inside a project or an optional project path is specified, the REPL is
|
|
|
|
run in the context of that project, using the version specified in its
|
|
|
|
configuration.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso repl # version and context depend on current working directory
|
|
|
|
> enso repl /path/to/project # runs the REPL in context of the specified project
|
2020-07-21 15:59:40 +03:00
|
|
|
```
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
### `language-server`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Launches the language server for a given project.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
2020-07-22 20:28:03 +03:00
|
|
|
> enso language-server \
|
2020-07-08 16:54:41 +03:00
|
|
|
--root-id 3256d10d-45be-45b1-9ea4-7912ef4226b1 \
|
|
|
|
--path /tmp/content-root
|
|
|
|
```
|
|
|
|
|
|
|
|
### `upgrade`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Checks for updates of the launcher and downloads any new versions.
|
|
|
|
|
|
|
|
Examples:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso upgrade
|
2020-09-09 16:37:26 +03:00
|
|
|
...
|
|
|
|
[info] Successfully upgraded launcher to 3.0.2.
|
2020-07-08 16:54:41 +03:00
|
|
|
> enso upgrade 2.0.1
|
2020-09-09 16:37:26 +03:00
|
|
|
...
|
|
|
|
[info] Successfully upgraded launcher to 2.0.1.
|
2020-07-21 15:59:40 +03:00
|
|
|
```
|
2020-07-08 16:54:41 +03:00
|
|
|
|
|
|
|
### `version`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Prints the version of the installed launcher as well as the full version string
|
|
|
|
of the currently selected Enso distribution.
|
|
|
|
|
2020-09-03 13:44:21 +03:00
|
|
|
Flag `--json` can be added to get the output in JSON format, instead of the
|
|
|
|
human-readable format that is the default.
|
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
```bash
|
|
|
|
> enso version
|
2020-07-10 13:57:42 +03:00
|
|
|
Enso Launcher
|
2020-09-09 16:37:26 +03:00
|
|
|
Version: 0.1.0
|
|
|
|
Built with: scala-2.13.3 for GraalVM 20.2.0
|
|
|
|
Built from: wip/rw/launcher-self-update* @ c76f7fe6a9e9f37cd8a296c615b7515d1b896d73
|
|
|
|
Built on: Linux (amd64)
|
|
|
|
Current default Enso engine:
|
2020-07-08 16:54:41 +03:00
|
|
|
Enso Compiler and Runtime
|
2020-09-09 16:37:26 +03:00
|
|
|
Version: 0.1.1-rc5
|
2020-07-08 16:54:41 +03:00
|
|
|
Built with: scala-2.13.3 for GraalVM 20.1.0
|
2020-09-09 16:37:26 +03:00
|
|
|
Built from: enso-0.1.1-rc5 @ 391eca6de06b0c642cf7868db62209a9af3d241d
|
2020-07-08 16:54:41 +03:00
|
|
|
Running on: OpenJDK 64-Bit Server VM, GraalVM Community, JDK 11.0.7+10-jvmci-20.1-b02
|
2020-09-09 16:37:26 +03:00
|
|
|
Linux 4.15.0-112-generic (amd64)
|
2020-07-08 16:54:41 +03:00
|
|
|
```
|
|
|
|
|
2020-07-10 13:57:42 +03:00
|
|
|
Besides `enso version`, `enso --version` is also supported and yields the same
|
|
|
|
result.
|
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
### `help`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Print this summary of available command and their usage.
|
|
|
|
|
|
|
|
## General Options
|
|
|
|
|
2020-09-01 14:23:27 +03:00
|
|
|
### `--use-enso-version`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Overrides the inferred (project local or `default`) version when running a
|
|
|
|
command.
|
|
|
|
|
|
|
|
### `--use-system-jvm`
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-08 16:54:41 +03:00
|
|
|
Tells the launcher to use the default JVM (based on `JAVA_HOME`) instead of the
|
|
|
|
managed one. Will not work if the set-up JVM version is not GraalVM.
|
2020-07-21 11:14:26 +03:00
|
|
|
|
2020-09-03 13:44:21 +03:00
|
|
|
### `--auto-confirm`
|
|
|
|
|
|
|
|
Tells the launcher to not ask questions, but proceed with defaults. Useful for
|
|
|
|
automation.
|
|
|
|
|
|
|
|
### `--hide-progress`
|
|
|
|
|
|
|
|
Suppresses displaying progress bars for downloads and other long running
|
|
|
|
actions. May be needed if program output is piped.
|
|
|
|
|
|
|
|
### `--ensure-portable`
|
|
|
|
|
|
|
|
Checks if the launcher is run in portable mode and if it is not, terminates the
|
|
|
|
application.
|
|
|
|
|
2020-08-19 15:24:31 +03:00
|
|
|
## Options From Newer Versions
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
For commands that launch an Enso component inside a JVM (`repl`, `run` and
|
2020-07-22 20:28:03 +03:00
|
|
|
`language-server`), parameters that the launcher does not know about (for
|
|
|
|
example introduced in versions of Enso newer than the launcher knows about) may
|
|
|
|
be passed after a double dash (`--`), i.e. `enso repl -- --someUnknownFlag`.
|
2020-07-21 11:14:26 +03:00
|
|
|
|
2020-08-19 15:24:31 +03:00
|
|
|
## JVM Options
|
|
|
|
|
|
|
|
If an environment variable `ENSO_JVM_OPTS` is defined, JVM options defined there
|
|
|
|
are passed to the launcher JVM.
|
|
|
|
|
|
|
|
> Note: Currently the `ENSO_JVM_OPTS` are parsed by splitting on the space
|
|
|
|
> character, so individual options listed in this environment variable should
|
|
|
|
> not contain spaces or they may be interpreted incorrectly.
|
|
|
|
|
2020-07-22 20:28:03 +03:00
|
|
|
Moreover, it is possible to pass parameters to the JVM that is used to launch
|
|
|
|
these components, which may be helpful with debugging. A parameter of the form
|
|
|
|
`--jvm.argumentName=argumentValue` will be passed to the JVM as
|
|
|
|
`-DargumentName=argumentValue`.
|