# Tâches de build

`elide build` déduit des tâches des source sets et des artefacts de `elide.pkl` et les exécute dans l'ordre des
dépendances. Les tâches dont les entrées n'ont pas changé sont ignorées ou restaurées depuis le cache.

## Lancer un build

```bash
elide build                   # run the default group
elide build compile-java-main # run one task
elide build compile           # run a group
elide build clean             # the clean target
elide build --inspect         # list tasks and their options without running
elide build jvm-test --help   # one task's options and what they mean
elide build --no-cache        # ignore cached results and build state
elide build --offline         # no network: no dependency fetches, no shared cache
elide build --workers=4       # run at most four tasks at once
```

Un argument nomme une tâche ou un groupe ; le deux-points initial (`:compile-java-main`) est facultatif. Une cible qui
ne correspond à rien fait échouer le build.

| Groupe | Alias | Tâches |
| --- | --- | --- |
| `default` | — | Ce qu'exécute un simple `elide build`. |
| `dependencies` | `deps` | Résolution et installation des dépendances. |
| `compilation` | `compile` | Compilation des sources. |
| `testing` | `test` | Tests ; également lancés par `elide test`. |

Certaines tâches acceptent des options, listées par `--inspect` :

```bash
elide build test --select=class:com.example.SomeTest
elide build run --args="a b c"
```

