# Native Image

Native Image заранее компилирует JVM-приложение в автономный исполняемый файл или разделяемую библиотеку.

## Компиляция из командной строки

```bash
elide native-image -- -cp app.jar com.example.Main
```

Аргументы компилятора указываются после `--`; `elide native-image -- --help` выводит их список. Рефлексии, ресурсам,
JNI и прокси нужны метаданные достижимости. Для финальной компоновки на хосте нужен инструментарий C.

## Артефакт проекта

```pkl
amends "elide:project.pkl"
import "elide:Jvm.pkl" as Jvm
import "elide:NativeImage.pkl" as Native

artifacts {
  ["app-jar"] = new Jvm.Jar {
    sources { "main" }
  }
  ["app"] = new Native.NativeImage {
    from { "app-jar" }
    entrypoint = "com.example.Main"
    type = "binary"
    options {
      optimization = "2"
      flags { "-H:+ReportExceptionStackTraces" }
    }
  }
}
```

| Свойство | Назначение | По умолчанию |
| --- | --- | --- |
| `from` | Ключи JAR-артефактов (не пути); пустое значение означает все объявленные JAR или JAR с классами проекта. | нет |
| `name` | Имя выходного файла. | имя проекта |
| `entrypoint` | Главный класс. | `jvm.main` |
| `moduleName` | Модуль запуска для модульных JAR; см. ниже. | модуль, содержащий точку входа |
| `type` | `"binary"` (исполняемый файл) или `"library"` (разделяемая библиотека). | `"binary"` |
| `options` | Параметры компилятора; см. ниже. | — |
| `dependsOn` | Артефакты, которые собираются первыми. | нет |

Результат записывается в `.dev/artifacts/native-image/`, итоговые аргументы — в `native-image.args`.

### Параметры компилятора

| Свойство `options` | Назначение | По умолчанию |
| --- | --- | --- |
| `optimization` | `"auto"`, `"b"` (быстрая сборка), `"s"`, `"0"` … `"4"`. | `"auto"` |
| `driverMode` | `"embedded"` (компилятор Elide) или `"external"` (`native-image` из `GRAALVM_HOME`/`JAVA_HOME`). | `"embedded"` |
| `verbose` | Подробный вывод компилятора. | `false` |
| `linkAtBuildTime.enabled` | Компоновать всё во время сборки. | `true` |
| `linkAtBuildTime.packages` | Пакеты, компонуемые во время сборки, когда `enabled` равно `false`. | нет |
| `classInit.default` | Инициализация классов по умолчанию: `"buildtime"` или `"runtime"`. | `"buildtime"` |
| `classInit.buildtime`, `classInit.runtime` | Классы или пакеты, инициализируемые во время сборки или выполнения. | нет |
| `exclusions.all` | Координаты, исключаемые из обоих путей. | собственные JAR компилятора |
| `exclusions.classpath`, `exclusions.modulepath` | Координаты, исключаемые из одного пути. | нет |
| `pgo.enabled` | Применять профили, если они есть. | `true` |
| `pgo.profiles` | Файлы профилей. | нет |
| `pgo.instrument` | Собрать инструментированный образ, записывающий профили. | `false` |
| `pgo.sampling` | Использовать сэмплирующие профили. | `false` |
| `pgo.autoprofile` | Функции автопрофилирования. | `false` |
| `features` | Включаемые классы функций компилятора. | нет |
| `flags` | Дополнительные флаги `native-image`; изменение файла, указанного во флаге, запускает пересборку. | нет |
| `cflags`, `ldflags` | Дополнительные флаги компилятора C и компоновщика. | нет |
| `defs` | Системные свойства для сборки образа. | нет |

Блок верхнего уровня `nativeImage { }` принимает те же параметры, но не применяет их; задавайте `options` каждого
артефакта.

### Модульные приложения

Если JAR из `from` содержит `module-info.class`:

- Модульные JAR и группа `dependencies.maven.modules` попадают в `--module-path` с
  `--add-modules=ALL-MODULE-PATH`; всё остальное остаётся в classpath.
- Бинарный файл запускается с `--module <module>/<entrypoint>`, используя `moduleName` или модуль, содержащий точку
  входа.
- Точка входа вне модулей собирается из classpath.

Без модульных JAR `moduleName` ни на что не влияет.

## Компиляция в WebAssembly

Объявите артефакт `WebImage` или передайте `--tool:wasm-gc` / `--tool:wasm-lm`; см. [WebImage](/docs/toolchain/jvm/webimage).
Чтобы запустить готовый WASM, см. [WebAssembly](/docs/wasm). Нативный образ может быть входными данными для
[образа контейнера](/docs/toolchain/jvm/containers).
