Autres pages › environment

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

The development environment: archec env

archec env says which tools a project needs to be worked on, and why. It reads them from the model: the project's kind, the code it generates, its boards, its deployments and its handlers. archec env doctor looks each one up on this computer and says how to install what is missing. archec env init writes the files that install them: mise.toml with pinned versions, a Makefile, and package lists for apt, Homebrew and winget.

archec env plan            # what the project in this folder needs, and why
archec env doctor          # which of them are here, and the fix for each one that is not
archec env init            # mise.toml, Makefile, env/apt.txt, env/Brewfile, env/winget.json
mise install && make setup # then: make build, make test

Each command takes the project folder or its main file (archec env doctor my-shop, archec env plan my-shop/main.arche); the default is the current folder. archec new --env mise,make,packages writes the same files in a new project.

What a project needs#

archec env plan lists the tools in two groups. The first holds what you need to build and test the project. The second holds optional tools: a flasher or a debugger for the board, a step that CI leaves out.

Svc (kind service): main.arche

Needs:
  go 1.27  kind service (go build, go vet, go test); target go (archec gen --target go)
  node 24  archec (archec itself)

Optional:
  arche-cli   archec (archec test)

Each tool comes from one of these:

  • The kind. archec new --kind writes the kind in .archec/kind.json. The kind's build and test steps name the programs they run, such as go, cmake, colcon or podman.
  • The code. Each archec gen target needs its toolchain: make and a C compiler for c, Rust for embassy, go for go, Qt 6 for ui-qml. A project without a kind gets its targets from its deployments: a binary's language, a processor that runs Zephyr, an FPGA.
  • The boards. A microcontroller board adds its tools as optional ones: arm-none-eabi-gcc and OpenOCD for C on an STM32, nRF or RP2040 board; probe-rs for Rust; esptool for an ESP32, and espup for Rust on its Xtensa cores. The devcontainer then gets the USB devices.
  • The handlers. Python handlers need Python 3. TypeScript handlers in .ts files add typescript to package.json, for tsc. A step that imports a Python module, such as the robot kind's MuJoCo check, adds that module to requirements.txt.
  • archec itself needs Node.js. archec test also needs arche-cli, Arche's simulator. archec sim needs nothing.

The plan also holds the ports the project serves, the base image for a devcontainer and the VS Code extensions to recommend. --json prints the whole plan; the VS Code extension reads the same data.

The doctor#

archec env doctor runs each tool's version command and compares the version with the pin:

Svc (kind service): darwin, mise on the PATH
  ✓ go 1.27.4  kind service (go build, go vet, go test); target go (archec gen --target go)
  ~ node 22.1.0, pinned 24  archec (archec itself)
      mise install node@24
      brew install node
  – arche-cli (optional) missing  archec (archec test)
✓ every tool the project needs is here; 1 at another version than its pin

A version matches its pin on the parts the pin gives, up to major.minor. So 1.27 matches 1.27.4, 24 matches 24.22.3, and 3.13 does not match 3.12. A pin of stable, latest or system matches any version.

The fix comes first from mise, when mise is on the PATH and has the tool: mise install go@1.27. Then comes the system's package manager: brew install on macOS, sudo apt install on Linux, winget install on Windows. A tool no package manager has, such as the Zephyr SDK or ESP-IDF, gets a note that says where to get it.

The doctor exits with 1 when a tool the project needs is missing. A version other than the pin is shown with ~, but it does not fail: the tool runs, and the pin may be the one that is out of date.

When archec new makes its first run and a tool is missing, the step is skipped, and its note gives the same fix: no go on this computer (go missing: brew install go).

The files#

archec env init writes mise, make and packages; --with picks others. archec env sync writes again the parts the project already has. Add --dry-run to print the files without writing them, and --json to get them as data.

Part Files Written again
mise mise.toml: [tools] with a pinned version per tool, [tasks] setup, gen, build, test, sim, ci, doctor Only what is missing is added. A version you changed and a task you wrote stay as they are.
make Makefile: the same tasks as targets, make help Rewritten around your USER CODE regions, which are kept. A Makefile archec did not write is left alone, and the targets go to archec.mk for you to include.
packages env/apt.txt, env/Brewfile, env/winget.json; requirements.txt and package.json when the handlers need packages The lists in env/ are written again each time. In requirements.txt and package.json, a missing package is added, and none is changed.
devcontainer .devcontainer/devcontainer.json and its Dockerfile In builds that have it; others say devcontainer: not available in this build.

mise.toml#

[tools]
go = "1.27"  # kind service, target go
node = "24"  # archec
# "cargo:probe-rs-tools" = "latest"  # optional: board nucleo-f446re

[tasks.build]
description = "build the generated code"
run = "cd src/go/svc && go build -o ../../../generated/bin/svc ."

mise installs each tool at its version, for this project only: mise install (the first time, mise trust lets mise read the file). An optional tool is written commented out: remove the # to have it.