Dans un [espace de travail](/docs/elide-pkl-reference#workspaces), préfixez le projet : `core:compile-kotlin-main`,
`core:compile`, ou `core` pour ses tâches par défaut. Les cibles sans préfixe se résolvent dans le projet courant, puis
dans la racine. `--inspect` regroupe les tâches par projet, et les lignes de progression le nomment
(`[core] Compiling Kotlin sources`).

Un projet peut ajouter ses propres groupes et tâches, y compris des tâches exécutées avant celles intégrées :
consultez [Extensions de compilation](/docs/toolchain/build-extensions).

## Options

Les options s'écrivent `--name` ou `--name=value`, n'importe où parmi les cibles. Les arguments après `--` vont au
processus que lance une tâche.
`--inspect` liste les options de toutes les tâches ; `elide build <task> --help` décrit celles d'une tâche donnée.

| Option | Effet |
| --- | --- |
| `--inspect`, `-i` | Liste les tâches et leurs options sans les exécuter. |
| `--no-cache` | Ignore le cache et l'état local du build ; toutes les tâches s'exécutent. |
| `--offline` | Aucun téléchargement de dépendances et aucun cache partagé. |
| `--workers=N` | Au plus `N` tâches simultanées (par défaut : nombre de processeurs). Le `=` est obligatoire. |
| `-f NAME[=VALUE]` | Option de build, lue via `build.flags` ; voir [Options de build](/docs/toolchain/build-flags). |

Les options sont vérifiées par rapport aux tâches avant toute exécution. Une option inconnue, une valeur manquante ou
inattendue, ou une option répétée provoque un échec :

```text
Unknown option '--worker', did you mean '--workers'?
Option '--workers' requires a value, as '--workers=<value>'
```

Les options globales (`-p`, `-v`, `--debug` et les autres) sont exemptées. Options des tâches :
[Dépendances](/docs/toolchain/dependencies#maven-options), [Tests](/docs/toolchain/testing#options).

## Cache de build

Le niveau **local** est toujours actif : `~/.elide/cache/entries-v2`, un répertoire par clé avec un enregistrement et
une archive tar des sorties. Les restaurations sont vérifiées par rapport à l'empreinte enregistrée. Les entrées dans
un format plus ancien comptent comme absentes.

Le niveau **partagé** est un cache HTTP, configuré par des variables d'environnement :

| Variable | Signification |
| --- | --- |
| `ELIDE_REMOTE_CACHE` | URL du point de terminaison. Non définie : pas de niveau partagé. |
| `ELIDE_REMOTE_CACHE_TOKEN` | Jeton bearer ; prioritaire sur l'authentification basique. |
| `ELIDE_REMOTE_CACHE_USERNAME`, `ELIDE_REMOTE_CACHE_PASSWORD` | Authentification basique ; les informations utilisateur dans l'URL fonctionnent aussi. |
| `ELIDE_REMOTE_CACHE_PUSH` | Envoie les sorties de ce build (`true` par défaut). |
| `ELIDE_REMOTE_CACHE_PULL` | Télécharge les entrées absentes (`true` par défaut). |
| `ELIDE_REMOTE_CACHE_POLICY` | `eager` (par défaut) transfère chaque entrée ; `smart` ne transfère que si cela fait gagner du temps. |

- Le cache local est consulté en premier ; les entrées trouvées à distance sont stockées localement.
- Configuration type : la CI envoie ; les développeurs définissent `ELIDE_REMOTE_CACHE_PUSH=false`.
- Les entrées distantes injoignables, lentes ou illisibles comptent comme absentes. Trois échecs de transport
  consécutifs désactivent le niveau pour le reste du build. Les erreurs HTTP comme `404` ne sont pas des échecs de
  transport ; un identifiant refusé déclenche un seul avertissement.
- Le build échoue sur une URL autre que `http`/`https`, un mot de passe sans nom d'utilisateur, un `PUSH`/`PULL` non
  booléen, ou des identifiants envoyés en `http` non chiffré vers un hôte autre que le loopback.
- Le cache fournit des sorties exécutables : utilisez `https`, exigez une authentification pour les écritures et
  limitez qui peut écrire.
- `--offline` désactive le niveau partagé pour une exécution ; `--no-cache` désactive le cache.

### `.eliderc` et la politique `smart`

Avec `smart`, une entrée n'est téléchargée que si c'est moins coûteux que de reconstruire, et envoyée que si l'envoi
coûte moins que le travail qu'il épargne. Les coûts viennent de `.eliderc` (syntaxe `java.util.Properties`) :
`~/.eliderc`, puis `<project>/.eliderc` par-dessus. Ce fichier décrit la machine : ne le commitez pas.

```properties
# ~/.eliderc
network.downlink = 200mbps
network.uplink = 20mbps
network.latency = 250ms
network.stability = good        # good | fair | poor
machine.compute = fast          # slow | normal | fast, or a multiplier such as 1.5

cache.remote.policy = smart     # smart | eager (default)
cache.remote.upload-budget = 2.0
cache.remote.min-build = 500ms  # work cheaper than this is never published
```

`Mb/s` et `mbps` sont des mégabits ; `MB/s` des mégaoctets. Les valeurs illisibles déclenchent un avertissement et la
valeur par défaut s'applique. `ELIDE_REMOTE_CACHE_POLICY` prime sur `cache.remote.policy`. Avec `eager`, le fichier
n'a aucun effet.

## État du build

| Fichier | Rôle |
| --- | --- |
| `.dev/elide.lock.v2.bin` | Empreintes portables par tâche, partageables entre machines. Ce n'est pas un fichier de verrouillage des dépendances. |
| `.dev/elide.build.bin` | Empreintes par tâche, propres à la machine. |
| `.dev/elide.filehash.bin` | Condensats de fichiers indexés par taille, dates, inode et mode, pour ne pas relire les fichiers inchangés. |

- Fichiers binaires ; ne les modifiez pas.
- Il n'existe pas de fichier de verrouillage des dépendances pour tous les écosystèmes ; npm écrit `aube-lock.yaml`.
- Dans un espace de travail, l'état de tous les membres est stocké dans le `.dev/` de la racine ; les sorties restent
  dans le `.dev/` de chaque projet.
- `--no-cache` ignore le fichier d'état local, mais lit toujours celui qui est partagé.
- `elide install` réutilise la résolution tant que la liste des dépendances ne change pas ; `--fresh` télécharge à
  nouveau toutes les dépendances et rafraîchit le cache global.
- Les arguments de chaque compilateur sont écrits à côté de sa sortie dans `<tool>.args`, un par ligne.

Consultez [Le répertoire .dev](/docs/toolchain/development-directory) pour les fichiers générés, les espaces de travail et le nettoyage.

## Mesurer la durée d'un build

Chaque tâche affiche sa durée. Pour plus de détails :

```bash
elide build -v                                                # everything, at debug
ELIDE_LOG=dev.elide.tooling.build.telemetry=debug elide build # only the timings
```

```text
[debug] dev.elide.tooling.build.telemetry stage graph took 590us
[debug] dev.elide.tooling.build.telemetry op compile-kotlin-main · up-to-date (up-to-date) took 420us
[debug] dev.elide.tooling.build.telemetry task compile-kotlin-main (skipped: up-to-date) took 12.6ms
```

Les régions sont une **étape** (configuration, graphe, exécution, sauvegarde de l'état), une **tâche**, ou une
**opération** sur une tâche (`prepare`, `fingerprint`, `up-to-date`, `execute`, consultations et écritures du cache).
Le travail à l'intérieur de `execute` n'est pas détaillé.

`ELIDE_BUILD_TELEMETRY` écrit une [trace Chrome](https://perfetto.dev/docs/visualization/large-traces) locale à la fin
du build ; rien n'est envoyé :

```bash
ELIDE_BUILD_TELEMETRY=1 elide build             # .dev/telemetry/build-<stamp>.trace.json
ELIDE_BUILD_TELEMETRY=profile.json elide build  # a file you name
ELIDE_BUILD_TELEMETRY=/tmp/traces elide build   # a directory you name
```

Ouvrez-la dans [Perfetto](https://ui.perfetto.dev), `chrome://tracing` ou [speedscope](https://speedscope.app), ou :

```bash
jq -r '.traceEvents[] | select(.ph=="X") | "\(.dur/1000 | floor)ms \(.cat) \(.name)"' \
  .dev/telemetry/build-*.trace.json | sort -rn | head
```

### Observations de restauration et corrélation des sessions

Les serveurs prenant en charge les reçus de restauration Elide peuvent renvoyer `x-elide-recall-receipt`
lorsqu'un téléchargement demande `x-elide-recall: 1`. Après extraction et validation, le client rapporte le résultat
à `outcomes` sous le point d'accès du cache configuré. Télécharger les octets ne suffit pas à compter une
restauration réussie ; les accès locaux suivants ne dupliquent pas le rapport. Le signalement est effectué au mieux
et ne décide pas du succès de la compilation.

`ELIDE_STUDIO_SESSION_ID` fournit des métadonnées bornées de corrélation au cache configuré et à l'origine HTTPS
de Maven Pkgst. Ce n'est pas un identifiant d'accès et cela ne change pas les clés d'action. Les requêtes de cache
authentifiées ou corrélées à une session ne suivent pas les redirections, pour ne pas divulguer ces métadonnées
à une autre origine.

Les rapports incluent la durée initiale de la tâche comme estimation bornée, afin de comparer le coût probable
d'une recompilation au coût mesuré de restauration. Ce n'est ni une mesure de facturation ni une preuve du temps gagné.
