callisto instructions

To use https://callisto.liw.fi/:

• Your project must be using Rust.
• CI will run in Ambient, which runs actions in a virtual machine that has no network access.
• Create a file .radicle/ambient.yaml at the root of your repository with content like the following:

pre_plan:
  - action: cargo_fetch
plan:
  - action: cargo_fmt
  - action: cargo_clippy

  - action: shell
    shell: |
      export CARGO_TARGET_DIR=/workspace/cache
      export CARGO_HOME=/workspace/deps
      export HOME=/root
      export PATH="/root/.cargo/bin:/root/.radicle/bin:$PATH"

      # Check that `rad` is there.
      rad --help >/dev/null || (echo rad is not there; exit 1)

      cargo doc --workspace --no-deps

      # FIXME: We can't run upgrade tests from older versions because
      # Ambient only fetches dependencies for the current version.
      # Thus, we can't build the old versions. This is an Ambient
      # problem that we can't fix here. So we skip the upgrade tests.
      cargo test --workspace --no-fail-fast -- --skip upgrade --test-threads 2

      subplot docgen ci-broker.subplot -o doc/ci-broker.html
      subplot docgen doc/userguide.subplot -o doc/userguide.html
      make -C doc
      cp doc/*.html /workspace/artifacts/.

  - action: custom
    name: dch
    args:
      debemail: liw@liw.fi
      debfullname: "Lars Wirzenius"

  - action: deb

• Here, pre_plan is a list of actions to run on the host, before the virtual machine runs. The only action you can put there is cargo_fetch, which downloads Rust crates and makes them available in the VM.
• The actions in plan are executed in the VM. The VM isolates them so that the actions can’t do any damage apart from spending time.
• Available actions:
  • cargo_build, cargo_clippy, cargo_fmt, cargo_test - run the corresponding cargo command
  • custom - run named executable located in .ambient in the repository, with the arguments serialized as JSON in stdin; in the example above, .ambient/dch
  • deb - build a deb package
  • shell - run arbitrary shell snippet with Bash
• Note that the cargo_* actions set environment variables so that the Rust installed in the VM works; see example above how to set them for the shell action
  • it’s a bug in Ambient that the environment variables aren’t set for all actions
• Ambient also supports post_plan actions, but they aren’t enabled on callisto
• There is a limit on CPUs, RAM, and run time, and disk space used for cache (/workspace/cache in the VM), dependencies (/workspace/deps), and artifacts (/workspace/artifacts), and the run will fail end (possibly with mysterious error messages) if those limits are exceeded.