# Задачи сборки

`elide build` выводит задачи из наборов исходников и артефактов в `elide.pkl` и выполняет их в порядке зависимостей.
Задачи с неизменившимися входными данными пропускаются или восстанавливаются из кеша.

## Запуск сборки

```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
```

Аргумент задаёт задачу или группу; начальное двоеточие (`:compile-java-main`) необязательно. Цель, которой ничего не
соответствует, приводит к ошибке сборки.

| Группа | Псевдоним | Задачи |
| --- | --- | --- |
| `default` | — | То, что выполняет `elide build` без аргументов. |
| `dependencies` | `deps` | Разрешение и установка зависимостей. |
| `compilation` | `compile` | Компиляция исходников. |
| `testing` | `test` | Тесты; их также запускает `elide test`. |

Некоторые задачи принимают параметры; их выводит `--inspect`:

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

В [рабочем пространстве](/docs/elide-pkl-reference#workspaces) добавьте префикс проекта: `core:compile-kotlin-main`,
`core:compile` или `core` для его задач по умолчанию. Цели без префикса ищутся в текущем проекте, затем в корне.
`--inspect` группирует задачи по проектам, а строки прогресса называют проект (`[core] Compiling Kotlin sources`).

Проект может добавлять собственные группы и задачи, в том числе выполняемые перед встроенными:
см. [Расширения сборки](/docs/toolchain/build-extensions).

## Параметры

Параметры записываются как `--name` или `--name=value` в любом месте среди целей. Аргументы после `--` передаются
процессу, который запускает задача.
`--inspect` перечисляет опции всех задач; `elide build <task> --help` описывает опции одной задачи.

| Параметр | Действие |
| --- | --- |
| `--inspect`, `-i` | Вывести задачи и их параметры без запуска. |
| `--no-cache` | Игнорировать кеш и локальное состояние сборки; выполняются все задачи. |
| `--offline` | Без загрузки зависимостей и без общего кеша. |
| `--workers=N` | Не более `N` одновременных задач (по умолчанию — число процессоров). Знак `=` обязателен. |
| `-f NAME[=VALUE]` | Флаг сборки, читается как `build.flags`; см. [Флаги сборки](/docs/toolchain/build-flags). |

Параметры проверяются по задачам до начала выполнения. Неизвестный параметр, отсутствующее или лишнее значение либо
повторённый параметр приводят к ошибке:

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

Глобальные флаги (`-p`, `-v`, `--debug` и другие) не проверяются. Параметры задач:
[Зависимости](/docs/toolchain/dependencies#maven-options), [Тестирование](/docs/toolchain/testing#options).

## Кеш сборки

**Локальный** уровень включён всегда: `~/.elide/cache/entries-v2`, по одному каталогу на ключ с записью и tar-архивом
результатов. При восстановлении проверяется записанный отпечаток. Записи в старом формате считаются промахом.

**Общий** уровень — это HTTP-кеш, который настраивается переменными окружения:

| Переменная | Назначение |
| --- | --- |
| `ELIDE_REMOTE_CACHE` | URL конечной точки. Не задана — общего уровня нет. |
| `ELIDE_REMOTE_CACHE_TOKEN` | Bearer-токен; имеет приоритет над базовой аутентификацией. |
| `ELIDE_REMOTE_CACHE_USERNAME`, `ELIDE_REMOTE_CACHE_PASSWORD` | Базовая аутентификация; данные пользователя в URL тоже работают. |
| `ELIDE_REMOTE_CACHE_PUSH` | Выгружать результаты этой сборки (по умолчанию `true`). |
| `ELIDE_REMOTE_CACHE_PULL` | Загружать при промахе (по умолчанию `true`). |
| `ELIDE_REMOTE_CACHE_POLICY` | `eager` (по умолчанию) передаёт каждую запись; `smart` — только когда это экономит время. |

- Сначала проверяется локальный кеш; попадания в удалённом кеше сохраняются локально.
- Типичная настройка: CI выгружает, разработчики задают `ELIDE_REMOTE_CACHE_PUSH=false`.
- Недоступные, медленные или нечитаемые удалённые записи считаются промахами. Три сбоя транспорта подряд отключают
  уровень до конца сборки. Ошибки HTTP, например `404`, сбоями транспорта не считаются; об отклонённых учётных данных
  выводится одно предупреждение.
- Сборка завершается ошибкой при URL со схемой, отличной от `http`/`https`, пароле без имени пользователя,
  небулевом `PUSH`/`PULL` или учётных данных по незашифрованному `http` к хосту, отличному от loopback.
- Кеш отдаёт исполняемые результаты: используйте `https`, требуйте аутентификацию для записи и ограничьте круг тех,
  кто может записывать.
- `--offline` отключает общий уровень на один запуск; `--no-cache` отключает кеширование.

### `.eliderc` и политика `smart`

При `smart` запись загружается, только если это дешевле повторной сборки, и выгружается, только если выгрузка обходится
дешевле, чем работа, которую она экономит. Стоимость берётся из `.eliderc` (синтаксис `java.util.Properties`):
`~/.eliderc`, поверх него `<project>/.eliderc`. Файл описывает машину, поэтому не добавляйте его в репозиторий.

```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` и `mbps` — мегабиты; `MB/s` — мегабайты. Для нечитаемых значений выводится предупреждение и используется
значение по умолчанию. `ELIDE_REMOTE_CACHE_POLICY` переопределяет `cache.remote.policy`. При `eager` файл ни на что не
влияет.

## Состояние сборки

| Файл | Роль |
| --- | --- |
| `.dev/elide.lock.v2.bin` | Переносимые отпечатки задач, которые можно использовать на разных машинах. Это не lock-файл зависимостей. |
| `.dev/elide.build.bin` | Отпечатки задач, локальные для машины. |
| `.dev/elide.filehash.bin` | Хеши файлов с ключом по размеру, времени, inode и режиму, чтобы не перечитывать неизменённые файлы. |

- Двоичные файлы; не редактируйте их.
- Единого lock-файла зависимостей для всех экосистем нет; npm записывает `aube-lock.yaml`.
- В рабочем пространстве состояние всех участников хранится в `.dev/` корня; результаты остаются в `.dev/` каждого
  проекта.
- `--no-cache` игнорирует локальный файл состояния, но по-прежнему читает общий.
- `elide install` повторно использует разрешение, пока список зависимостей не меняется; `--fresh` заново загружает
  все зависимости, обновляя глобальный кеш.
- Аргументы каждого компилятора записываются рядом с его результатом в `<tool>.args`, по одному на строку.

О сгенерированных файлах, рабочих пространствах и очистке см. [Каталог .dev](/docs/toolchain/development-directory).

## Замер времени сборки

Каждая задача выводит свою длительность. Подробнее:

```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
```

Участок — это **этап** (конфигурация, граф, выполнение, сохранение состояния), **задача** или **операция** над задачей
(`prepare`, `fingerprint`, `up-to-date`, `execute`, поиск и запись в кеше). Работа внутри `execute` не детализируется.

`ELIDE_BUILD_TELEMETRY` по завершении сборки записывает локальную
[трассировку Chrome](https://perfetto.dev/docs/visualization/large-traces); ничего не выгружается:

```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
```

Откройте её в [Perfetto](https://ui.perfetto.dev), `chrome://tracing` или [speedscope](https://speedscope.app) либо
выполните:

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

### Наблюдения восстановления и корреляция сеансов

Серверы, поддерживающие квитанции восстановления Elide, могут возвращать `x-elide-recall-receipt`, если загрузка
архива запрашивает `x-elide-recall: 1`. После распаковки и проверки клиент сообщает результат в `outcomes` под
настроенной конечной точкой кеша. Одна загрузка байтов не считается успешным восстановлением; последующие локальные
попадания не дублируют сообщение. Отчёт отправляется по возможности и не определяет успех сборки.

`ELIDE_STUDIO_SESSION_ID` передаёт ограниченные метаданные корреляции запросов настроенному кешу сборки и HTTPS-источнику
Maven Pkgst. Это не учётные данные, и ключи действий не меняются. Аутентифицированные или связанные с сеансом
запросы кеша не следуют перенаправлениям, чтобы метаданные не попали на другой источник.

Отчёты включают исходную длительность задачи как ограниченную оценку для сравнения вероятной стоимости повторной
сборки с измеренной стоимостью восстановления. Эта оценка не является данными для оплаты или доказательством экономии времени.
