Ensure a JDK (Java Development Kit) is installed on your machine. Java versions 8 or 11 are recommended, with 8 as minimum version. If you don't already have a JDK installed, you can install one by following the instructions on the AdoptOpenJDK website, or by grabbing the coursier command-line and using its
cs java command. Your OS package manager (
apt, …) may also offer to install a JDK for you.
Once a JDK is installed, you should be able to run the
java command, like
$ 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
Check-out the sources with git:
$ git clone https://github.com/almond-sh/almond.git $ cd almond
Almond is built with mill. A mill launcher ships with almond, so that you don't need to install mill yourself. We list below useful commands, to help get you started using mill to build almond.
Run a Jupyter notebook server without installing a kernel
$ ./mill -i jupyter
- build an almond launcher, then
- start JupyterLab in the current directory.
From the JupyterLab instance, select the kernel "Scala (sources)".
Optionally, pass a Scala version and / or JupyterLab options, like
$ ./mill -i jupyter 2.12.13 $ ./mill -i jupyter --ip=192.168.0.1 $ ./mill -i jupyter 2.12.13 --ip=192.168.0.1
(If specified, the Scala version needs to be passed first.)
Build a kernel launcher
$ ./mill launcher
Once done building, this should print the path to the kernel launcher, like
Optionally, pass a Scala version, like
$ ./mill launcher 2.12.13
You can then run that launcher to install it on your system:
$ out/scala/scala-kernel/2.13.4/unixLauncher/dest/launcher --install
--help or see this page for the available options.
Watch for source changes
You can re-build a launcher upon source changes with
$ ./mill -w launcher
If you ran a JupyterLab server from the almond sources, you can restart the kernel from a notebook via JupyterLab to pick a newly built launcher. If you passed a Scala version to
./mill jupyter, beware to pass the same version to
./mill -w launcher.
List available Scala versions
$ ./mill scalaVersions 2.13.4 2.13.3 …
Print the latest supported Scala 2.13 version
$ ./mill scala213 2.13.4
Print the latest supported Scala 2.12 version
$ ./mill scala212 2.12.13
Compile all modules for a Scala version
$ ./mill '__[2.13.4].compile'
Compile all modules for a Scala version and watch source changes
$ ./mill -w '__[2.13.4].compile'
Compile all tests for a Scala version
$ ./mill '__[2.13.4].test.compile'
Compile all tests for a Scala version and watch source changes
$ ./mill -w '__[2.13.4].test.compile'
Run all tests for a Scala version and watch source changes
$ ./mill -w '__[2.13.4].test'
Compile specific modules
$ ./mill 'scala.scala-kernel[2.13.4].compile'
Generate Metals configuration files
It is recommended to generate Metals configuration files manually, rather than letting Metals load the project itself. In order to do that, run
$ ./mill mill.contrib.Bloop/install
If you're using Metals from VSCode, you can then run the "Metals: Connect to build server" command to take into account the newly generated files.
If the command above takes too long to run, comment out Scala versions in
deps.sc. If no 2.12 versions are left, also comment out the few 2.12-specific projects in
build.sc (look for
212 to find them). Same if no 2.13 versions are left (look for
213 to spot 2.13-specific projects).
Generate IntelliJ IDEA configuration files
It is recommended to manually generate IntelliJ configuration files, rather than letting IntelliJ load the project itself. In order to do that, run
You can then open the project in IntelliJ. IntelliJ should also automatically pick those files when they are overwritten.
Just like for Metals above, you may benefit from disabling all but one Scala version (see above for more details).
Validate the example notebooks
Example notebooks live under
examples/. These are run on the CI using nbconvert, and the resulting outputs are compared to the committed ones. Any difference results in the examples job on the CI to fail.
To validate the examples locally, run
$ ./mill -i validateExamples
Optionally, you can pass a glob to filter notebook names:
$ ./mill -i validateExamples 'scalapy*'