To pin a version, change it in mise.toml. archec env sync never changes a version you wrote, and the plan and the doctor read your pin. A tool with no mise package, such as Qt or a vendor SDK, is not in [tools]. Install it with the package lists, or as the doctor says.

Makefile#

build: gen ## build the generated code
	cd src/go/svc && go build -o ../../../generated/bin/svc .
# USER CODE BEGIN build
	@echo your own step, kept
# USER CODE END build

Each target is followed by a region of its own. A line in the region is part of the target's recipe, so it starts with a tab. The last region, targets, holds targets of your own. make setup first runs mise install when there is a mise.toml, then the commands the tools need after they are installed: rustup target add for the board's Rust target, pip install -r requirements.txt, npm install.

The package lists#

  • env/apt.txt: sudo apt install -y $(grep -v "^#" env/apt.txt).
  • env/Brewfile: brew bundle --file env/Brewfile.
  • env/winget.json: winget import env/winget.json.

Optional tools are commented out in apt.txt and the Brewfile, and left out of winget.json.

Dev container#

archec env init --with devcontainer (or archec new --env devcontainer) writes two files; archec env sync writes them again when the project's needs change:

file what it is
.devcontainer/devcontainer.json VS Code's "Reopen in Container", or devcontainer up: the image, the extensions, the forwarded ports, the user
.devcontainer/Dockerfile the image: system packages, mise and the project's pinned tools, archec itself

Open the project in VS Code, run Dev Containers: Reopen in Container: every tool the project needs is there, at the versions mise.toml pins, and so is archec. When the container is made, mise install && archec env doctor runs (postCreateCommand), so a pin changed since the image was built is installed, and anything still missing is said.

How each tool gets in the image#

One rule, in this order, so that no tool is installed twice:

  1. mise: a tool mise knows. The project's mise.toml is copied into the image as the user's global mise config and mise install runs: the same versions as on your computer, in any folder of the container. (No mise.toml: mise use -g tool@version for each, at the version archec picked.)
  2. apt: else a tool with Debian/Ubuntu packages: one apt-get install --no-install-recommends, the package lists removed after.
  3. devcontainer feature: else a tool with a good feature (ghcr.io/devcontainers/features/docker-outside-of-docker:1), in features. A tool the Dockerfile installs never also gets a feature.

A tool none of them installs (a vendor SDK) is named in a comment of the Dockerfile, with how to get it.

Then each tool's after-install commands (rustup target add …, pip install west), the kind's shell setup (. /opt/ros/jazzy/setup.sh, in /etc/profile.d/archec-env.sh, read by every bash), and archec.

mise is its release binary, pinned (ARG MISE_VERSION) and checked against its SHA-256 — not the install script, nor the apt repository (which gives whatever is newest): the same bytes on every build. To move to another mise, change MISE_VERSION and the two sums.

archec is the arche-lang CLI from https://arche-lang.xyz/downloads: arche-lang-<version>.tgz, installed with npm install -g on a node from mise (the project's, or node 22). The version is the one the project was made with (archec in .archec/kind.json, else in generated/.archegen.json), in ARG ARCHEC_VERSION; empty means the latest. Only the latest release is served: when the recorded one is gone, the latest is installed, with a warning in the build log. The latest is checked against the SHA-256 in latest.json.

The user#

The container runs as vscode (uid 1000), not root, so that what you build in the bind-mounted project belongs to you on a Linux host.

  • mcr.microsoft.com/devcontainers/base:bookworm (most kinds) has that user.
  • ros:jazzy-ros-base (ROS 2) runs as root and has an ubuntu user with uid 1000: the Dockerfile renames it vscode (any other image without the user gets it made), with passwordless sudo.

What is yours#

  • Dockerfile: archec's, except two # USER CODE regions it keeps on every archec env sync (regeneration): devcontainer.root (run as root, after the packages: more packages, udev rules) and devcontainer.user (as vscode, at the end).
  • devcontainer.json (JSON with comments): archec writes again name, build, features, forwardPorts, portsAttributes, postCreateCommand, remoteUser, and its own entries of containerEnv and customizations.vscode.extensions. Every other key (runArgs, mounts, settings, more extensions or variables) is kept. Your comments are not: the file is read, then written again.

Boards over USB#

A project that flashes or reads a board gets the user in the dialout and plugdev groups, and two runArgs lines in devcontainer.json, commented out — archec never makes a container privileged on its own:

  // "runArgs": ["--device=/dev/ttyACM0"]
  // "runArgs": ["--privileged", "-v", "/dev/bus/usb:/dev/bus/usb"]

