Install the toolchains¶
langadapter toolchains installs the tools a language's projects need on
Ubuntu 24.04 on x86_64: on the computer itself, in WSL with Ubuntu 24.04 and
in an Ubuntu 24.04 container. Each language's part ends with langadapter check on a small
example: it runs the example's tests, measures their coverage and runs a mutation
session on its source file, so the command shows that the tools it installed work
together.
Install with the recipe¶
Name the languages, or all for every language that has a part on this
system:
langadapter toolchains python java
The parts install below ~/.local/share/langadapter/toolchains, or below
$XDG_DATA_HOME/langadapter/toolchains where that variable is set, unless
--into DIR names another directory. The command runs the parts in the order
named and stops at the first part that fails, with that part's status. It
ends with one line per language that a shell reads to find the tools:
. /home/user/.local/share/langadapter/toolchains/python.env
. /home/user/.local/share/langadapter/toolchains/java.env
Add these lines to the shell's start file, such as ~/.bashrc, so later
shells find the tools too. An install directory that holds a double quote, a
dollar sign, a backtick, a backslash, a line break or a colon is refused,
since a shell reads it in these files and a colon splits their PATH line.
--list shows each part and what it downloads, and runs nothing. It too
needs a system with parts, Ubuntu 24.04, also in WSL: on another system the
command says so, as for an install.
langadapter toolchains all --list
What each part installs¶
| Language | Installs | How runs find it |
|---|---|---|
| python | uv, CPython through uv, and an environment with pytest, coverage.py and Cosmic Ray at the versions LangAdapter pins | python.env puts uv on PATH. A project keeps its own interpreter, or names python_version, and LangAdapter provisions an environment with uv (Python projects). |
| java | a Temurin JDK and Maven | java.env sets JAVA_HOME, LANGADAPTER_MAVEN, LANGADAPTER_JAVA_TOOLS, the tool cache below the install directory, and PATH (Java projects). |
| c | GCC 13 with its gcov, make and binutils from the Ubuntu archive, clang and Mull from their Ubuntu packages, and uv and CMake through uv | c.env puts Mull, clang and CMake on PATH, and the system's GCC is the project's compiler (C projects). |
Tested environments names the versions
each part installs. On a machine that is not x86_64 a part stops before it
fetches anything. A built-in part's versions are fixed. For other versions,
install the tools yourself, as Windows and macOS lists.
The python part's environment with pytest, coverage.py and Cosmic Ray has
the interpreter DIR/python/environments/toolchain-<digest>/bin/python,
where <digest> is twelve hexadecimal digits of the environment's inputs,
and that interpreter can be a project's (Interpreter(path=...)).
What the parts download¶
Each part names its downloads by kind, and --list prints them:
- Checked by the part: the files a part fetches itself, checked against a checksum the part holds before it unpacks them. These are uv's archive, the JDK and Maven archives, and the Ubuntu packages of clang and Mull.
- Pinned through uv or Maven: CPython comes through uv, which checks it
against its own checksum. pytest, coverage.py and Cosmic Ray come from
PyPI at the versions LangAdapter pins, and CMake at the version the C part
pins, without a checksum LangAdapter holds.
The Java check's first run fetches the JUnit launcher, JaCoCo and PIT into
LangAdapter's tool cache, as every first run does, and Maven fetches its
build plugins and the example's JUnit from Maven Central into the
example's Maven repository below the install directory
(
DIR/java/repository). Maven only warns when a checksum there differs. - From the archive: the packages a part installs with apt-get rest on the Ubuntu archive's signatures.
A part never calls sudo. Run as root, as in a container, it installs the
system packages it needs with apt-get. Run as a user, it stops with the exact
sudo apt-get update && sudo apt-get install line when one is missing.
In a container¶
The parts download through the command's Python, which needs the system's certificates. A container build installs them and a Python with venv first:
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3-venv ca-certificates
RUN python3 -m venv /opt/venv && /opt/venv/bin/pip install "langadapter[c]"
RUN /opt/venv/bin/langadapter toolchains python java c --into /opt/toolchains
Containers says how a project then runs in such a container.
A language from an extension¶
An extension file can bring its own part beside langadapter_language, as
langadapter_toolchain: a mapping from a system name such as ubuntu-24.04
to the part's shell text. --extension FILE loads the file first, and
--list shows its part before anything runs:
langadapter toolchains lua --extension lua.py --list
The part's text runs with the rights of the user who runs the command, as the extension's own code does when it loads.
A part is a POSIX shell script that takes three arguments: the install
directory, the Python the command runs in, and the extension: the file's
absolute path for a file, the module's name for an installed module, and
empty for a built-in part. It writes below
DIR/<language>/ and the file DIR/<language>.env, and keeps what its
check downloads below DIR/<language>/ too, as the Java part keeps
LangAdapter's tool cache and its example's Maven repository. It
names each download in a header line # download <kind>: <text>, and an
extension's part ends with
"$2" -m langadapter.cli check <language> --extension "$3" --example DIR/<language>/example,
so the check runs the LangAdapter of the command and finds its language.
The system name is <ID>-<VERSION_ID> from /etc/os-release, such as
ubuntu-24.04, and a system that the mapping does not name has no part. The
built-in parts name their downloads with the kinds checked, pinned and
archive. An extension's part may use any kind word, which --list prints
as written. A part belongs to the language the same file names as
langadapter_language, so a file without one brings no part. A part is read
and shown only on a system with parts, and langadapter check names no
part. From Windows, run langadapter toolchains LANGUAGE --extension FILE
--list in WSL to see it. The part writes the example its check runs itself. A whole part for
a language lua, at the end of lua.py:
langadapter_toolchain = {"ubuntu-24.04": """#!/bin/sh
# download archive: lua5.4, installed with apt-get as root
set -eu
mkdir -p "$1"
DIR=$(cd "$1" && pwd)
HERE=$DIR/lua
mkdir -p "$HERE/example"
if [ "$(id -u)" -eq 0 ]; then
apt-get update && apt-get install -y --no-install-recommends lua5.4
elif ! command -v lua5.4 >/dev/null; then
echo "sudo apt-get update && sudo apt-get install lua5.4" >&2
exit 1
fi
echo "export LUA=$(command -v lua5.4)" > "$DIR/lua.env"
cat > "$HERE/example/calc.lua" <<'EOF'
function add(a, b) return a + b end
EOF
cat > "$HERE/example/test_calc.lua" <<'EOF'
assert(add(2, 3) == 5)
EOF
"$2" -m langadapter.cli check lua --extension "$3" --example "$HERE/example"
"""}
DIR/lua.env is a shell file of export lines, which the command names at
its end for a shell to read.
Windows and macOS¶
The recipe runs on Ubuntu 24.04. On Windows, WSL with Ubuntu 24.04 runs it, and Testuary's guide Set up your machine shows how to set WSL up. On Windows itself and on macOS, install the tools by hand:
- Python: an interpreter with pytest, coverage.py and Cosmic Ray at the
versions Tested environments names,
installed into the project's environment with pip, or uv with
python_version(Python projects). - Java: a JDK of a version
Tested environments names, such as
Temurin's, with
JAVA_HOMEset, and Maven or Gradle onPATH, or the project's own wrapper (Java projects).
langadapter check python --example DIR or
langadapter check java --example DIR then runs the language's tests on an
example directory whose tests pass.
Check on an example
gives the rules of such a run: the program that runs the tests, for Python
the project's activated environment, the tools it runs or leaves not checked,
and the exit statuses. C projects run on Linux only.