Browse files

Merge pull request #251 from alexarchambault/update-doc

Add install from sources instructions
  • Loading branch information...
alexarchambault committed Oct 29, 2018
2 parents ec89c95 + 9853942 commit d2574fbbb594b7564090abd44a4fce69132c63fb
@@ -0,0 +1,67 @@
title: Installing from sources
## Prerequisites
Ensure a JDK 8 is installed on your machine
$ java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
$ javac -version
javac 1.8.0_121
Ensure an [sbt]( launcher is installed
$ sbt -help
Usage: sbt [options]
If it's not, [sbt-extras]( or the default installer from [the sbt website]( should do.
## Compiling
Check-out the sources with
$ git clone
$ cd almond
Compile and publish the kernel locally with
$ sbt publishLocal
This installs the kernel artifacts under your `~/.ivy2/local` local repository. The kernel artifacts should land under `~/.ivy2/local/sh.almond/` in particular. In the output of `sbt publishLocal`, note the snapshot version the kernel is installed with. At the time of writing this, this version is `0.1.11-SNAPSHOT`.
## Installing
Create a launcher with
$ coursier bootstrap \
-i user -I user:sh.almond:scala-kernel-api_$SCALA_VERSION:$ALMOND_VERSION \
sh.almond:scala-kernel_$SCALA_VERSION:$ALMOND_VERSION \
-o almond-snapshot --embed-files=false
Compared to [the default installation instructions](, `--embed-files=false` is added as an option. This makes the generated launcher directly rely on files under `~/.ivy2/local`, rather than copying those in the launcher. If the files under `~/.ivy2/local` are updated (e.g. with a new `sbt publishLocal`), just restarting the kernel is enough for these to be picked, which is useful for fast iterations during development.
Then install the kernel with
$ ./almond-snapshot --install \
--id scala-snapshot \
--display-name "Scala (snapshot)" \
--log debug \
--log-to "$(pwd)/almond-snapshot-log.txt"
Optionally, change the log level with e.g. `--log debug`. If you'd like these logs to go to a distinct file rather than in the console, pass e.g. `--log-to "/path/to/log-file.txt"`.
## Development cycle
Once the kernel is installed this way, one can update its artifacts with `sbt publishLocal`. These are taken into account by restarting the kernel.
Re-generating an installer, and installing it, is only necessary if the dependencies of the kernel are changed / updated, or if the kernel version changes. It is safer to re-generate an installer and install it after a `git pull` in particular.
@@ -0,0 +1,39 @@
title: Generate the website
Install pre-requisites with
$ sbt \
interpreter-api/exportVersions \
interpreter-api/publishLocal \
Then run
$ scripts/
If the generation is successful, this should print instructions to run
a small webserver serving the website, like
$ npx http-server docs/website/build/almond
This command should itself print the address to access the local website,
like ``.
## Watch sources
Pass `--watch` to `` above,
$ scripts/ --watch
In another terminal, go under the `docs/website` directory, and run
$ yarn start
This should open a browser window, pointing at the locally running website.
@@ -13,7 +13,7 @@ $ coursier bootstrap @EXTRA_COURSIER_ARGS@\
See the available versions of almond [here](,
adjust `ALMOND_VERSION` and `SCALA_VERSION` at your convenience (not all combinations are guaranteed
to be available, see the available combinations [here](
to be available, see the available combinations [here](
Run the launcher like
@@ -3,6 +3,6 @@
"Quick start": ["intro", "quick-start-install"],
"Usage": ["usage-shell", "usage-jupyter", "usage-plotting", "usage-spark"],
"Installation": ["install-options", "install-multiple", "install-versions", "install-other"],
"Development": ["dev-custom-kernel", "dev-libraries"]
"Development": ["dev-from-sources", "dev-custom-kernel", "dev-libraries", "dev-website"]
@@ -3,6 +3,12 @@ set -e
# FIXME Lots of duplications with
if [ "$1" == "--watch" ]; then
cd "$(dirname "${BASH_SOURCE[0]}")"
# Assumes 'sbt interpreter-api/exportVersions' has been run
@@ -20,6 +26,12 @@ fi
echo "Processing Markdown files"
if [ "$WATCH" = 1 ]; then
# first processing md files via
# requires the cache modules and its dependencies to have been published locally
# with
@@ -32,7 +44,12 @@ echo "Processing Markdown files"
--out ../docs/processed-pages \
if [ "$WATCH" = 1 ]; then
exit 0
echo "Generating website"

0 comments on commit d2574fb

Please sign in to comment.