Uncomment one (prefer --device with your board's device). It works on a Linux host only: Docker Desktop and Podman on macOS cannot pass USB to a container (flash from the host there); on Windows, attach the board to WSL first with usbipd (usbipd bind --busid <id>, then usbipd attach --wsl --busid <id>).

CI in the same image#

With a dev container, the CI files archec new writes run the code job in its image — the same tools, the same versions as yours:

  • GitHub (.github/workflows/archec.yml): devcontainers/ci@v0.3 builds the image and runs, as vscode, archec gen for each target, then the kind's build and test commands (after its setup line, for ROS 2). The model's job is unchanged.
  • GitLab (.gitlab-ci.yml): docker:27 with the docker:27-dind service builds .devcontainer/Dockerfile and runs the same commands in it, as root (the runner's checkout belongs to root; mise's folders are fixed in the image, so root finds the same tools). The runner needs privileged mode for docker-in-docker.

Without a dev container the CI files are as before: each tool set up on the runner (actions/setup-go, …), or the kind's own image (ROS 2).

Limits#

  • The build context is the project folder: add a .dockerignore there when generated/ or build outputs make it large.
  • mise tools that come from GitHub releases (ubi:, aqua:) may meet GitHub's rate limit on a busy CI runner; give the build a GITHUB_TOKEN.
  • Language packages for your own code (pip, npm, cargo, Go modules) are not installed in the image: your project's usual install step does that.

In VS Code#

The arche-lang extension shows the same plan and doctor, and writes the same files.

  • The Environment view (in the Arche side bar): one row per tool. ✓ found, ✗ missing, ⚠ at another version than the pin; an optional tool is dimmed. The description is the version found and the one pinned; the tooltip says why the project needs it and how to install it. The title bar has Set Up…, Run Doctor in Terminal (archec env doctor in a terminal named arche env) and Refresh. On a row, Install Tool… asks "Run brew install go in a terminal?" and only then types the command in the arche env terminal; Copy Fix Command copies it.
  • The status bar: env ✓ when every tool the project needs is here, env: 2 missing otherwise. A click shows the view.
  • Arche: Set Up Development Environment… asks which parts to write (mise.toml, Makefile, dev container, package lists; the ones the project has are ticked), shows each file that would change in the diff editor, and writes them after a "Write N files" confirmation that lists the tools and their pins. When it wrote a dev container, it offers Reopen in Container (or shows the Dev Containers extension, when it is not installed: the extension never installs anything). A second run with nothing new writes nothing.
  • Once per project, when a tool it needs is missing: "This project needs go, cmake — not found. Set up the environment?" with Show Environment, Set Up… and Don't Ask Again for This Project.

The doctor runs its probes in the background, in parallel, each with a time-out, once there is a project; the report is kept until you save mise.toml, .archec/kind.json or a .arche file, close the arche env terminal, or click Refresh. In a dev container the extension runs inside the container, so the view and the status bar say what the container has: env ✓ when its Dockerfile installed everything. arche-cli counts as here when the extension carries it (or arche.paths.appCli names one).

The catalogue#

The tools archec knows are in src/env/catalog.ts. Each one has a version command, a default version and its names for mise, apt, Homebrew and winget. It can also have a devcontainer feature, commands to run after the install, and a note for a vendor SDK. Each word a kind's steps name is in it.

Area Tools
archec, handlers node, python3, uv, arche-cli
C, C++ make, cc, cmake, ctest, ninja, qmake6 (Qt 6), lcov, gcovr
Go, Rust go, rustup, cargo, probe-rs, espup
Microcontrollers arm-none-eabi-gcc, openocd, esptool, west, zephyr-sdk, esp-idf, platformio, renode
FPGA ghdl
Containers podman, docker-compose, kubectl
ROS 2 ros2, colcon, gazebo
Others protoc, bash, git

A tool a step names that the catalogue does not have is still listed, with a note: install it as its own project says.

Windows#

On Windows, the doctor's fixes are winget install --id … -e, and env/winget.json installs the whole list. Some toolchains do not run natively on Windows: a C compiler named cc, make in the shell, ROS 2. For these, there are two ways:

  • WSL. Install Ubuntu with wsl --install, open the project from there, and use the Linux commands (env/apt.txt).
  • Dev Containers. VS Code's Dev Containers extension runs the project's .devcontainer/ in Docker Desktop or Podman, through WSL 2. The tools are then the container's, the same as on Linux and macOS.

mise runs on Windows too. It installs Go, Node.js, Python, CMake and the other tools it has.

Limits#

  • archec does not install anything itself. It says what to run and writes the files that run it.
  • The doctor checks each program and its version. It does not check a Rust target, a Python module, or that a daemon (podman, Docker) is running; the first run of archec new and make test find those.
  • Vendor SDKs (the Zephyr SDK, ESP-IDF, Espressif's Rust, Renode) have no package and no pin: their notes say where to get them.
  • The package names were checked for Debian bookworm, Ubuntu 24.04, Homebrew and mise. Some tools are only in another apt repository: ROS 2, Kubernetes, and Docker's own Compose. kubectl has no Debian package: mise or the Kubernetes repository installs it.
  • A task archec added to mise.toml is not changed when the model changes, because it may be yours now. Delete it, and archec env sync writes it again.