Dev Set-Up

Nix

Please install Nix to contribute to this project, and run:

• nix run .#test to execute unit and integration tests, which should be (relatively) fast

You can also enter the Nix build environment to have the same tools available, which is convenient for development:

nix develop

We recommend that you also install direnv which conveniently automates this.

Setup is in flux, WIP full Nix adoption!

This project is in the process of fully adopting https://nixos.org for all required tools. Much of following is out of date!

Scripts

• ./enola locally builds and then starts Enola; this is equivalent to starting it as an end-user from the packages
• ./test.bash runs unit and integration tests, and should be (relatively) fast
• ./tools/test-ci/test.bash runs the same as above and then some slower tests etc. like CI
• ./update.bash updates dependencies

These scripts assume that Nix is “activated” (PATH) in your shell, see above; they currently do not do this by themselves. So launching them from outside the Nix build environment (AKA nix develop) is not supported.

TODO Hashbang magic, if any?

Use Nix apps…

These scripts should probably be defined as Nix “apps” and used as nix run .#test and nix run .#enola ? Contributions welcome!

Further Reading

You can now read more about:

• Code Style
• IDE Support
• Dependencies
• Bazel

GitHub Codespaces

We highly recommend you use our ready-made “1 click” Web/Cloud IDE set-up.

Development Environment in a Docker Container

Because it can be a PITA to install all required tools, especially on non-Linux platforms, this project comes with a containerized (“Docker”) development environment, which you can use like this:

1. Get the source code:

   git clone https://github.com/enola-dev/enola.git
   cd enola
   

2. Build and enter (prompt) the Dev. Env. container, which includes all required tools, but with the source code “local / on host” mounted:

   ./devenv.bash
   

3. (You’re now in the container.) Run the Enola CLI, built from source:

   ./enola
   

4. (You’re still in the container.) Build everything and run the tests:

   ./test.bash
   

When tests ran fully successfully, then a .git/hooks/pre-commit that’s useful for development is installed.

Documentation Writing

To work on documentation, launch:

• tools/docs/serve-quick.bash for hot reloading live refresh, which is great while writing (even though it has some limitations)
• tools/docs/serve-build.bash for a “real” (full) docs build, without without the demo “screen cast” recordings (which are slow)
• tools/docs/serve.bash for generating the “real” (full) static site/ exactly as it’s deployed on https://docs.enola.dev

Manual Tools Installation

If you do still want to try, here’s how to manually install what the development environment container comes built-in with:

1. Install Java Development Kit (JDK), same version as in .bazelrc. There are different Java (like Linux) “distributions” (all based on OpenJDK). The easiest way to install one of them is typically to use your OS’ package manager:

   sudo apt-get install openjdk-21-jdk openjdk-21-doc openjdk-21-source
   

An alternative is to use e.g. the SDKMAN! If you work on several projects using different Java versions, then we recommend using something like jEnv (with .java-version), or asdf (with .tool-versions), or direnv (with .envrc).

1. Install C/C++ etc. (it’s required by the Proto rule for Bazel), e.g. do:

   sudo apt-get install build-essential
   

2. Install Python venv (it’s used by the presubmit and docs site generation), e.g. with:

   sudo apt-get install python3-venv
   

3. Install Bazelisk (NOT Bazel), on a (recent enough…) Debian/Ubuntu with Go e.g. like this (or some more manual equivalent):

   sudo apt update
   sudo apt install golang-go
   go install github.com/bazelbuild/bazelisk@latest
   

You should now be able to proceed as above (but without requiring Docker).

Clean Up

Use Nix and do not do pip install -r requirements.txt outside of the virtual environment!

In case of errors such as ModuleNotFoundError: No module named 'pre_commit', try wiping the cache of https://pre-commit.com:

rm -rf ~/.cache/pre-commit/

In cases like ImportError: cannot import name '...' from '...', maybe try wiping the user (non-venv) Python libs:

rm -rf ~/.local/lib/python*

For “cannot parse .renovaterc.json5 because support is missing for json5” from pre-commit run --all-files you may have to:

rm -rf ~/.cache/pre-commit/
pip install -r requirements.txt

But if you are correctly in Nix’s development environment (nix develop), then there should normally be no need for any this.