Permalink
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
```bash
$ 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](https://scala-sbt.org) launcher is installed
```bash
$ sbt -help
Usage: sbt [options]
[…]
```
If it's not, [sbt-extras](https://github.com/paulp/sbt-extras) or the default installer from [the sbt website](https://scala-sbt.org) should do.
## Compiling
Check-out the sources with
```bash
$ git clone https://github.com/almond-sh/almond.git
$ cd almond
```
Compile and publish the kernel locally with
```bash
$ 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
```bash
$ SCALA_VERSION=2.12.7 ALMOND_VERSION=0.1.11-SNAPSHOT
$ 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](quick-start-install.md), `--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
```bash
$ ./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
```bash
$ sbt \
interpreter-api/exportVersions \
interpreter-api/publishLocal \
scala-kernel-api/publishLocal
```
Then run
```bash
$ scripts/generate-website.sh
```
If the generation is successful, this should print instructions to run
a small webserver serving the website, like
```bash
$ npx http-server docs/website/build/almond
```
This command should itself print the address to access the local website,
like `http://127.0.0.1:8080`.
## Watch sources
Pass `--watch` to `generate-website.sh` above,
```bash
$ scripts/generate-website.sh --watch
```
In another terminal, go under the `docs/website` directory, and run
```bash
$ 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](https://github.com/jupyter-scala/jupyter-scala/releases),
adjust `ALMOND_VERSION` and `SCALA_VERSION` at your convenience (not all combinations are guaranteed
to be available, see the available combinations [here](versions.md)).
to be available, see the available combinations [here](install-versions.md)).
Run the launcher like
```bash
@@ -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 https://github.com/coursier/coursier/blob/3309b64102678550b1393c524dddf2b71fb9d931/scripts/generate-website.sh
if [ "$1" == "--watch" ]; then
WATCH=1
else
WATCH=0
fi
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
EXTRA_OPTS="--watch"
else
EXTRA_OPTS=""
fi
# first processing md files via https://github.com/olafurpg/mdoc
# 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 \
--site.VERSION "$VERSION" \
--site.SCALA_VERSION "$SCALA_VERSION" \
--site.EXTRA_COURSIER_ARGS "$EXTRA_COURSIER_ARGS"
--site.EXTRA_COURSIER_ARGS "$EXTRA_COURSIER_ARGS" \
$EXTRA_OPTS
if [ "$WATCH" = 1 ]; then
exit 0
fi
echo "Generating website"

0 comments on commit d2574fb

Please sign in to comment.