2020-05-15 13:41:26 +03:00
|
|
|
---
|
|
|
|
layout: developer-doc
|
|
|
|
title: Contributing to Enso
|
|
|
|
category: summary
|
|
|
|
tags: [summary, contributing]
|
|
|
|
order: 2
|
|
|
|
---
|
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
# Contributing to Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
Thank you for your interest in contributing to Enso! We believe that only
|
|
|
|
through community involvement can Enso be the best it can be! There are a whole
|
|
|
|
host of ways to contribute, and every single one is appreciated. The major
|
|
|
|
sections of this document are linked below:
|
|
|
|
|
2020-06-29 20:24:41 +03:00
|
|
|
<!-- MarkdownTOC levels="2,3" autolink="true" -->
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-03-06 15:02:19 +03:00
|
|
|
- [The Contributor License Agreement](#the-contributor-license-agreement)
|
2019-06-11 19:07:54 +03:00
|
|
|
- [Issues](#issues)
|
|
|
|
- [Feature Enhancements](#feature-enhancements)
|
|
|
|
- [Bug Reports](#bug-reports)
|
|
|
|
- [Hacking on Enso](#hacking-on-enso)
|
2020-06-29 20:24:41 +03:00
|
|
|
- [Design Documentation](#design-documentation)
|
|
|
|
- [System Requirements](#system-requirements)
|
|
|
|
- [Getting the Sources](#getting-the-sources)
|
2020-07-21 15:59:40 +03:00
|
|
|
- [Getting Set Up \(Rust\)](#getting-set-up-rust)
|
|
|
|
- [Getting Set Up \(JVM\)](#getting-set-up-jvm)
|
|
|
|
- [Getting Set Up \(Documentation\)](#getting-set-up-documentation)
|
2020-06-29 20:24:41 +03:00
|
|
|
- [Building Enso](#building-enso)
|
|
|
|
- [Running Enso](#running-enso)
|
2019-06-11 19:07:54 +03:00
|
|
|
- [Pull Requests](#pull-requests)
|
|
|
|
- [Documentation](#documentation)
|
|
|
|
- [Issue Triage](#issue-triage)
|
|
|
|
- [Out-of-Tree Contributions](#out-of-tree-contributions)
|
|
|
|
- [Helpful Documentation and Links](#helpful-documentation-and-links)
|
|
|
|
|
|
|
|
<!-- /MarkdownTOC -->
|
|
|
|
|
2020-03-06 15:02:19 +03:00
|
|
|
All contributions to Enso should be in keeping with our
|
2020-05-20 14:21:52 +03:00
|
|
|
[Code of Conduct](./CODE_OF_CONDUCT.md).
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-03-06 15:02:19 +03:00
|
|
|
## The Contributor License Agreement
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-03-06 15:02:19 +03:00
|
|
|
As part of your first contribution to this repository, you need to accept the
|
|
|
|
Contributor License Agreement. You will automatically be asked to sign the CLA
|
|
|
|
when you make your first pull request.
|
|
|
|
|
|
|
|
Any work intentionally submitted for inclusion in Enso shall be licensed under
|
|
|
|
this CLA.
|
|
|
|
|
|
|
|
The CLA you sign applies to all repositories associated with the Enso project,
|
|
|
|
so you will only have to sign it once at the start of your contributions.
|
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
## Issues
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-05-20 14:21:52 +03:00
|
|
|
If you're wanting to get involved with Enso's development and are looking for
|
|
|
|
somewhere to start, you can check out the following tags in our issues:
|
|
|
|
|
2020-06-24 14:05:31 +03:00
|
|
|
- [Good First Issue](https://github.com/enso-org/enso/labels/Status%3A%20Good%20First%20Issue)
|
|
|
|
- [Help Wanted](https://github.com/enso-org/enso/labels/Status%3A%20Help%20Wanted)
|
2020-05-20 14:21:52 +03:00
|
|
|
|
|
|
|
You can use the "Size" and "Difficulty" labels that should be assigned to every
|
|
|
|
issue to get a better idea of how much work a given issue might be.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Feature Enhancements
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
If you feel like you have a suggestion for a change to the way that Enso works
|
2020-07-21 15:59:40 +03:00
|
|
|
as a language, please take a look at the [Enso RFC process](./rfcs/README.md) to
|
|
|
|
learn how to file an RFC for the project.
|
2020-05-20 14:21:52 +03:00
|
|
|
|
|
|
|
In essence, the RFC process provides a way to propose major changes to the
|
2020-07-21 15:59:40 +03:00
|
|
|
language, the compiler, and the runtime in a way that ensures that they get seen
|
|
|
|
and discussed by all the major stakeholders involved.
|
2020-05-20 14:21:52 +03:00
|
|
|
|
|
|
|
If, on the other hand, you're asking for a smaller feature, please feel free to
|
2020-07-21 15:59:40 +03:00
|
|
|
submit a
|
|
|
|
[feature request](https://github.com/enso-org/enso/issues/new?assignees=&labels=Type%3A+Enhancement&template=feature-request.md&title=)
|
2020-05-20 14:21:52 +03:00
|
|
|
to the repository.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Bug Reports
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
While it's never great to find a bug, they are a reality of software and
|
|
|
|
software development! We can't fix or improve on the things that we don't know
|
|
|
|
about, so report as many bugs as you can! If you're not sure whether something
|
|
|
|
is a bug, file it anyway!
|
|
|
|
|
|
|
|
**If you are concerned that your bug publicly presents a security risk to the
|
2020-05-20 14:21:52 +03:00
|
|
|
users of Enso, please look at our [security guidelines](./SECURITY.md).**
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
Even though GitHub search can be a bit hard to use sometimes, we'd appreciate if
|
|
|
|
you could
|
2020-07-21 15:59:40 +03:00
|
|
|
[search](https://github.com/enso-org/enso/search?q=&type=Issues&utf8=%E2%9C%93)
|
|
|
|
for your issue before filing a bug as it's possible that someone else has
|
|
|
|
already reported the issue. We know the search isn't the best, and it can be
|
|
|
|
hard to know what to search for, so we really don't mind if you do submit a
|
|
|
|
duplicate!
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-05-20 14:21:52 +03:00
|
|
|
Opening an issue is as easy as following
|
2020-06-24 14:05:31 +03:00
|
|
|
[this link](https://github.com/enso-org/enso/issues/new?template=bug-report.md)
|
2019-06-11 19:07:54 +03:00
|
|
|
and filling out the fields. The template is intended to collect all the
|
|
|
|
information we need to best diagnose the issue, so please take the time to fill
|
|
|
|
it out accurately.
|
|
|
|
|
|
|
|
The reproduction steps are particularly important, as the more easily we can
|
|
|
|
reproduce it, the faster we can fix the bug! It's also helpful to have the
|
|
|
|
output of `enso --version`, as that will let us know if the bug is Operating
|
|
|
|
System or Architecture specific.
|
|
|
|
|
|
|
|
## Hacking on Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
This will get you up and running for Enso development, with only a minimal
|
|
|
|
amount of setup required. Enso's build system is fairly simple, allowing you to
|
2020-06-08 13:03:39 +03:00
|
|
|
bootstrap the compiler as long as you have a minimal set of tools.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
### Design Documentation
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
If you're going to start contributing to Enso, it is often a good idea to take a
|
|
|
|
look at the design documentation for the language. These files explain provide
|
|
|
|
both a rigorous specification of Enso's design, but also insight into the _why_
|
|
|
|
behind the decisions that have been made.
|
|
|
|
|
2020-06-01 15:03:30 +03:00
|
|
|
These can be found in [`docs/`](README.md), and are organised by the part of the
|
|
|
|
compiler that they relate to.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
### System Requirements
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-08-10 13:14:39 +03:00
|
|
|
The following operating systems are supported for developing Enso:
|
|
|
|
|
|
|
|
- Windows 10
|
|
|
|
- macOS 10.14 and above
|
|
|
|
- Linux 4.4 and above
|
|
|
|
|
|
|
|
Currently only the x86_64 (amd64) architecture is supported. You may be able to
|
|
|
|
develop Enso on other systems, but issues arising from unsupported
|
|
|
|
configurations will not be fixed by the core team.
|
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
In order to build and run Enso you will need the following tools:
|
|
|
|
|
2020-06-01 15:03:30 +03:00
|
|
|
- [sbt](https://www.scala-sbt.org/) with the same version as specified in
|
|
|
|
[`project/build.properties`](../project/build.properties).
|
2020-07-01 14:21:13 +03:00
|
|
|
- [GraalVM](https://www.graalvm.org/) with the same version as described in the
|
|
|
|
[`build.sbt`](../build.sbt) file, configured as your default JVM. GraalVM is
|
|
|
|
distributed for different Java versions, so you need a GraalVM distribution
|
|
|
|
for the same Java version as specified in [`build.sbt`](../build.sbt).
|
2020-04-17 17:00:29 +03:00
|
|
|
- [Flatbuffers Compiler](https://google.github.io/flatbuffers) with version
|
2020-04-17 16:47:58 +03:00
|
|
|
1.12.0.
|
2020-06-29 20:24:41 +03:00
|
|
|
- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html),
|
|
|
|
the rust build tool.
|
|
|
|
- [Rustup](https://rustup.rs), the rust toolchain management utility.
|
2020-08-10 13:14:39 +03:00
|
|
|
- On MacOS and Linux, the `tar` command is required for running some tests. It
|
|
|
|
should be installed by default on most distributions.
|
2020-08-28 14:03:09 +03:00
|
|
|
- If you want to be able to build the Launcher Native Image, you will need a
|
|
|
|
native C compiler for your platform as described in the
|
|
|
|
[Native Image Prerequisites](https://www.graalvm.org/reference-manual/native-image/#prerequisites).
|
|
|
|
On Linux that will be `gcc`, on macOS you may need `xcode` and on Windows you
|
|
|
|
need to configure the Developer Command Prompt for Microsoft Visual C++ for
|
|
|
|
the x64 architecture.
|
2020-04-06 19:13:19 +03:00
|
|
|
|
|
|
|
Managing multiple JVM installations can be a pain, so some of the team use
|
2020-04-17 17:00:29 +03:00
|
|
|
[Jenv](http://www.jenv.be/): A useful tool for managing multiple JVMs.
|
2020-04-17 16:47:58 +03:00
|
|
|
|
2020-04-17 17:00:29 +03:00
|
|
|
The flatbuffers `flatc` compiler can be installed from the following locations:
|
2020-04-17 16:47:58 +03:00
|
|
|
|
2020-04-17 17:00:29 +03:00
|
|
|
- Using the `conda` package manager (`conda install flatbuffers`). This will
|
|
|
|
work on all platforms, but requires some knowledge of `conda` and how its
|
|
|
|
environments work.
|
|
|
|
- Windows users can download binaries directly from the flatbuffers github
|
|
|
|
[releases](https://github.com/google/flatbuffers/releases).
|
|
|
|
- MacOS users can install it via homebrew (`brew install flatbuffers`).
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
### Getting the Sources
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
Given you've probably been reading this document on GitHub, you might have an
|
2020-03-06 15:02:19 +03:00
|
|
|
inkling where to look!. You can clone Enso using two methods:
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
- **Via HTTPS:** We recommend you only use HTTPS if checking out the sources as
|
|
|
|
read-only.
|
|
|
|
|
|
|
|
```
|
2020-06-24 14:05:31 +03:00
|
|
|
git clone https://github.com/enso-org/enso.git
|
2019-06-11 19:07:54 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
- **Via SSH:** For those who plan on regularly making direct commits, cloning
|
|
|
|
over SSH may provide a better user experience (but requires setting up your
|
|
|
|
SSH Keys with GitHub).
|
|
|
|
|
|
|
|
```
|
2020-06-24 14:05:31 +03:00
|
|
|
git clone git@github.com:enso-org/enso.git
|
2019-06-11 19:07:54 +03:00
|
|
|
```
|
|
|
|
|
2020-06-29 20:24:41 +03:00
|
|
|
### Getting Set Up (Rust)
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-08-10 13:14:39 +03:00
|
|
|
The SBT project requires a specific nightly rust toolchain. To get it set up,
|
|
|
|
you will need to install [rustup](https://rustup.rs/) and then run the following
|
2020-08-03 17:00:12 +03:00
|
|
|
commands:
|
2020-06-29 20:24:41 +03:00
|
|
|
|
|
|
|
```bash
|
|
|
|
rustup toolchain install nightly-2019-11-04
|
|
|
|
rustup override set nightly-2019-11-04
|
|
|
|
rustup component add clippy
|
|
|
|
```
|
|
|
|
|
2020-07-03 16:42:45 +03:00
|
|
|
You will also need `node` in order to run the `wasm` tests. We only support the
|
|
|
|
latest LTS version of [NodeJS](https://nodejs.org/en/download) and NPM. We
|
|
|
|
recommend using [`nvm`](https://github.com/nvm-sh/nvm) to manage node versions.
|
|
|
|
The current LTS is `v12.18.0`.
|
|
|
|
|
2020-07-01 14:21:13 +03:00
|
|
|
### Getting Set Up (JVM)
|
2020-07-21 15:59:40 +03:00
|
|
|
|
|
|
|
In order to properly build the `runtime` component, the JVM running SBT needs to
|
|
|
|
have some dependency JARs available in its module path at startup. To ensure
|
2020-07-01 14:21:13 +03:00
|
|
|
they are available, before running any compilation or other tasks, these
|
|
|
|
dependencies should be prepared. To do so, run the following command in the
|
|
|
|
repository root directory:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
sbt bootstrap
|
|
|
|
```
|
|
|
|
|
|
|
|
It is preferred to not run this command from the sbt shell, but in batch mode,
|
|
|
|
because SBT has to be launched again anyway to pick up these JARs at startup.
|
|
|
|
|
|
|
|
Bootstrap has to be run only when building the project for the first time
|
|
|
|
**and** after each change of Graal version.
|
|
|
|
|
2020-07-21 15:59:40 +03:00
|
|
|
### Getting Set Up (Documentation)
|
|
|
|
|
|
|
|
We enforce automated formatting of all of our documentation and configuration
|
|
|
|
using the fairly common [prettier](https://prettier.io) automatic formatter. You
|
|
|
|
can install prettier for our project by running the following command:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
npm install
|
|
|
|
```
|
|
|
|
|
|
|
|
This does, however, mean that you have to have node installed on your system.
|
|
|
|
Please follow the guidelines [above](#getting-set-up-rust) to install node if
|
|
|
|
you have not already done so.
|
|
|
|
|
|
|
|
The version if prettier is forced by our
|
|
|
|
[`package-lock.json`](../package-lock.json) in order for us to make formatting
|
|
|
|
bumps all at once.
|
|
|
|
|
|
|
|
You can format all of our documentation and configuration as follows:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
npx prettier --write <dir>
|
|
|
|
```
|
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
### Building Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
There are multiple projects in this repository, but all can be built, run and
|
|
|
|
tested using `sbt`. As long as your configuration is correct, with the correct
|
2020-08-03 17:00:12 +03:00
|
|
|
versions of SBT, Rust and GraalVM, the same steps can be followed on all of our
|
2019-10-30 12:58:20 +03:00
|
|
|
supported platforms (Linux, MacOS and Windows).
|
|
|
|
|
|
|
|
SBT will handle downloading and building library dependencies as needed, meaning
|
|
|
|
that you don't need to handle any of this manually.
|
|
|
|
|
|
|
|
**Please note** that at the current time, the Windows build of GraalVM is in an
|
|
|
|
experimental state. This means that while it may function, we are not intending
|
|
|
|
to provide work-arounds for building on that platform while it is still in an
|
|
|
|
unstable state.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
#### Building Enso Components
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-12-19 13:57:41 +03:00
|
|
|
In order to build a specific component (e.g. `runtime`), please follow the
|
2019-10-30 12:58:20 +03:00
|
|
|
following steps.
|
|
|
|
|
|
|
|
1. Enter the sbt shell in the repository root directory by typing `sbt`.
|
2019-12-19 13:57:41 +03:00
|
|
|
2. Change to the project you are concerned with (in our case `runtime`) by
|
|
|
|
executing `project runtime`.
|
2019-10-30 12:58:20 +03:00
|
|
|
3. Execute `compile` in order to compile the project in question. This will
|
|
|
|
compile the project and all its dependencies as necessary.
|
|
|
|
|
|
|
|
You can substitute both `bench` and `test` for `compile` in step 3, and the sbt
|
|
|
|
shell will execute the appropriate thing. Furthermore we have `testOnly` and
|
|
|
|
`benchOnly` that accept a glob pattern that delineates some subset of the tests
|
|
|
|
or benchmarks to run (e.g. `testOnly *FunctionArguments*`).
|
|
|
|
|
2019-11-05 17:12:33 +03:00
|
|
|
#### Building the Interpreter CLI Fat Jar
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-11-05 17:12:33 +03:00
|
|
|
In order to build a fat jar with the CLI component, run the `assembly` task
|
2020-04-08 18:02:22 +03:00
|
|
|
inside the `runner` subproject:
|
2020-03-17 13:06:47 +03:00
|
|
|
|
|
|
|
```bash
|
2020-04-08 18:02:22 +03:00
|
|
|
sbt "runner/assembly"
|
2019-11-05 17:12:33 +03:00
|
|
|
```
|
2020-03-17 13:06:47 +03:00
|
|
|
|
2020-07-21 11:14:26 +03:00
|
|
|
This will produce an executable `runner.jar` fat jar and a `runtime.jar` fat jar
|
|
|
|
in the repository root. The `runner.jar` depends only on the `runtime.jar` and a
|
|
|
|
vanilla GraalVM distribution. To run it, use:
|
2020-03-17 13:06:47 +03:00
|
|
|
|
|
|
|
```bash
|
2020-07-21 11:14:26 +03:00
|
|
|
JAVA_HOME=<PATH_TO_GRAAL_HOME> ./runner.jar <CLI_ARGS>
|
2019-11-05 17:12:33 +03:00
|
|
|
```
|
2020-03-17 13:06:47 +03:00
|
|
|
|
2020-07-10 13:57:42 +03:00
|
|
|
#### Building the Launcher Native Binary
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-10 13:57:42 +03:00
|
|
|
If you want to build the native launcher binary, you need to ensure that the
|
|
|
|
Native Image component is installed in your GraalVM distribution. To install it,
|
|
|
|
run:
|
|
|
|
|
|
|
|
```bash
|
2020-08-28 14:03:09 +03:00
|
|
|
<path-to-graal-home>/bin/gu install native-image
|
2020-07-10 13:57:42 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
Then, you can build the launcher using:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
sbt launcher/buildNativeImage
|
|
|
|
```
|
|
|
|
|
2020-07-03 16:42:45 +03:00
|
|
|
#### Testing Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-07-03 16:42:45 +03:00
|
|
|
Running the tests for the JVM enso components is as simple as running
|
|
|
|
`sbt / test`. To test the Rust components you can run `cargo test`. Finally, you
|
|
|
|
can run the WASM tests for the rust components by using `./run --test-wasm`.
|
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
#### Passing Debug Options
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
GraalVM provides some useful debugging options, including the ability to output
|
|
|
|
the compilation graph during JIT optimisation, and the ASM generated by the JIT.
|
|
|
|
|
|
|
|
However, as we don't want these things polluting our standard builds, we provide
|
|
|
|
a helper SBT command `withDebug` to allow for passing these options. It supports
|
|
|
|
the following flags:
|
|
|
|
|
|
|
|
- `--dumpGraphs`: This dumps the IGV (a Graal tool) graphs for the program to
|
|
|
|
allow for manual analysis and discovery of optimisation failures.
|
|
|
|
- `--showCompilations`: Prints the truffle compilation trace information.
|
|
|
|
- `--printAssembly`: Prints the assembly output from the HotSpot JIT tier.
|
|
|
|
|
|
|
|
For more information on this sbt command, please see
|
2020-06-01 15:03:30 +03:00
|
|
|
[WithDebugCommand.scala](../project/WithDebugCommand.scala).
|
2019-10-30 12:58:20 +03:00
|
|
|
|
|
|
|
It is used as an addendum to the basic sbt command you want to run (e.g. `test`
|
|
|
|
from above). The format is `withDebug COMMAND [OPTIONS...]`, and if you need to
|
|
|
|
pass any additional options to `COMMAND` you must do so following a `--`. For
|
|
|
|
example:
|
|
|
|
|
|
|
|
```
|
|
|
|
withDebug run --dumpGraphs --printAssembly -- --run MyFile.enso
|
|
|
|
withDebug benchOnly --showCompilations -- RecursionBenchmark
|
|
|
|
```
|
|
|
|
|
2020-03-06 16:47:17 +03:00
|
|
|
#### Working with Assembly
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-03-06 16:47:17 +03:00
|
|
|
In order to examine the assembly generated by GraalVM and HotSpot you need to
|
|
|
|
provide your JVM install with a dynamic library that supports the dumping of
|
2020-03-24 22:48:53 +03:00
|
|
|
assembly. It can be acquired for MacOS and Linux
|
2020-03-06 16:47:17 +03:00
|
|
|
[here](https://github.com/liuzhengyang/hsdis/), and for windows from
|
|
|
|
[here](http://fcml-lib.com/). There are other methods to acquire it, as well, so
|
|
|
|
please choose one best suited for you.
|
|
|
|
|
2020-03-24 22:48:53 +03:00
|
|
|
Once you have a copy of the dynamic library, it needs to be placed in
|
2020-07-01 14:21:13 +03:00
|
|
|
`$JVM_HOME/lib/server`.
|
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
#### Native Image
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
Native image is a capability provided alongside GraalVM that allows the
|
|
|
|
generation of native executables from JVM language programs (such as the Enso
|
|
|
|
interpreter itself). However, it results in significantly degraded peak
|
|
|
|
performance, so it is not part of our roadmap currently.
|
|
|
|
|
|
|
|
If you would like to experiment with it, you can execute the `buildNativeImage`
|
2020-07-21 15:59:40 +03:00
|
|
|
command in the sbt shell while inside the `runner` project. Please note that
|
|
|
|
while the command is available at the moment, and you are welcome to
|
2020-06-24 14:05:31 +03:00
|
|
|
[report an issue](https://github.com/enso-org/enso/issues/new?assignees=&labels=Type%3A+Bug&template=bug-report.md&title=)
|
2019-10-30 12:58:20 +03:00
|
|
|
with the functionality, any bugs you report will _not_ be considered high
|
|
|
|
priority.
|
|
|
|
|
|
|
|
**WE CURRENTLY DO NOT SUPPORT THE NATIVE IMAGE BUILD.**
|
|
|
|
|
|
|
|
#### Using IntelliJ
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
Internally, most of the developers working on the Enso project use IntelliJ as
|
|
|
|
their primary IDE. To that end, what follows is a basic set of instructions for
|
|
|
|
getting the project into a working state in IntelliJ.
|
|
|
|
|
|
|
|
1. Clone the project sources.
|
|
|
|
2. Open IntelliJ
|
|
|
|
3. File -> New -> Project From Existing Sources.
|
|
|
|
4. Navigate to the directory into which you cloned the project sources. By
|
|
|
|
default this will be called `enso`. Select the directory, and not the
|
|
|
|
`build.sbt` file it contains.
|
|
|
|
5. In the 'Import Project' dialogue, select 'Import project from external
|
|
|
|
model' and choose 'sbt'.
|
|
|
|
6. Where it says 'Download:', ensure you check both 'Library Sources' and 'sbt
|
|
|
|
sources'.
|
|
|
|
7. In addition, check the boxes next to 'Use sbt shell:' such that it is used
|
|
|
|
both 'for imports' and 'for builds'.
|
|
|
|
8. Disallow the overriding of the sbt version.
|
|
|
|
9. Under the 'Project JDK' setting, please ensure that it is set up to use a
|
2020-07-01 14:21:13 +03:00
|
|
|
GraalVM version as described in [System requirements](#system-requirements).
|
|
|
|
You may need to add it using the 'New' button if it isn't already set up.
|
2019-10-30 12:58:20 +03:00
|
|
|
10. Click 'Finish'. This will prompt you as to whether you want to overwrite the
|
|
|
|
`project` folder. Select 'Yes' to continue. The Enso project will load up
|
|
|
|
with an open SBT shell, which can be interacted with as described above. You
|
|
|
|
will want to use scalafmt for formatting of Scala code, and install Google
|
|
|
|
Java Format for formatting Java code. For more information see the relevant
|
2020-06-01 15:03:30 +03:00
|
|
|
[Style Guides](style-guide/README.md).
|
2019-10-30 12:58:20 +03:00
|
|
|
|
|
|
|
However, as mentioned in the [Troubleshooting](#troubleshooting) section below,
|
|
|
|
the forked nature of execution in the SBT shell means that we can't trivially
|
|
|
|
make use of the IntelliJ debugger. In order to get debugging working, you will
|
|
|
|
need to follow these steps:
|
|
|
|
|
|
|
|
1. Go to Run -> Edit Configurations.
|
2020-07-21 15:59:40 +03:00
|
|
|
2. Click the `+` button in the header of the 'Run/Debug Configurations' dialogue
|
|
|
|
that pops up.
|
2019-10-30 12:58:20 +03:00
|
|
|
3. Select 'Remote' and name the new configuration appropriately.
|
|
|
|
4. In the options for that configuration select 'Listen to remote JVM' under
|
|
|
|
'Debugger mode:'
|
|
|
|
5. Where it provides the command-line arguments for the remote JVM, copy these
|
2019-11-27 14:32:36 +03:00
|
|
|
and add them to `truffleRunOptions` in [`build.sbt`](build.sbt). Remove the
|
|
|
|
portion of these options after `suspend=y`, including the comma. They are
|
|
|
|
placeholders that we don't use.
|
2020-08-05 23:16:44 +03:00
|
|
|
6. Alternatively, certain tasks, such as `run`, `benchOnly` and `testOnly` can
|
|
|
|
be used through the `withDebug` SBT command. For this to work, your remote
|
2020-08-10 13:14:39 +03:00
|
|
|
configuration must specify the host of `localhost` and the port `5005`. The
|
|
|
|
command syntax is `withDebug --debugger TASK_NAME -- TASK_PARAMETERS`, e.g.
|
|
|
|
`withDebug --debugger testOnly -- *AtomConstructors*`.
|
2020-08-05 23:16:44 +03:00
|
|
|
7. Now, when you want to debug something, you can place a breakpoint as usual in
|
2019-10-30 12:58:20 +03:00
|
|
|
IntelliJ, and then execute your remote debugging configuration. Now, in the
|
|
|
|
SBT shell, run a command to execute the code you want to debug (e.g.
|
|
|
|
`testOnly *CurryingTest*`). This will open the standard debugger interface
|
|
|
|
and will allow you to step through your code.
|
|
|
|
|
|
|
|
**Please be careful** to ensure that you don't commit these changes to the sbt
|
|
|
|
configuration as they are specific to your machine.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
#### Troubleshooting
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
If you are having issues building Enso, please check the list below before
|
|
|
|
filing an issue with us.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
- **`StackOverflowError` During Compilation:** Please ensure that your version
|
|
|
|
of sbt is respecting the project's `.jvmopts` settings. We make significant
|
|
|
|
use of recursion when expanding macros for the parser, and these require use
|
|
|
|
of additional stack. Alternatively, you can explicitly pass `-Xss8M` to the
|
|
|
|
`sbt` invocation.
|
|
|
|
- **Debugging Not Working:** The sbt tasks run the invoked programs in a forked
|
|
|
|
JVM. This means that to attach a debugger to it you need to use the JVM remote
|
|
|
|
debugging support. We cannot support all possible configurations for this, but
|
|
|
|
if you use IntelliJ please see the [Using IntelliJ](#using-intellj) section
|
|
|
|
above for instructions.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
If your problem was not listed above, please
|
2020-06-24 14:05:31 +03:00
|
|
|
[file a bug report](https://github.com/enso-org/enso/issues/new?assignees=&labels=Type%3A+Bug&template=bug-report.md&title=)
|
2019-10-30 12:58:20 +03:00
|
|
|
in our issue tracker and we will get back to you as soon as possible.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
### Running Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
The only component in this repository with a proper executable is the Enso
|
2020-07-21 15:59:40 +03:00
|
|
|
interpreter. It can be run using the sbt `run` command in the project `runner`
|
|
|
|
and provides a rudimentary command-line interface to the basic capabilities of
|
|
|
|
the interpreter.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-07-21 15:59:40 +03:00
|
|
|
Detailed information on the flags it supports can be obtained by executing
|
|
|
|
`run --help`, but the primary functionality is as follows:
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2019-10-30 12:58:20 +03:00
|
|
|
- `--new PATH`: Creates a new Enso project at the location spcified by `PATH`.
|
|
|
|
- `--run PATH`: Executes the interpreter on the Enso source specified by `PATH`.
|
|
|
|
In this case, `PATH` must point to either a standalone Enso file or an Enso
|
|
|
|
project.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
#### Language Server Mode
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-03-24 22:48:53 +03:00
|
|
|
The Language Server can be run using the `--server` option. It requires also a
|
|
|
|
content root to be provided (`--root-id` and `--path` options). Command-line
|
|
|
|
interface of the runner prints all server options when you execute it with
|
|
|
|
`--help` option.
|
2020-03-06 17:17:46 +03:00
|
|
|
|
|
|
|
Below are options uses by the Language Server:
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-03-06 17:17:46 +03:00
|
|
|
- `--server`: Runs the Language Server
|
|
|
|
- `--root-id <uuid>`: Content root id.
|
|
|
|
- `--path <path>`: Path to the content root.
|
2020-03-24 22:48:53 +03:00
|
|
|
- `--interface <interface>`: Interface for processing all incoming connections.
|
2020-03-17 13:06:47 +03:00
|
|
|
Default value is 127.0.0.1
|
2020-07-22 20:28:03 +03:00
|
|
|
- `--rpc-port <port>`: RPC port for processing all incoming connections. Default
|
|
|
|
value is 8080.
|
|
|
|
- `--data-port <port>`: Data port for visualisation protocol. Default value
|
|
|
|
is 8081.
|
2020-03-06 17:17:46 +03:00
|
|
|
|
|
|
|
To run the Language Server on 127.0.0.1:8080 type:
|
2020-03-17 13:06:47 +03:00
|
|
|
|
2020-03-06 17:17:46 +03:00
|
|
|
```bash
|
2020-07-21 11:14:26 +03:00
|
|
|
./runner.jar \
|
2020-03-06 17:17:46 +03:00
|
|
|
--server \
|
|
|
|
--root-id 3256d10d-45be-45b1-9ea4-7912ef4226b1 \
|
|
|
|
--path /tmp/content-root
|
|
|
|
```
|
|
|
|
|
2020-03-17 13:06:47 +03:00
|
|
|
If you want to provide a socket that the server should listen to, you must
|
|
|
|
specify the following options:
|
2020-03-06 17:17:46 +03:00
|
|
|
|
2020-03-17 13:06:47 +03:00
|
|
|
- `--interface`: The interface on which the socket will exist (e.g. `0.0.0.0`).
|
|
|
|
- `--port`: The port on `interface` where the socket will be opened (e.g. `80`).
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Pull Requests
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
Pull Requests are the primary method for making changes to Enso. GitHub has
|
|
|
|
[fantastic documentation](https://help.github.com/articles/about-pull-requests/)
|
2020-03-06 15:02:19 +03:00
|
|
|
on using the pull request feature. Enso uses the 'fork-and-pull' model of
|
2019-06-11 19:07:54 +03:00
|
|
|
development. It is as described
|
|
|
|
[here](https://help.github.com/articles/about-collaborative-development-models/)
|
|
|
|
and involves people pushing changes to their own fork and creating pull requests
|
2020-03-06 15:02:19 +03:00
|
|
|
to bring those changes into the main Enso repository.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-06-15 16:25:55 +03:00
|
|
|
Please make all pull requests against the `main` branch.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-03-24 22:48:53 +03:00
|
|
|
- We run CI on all contributions to Enso, but it's still useful for you to run
|
2020-04-06 19:13:19 +03:00
|
|
|
the tests yourself locally first! This can be done by running `test` in the
|
2020-03-24 22:48:53 +03:00
|
|
|
`enso` project in sbt.
|
2020-03-17 13:06:47 +03:00
|
|
|
- Additionally, please ensure that your code conforms to the Enso style guides,
|
2020-06-01 15:03:30 +03:00
|
|
|
particularly the [Scala Style Guide](./style-guide/scala.md) and the
|
|
|
|
[Java Style Guide](./style-guide/java.md).
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
Make sure you perform these checks before _every_ pull request. You can even add
|
|
|
|
[git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) before
|
|
|
|
every push to make sure that you can't forget.
|
|
|
|
|
2020-03-17 13:06:47 +03:00
|
|
|
- Every pull request to the Enso repository is reviewed by a member of the core
|
|
|
|
team! You'll get assigned a reviewer based on the areas your PR touches, but
|
|
|
|
please feel free to ask for a specific person if you've worked with them in a
|
|
|
|
specific area before!
|
|
|
|
- If you have questions, or would like to begin the review process before your
|
2020-07-21 15:59:40 +03:00
|
|
|
PR is 'done', please use the
|
|
|
|
[Draft Pull Requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
|
2020-04-06 19:13:19 +03:00
|
|
|
feature on GitHub. Doing so will allow you to make use of our CI
|
|
|
|
infrastructure as part of your development process.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
Once the reviewer approves your pull request it will be tested by our continuous
|
2020-03-17 13:06:47 +03:00
|
|
|
integration provider before being merged. If we request changes to your PR,
|
|
|
|
please feel free to discuss the suggestions and comments! We can only achieve
|
|
|
|
the best results through open collaboration.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Documentation
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-05-20 14:21:52 +03:00
|
|
|
Documentation improvements are very welcome! For now, the main documentation
|
|
|
|
available is the _developer_ documentation for the language, which can be found
|
|
|
|
at the [dev docs site](https://dev.enso.org). The source for this documentation
|
2020-06-01 15:03:30 +03:00
|
|
|
is found in the [`docs/`](.) folder, and can be altered from there.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
2020-05-20 14:21:52 +03:00
|
|
|
Documentation pull requests will be reviewed in exactly the same way as normal
|
|
|
|
pull requests.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
To find documentation-related issues, sort by the
|
2020-06-24 14:05:31 +03:00
|
|
|
[Category: Documentation](hhttps://github.com/enso-org/enso/labels/Category%3A%20Documentation)
|
2019-06-11 19:07:54 +03:00
|
|
|
label.
|
|
|
|
|
|
|
|
## Issue Triage
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
Sometimes issues can be left open long after the bug has been fixed. Other
|
|
|
|
times, a bug might go stale because something has changed in the meantime.
|
|
|
|
|
|
|
|
It can be helpful to go through older bug reports and make sure that they are
|
|
|
|
still valid. Load up an older issue, double check that it's still true, and
|
|
|
|
leave a comment letting us know if it is or is not. The
|
2020-06-24 14:05:31 +03:00
|
|
|
[least recently updated](https://github.com/enso-org/enso/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc)
|
2019-06-11 19:07:54 +03:00
|
|
|
sort is good for finding issues like this.
|
|
|
|
|
|
|
|
Contributors with sufficient permissions can help by adding labels to help with
|
|
|
|
issue triage.
|
|
|
|
|
|
|
|
If you're looking for somewhere to start, take a look at the
|
2020-06-24 14:05:31 +03:00
|
|
|
[Difficulty: Beginner](https://github.com/enso-org/enso/labels/Difficulty%3A%20Beginner)
|
2019-06-11 19:07:54 +03:00
|
|
|
issue label, as well as the
|
2020-06-24 14:05:31 +03:00
|
|
|
[Status: Help Wanted](https://github.com/enso-org/enso/labels/Status%3A%20Help%20Wanted)
|
2020-05-20 14:21:52 +03:00
|
|
|
and
|
2020-07-21 15:59:40 +03:00
|
|
|
[Status: Good First Issue](https://github.com/enso-org/enso/labels/Status%3A%20Good%20First%20Issue)
|
|
|
|
labels.
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Out-of-Tree Contributions
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2019-06-11 19:07:54 +03:00
|
|
|
As helpful as contributing to Enso directly is, it can also be just as helpful
|
|
|
|
to contribute in other ways outside this repository:
|
|
|
|
|
2020-04-06 19:13:19 +03:00
|
|
|
- Answer questions in the [Discord](https://chat.luna-lang.org) or on
|
2020-06-24 14:05:31 +03:00
|
|
|
[StackOverflow](https://stackoverflow.com/questions/tagged/enso).
|
2019-06-11 19:07:54 +03:00
|
|
|
|
|
|
|
## Helpful Documentation and Links
|
2020-07-21 15:59:40 +03:00
|
|
|
|
2020-03-06 15:02:19 +03:00
|
|
|
For people new to Enso, and just starting to contribute, or even for more
|
2019-06-11 19:07:54 +03:00
|
|
|
seasoned developers, some useful places to look for information are:
|
|
|
|
|
2020-06-01 15:03:30 +03:00
|
|
|
- The [design documentation](./README.md).
|
2019-06-11 19:07:54 +03:00
|
|
|
- The community! Don't be afraid to ask questions.
|