Виконувані файли

Контракт для програм, зібраних через clau -o або збіркою проєкту. Позиційні вхідні файли або рівно одна обрана ціль проєкту компонуються в шлях -o; збірка проєкту компонує кожну обрану ціль-виконуваний файл у її output з маніфесту (компонування, проєкти).

Вибір точки входу

Точка входу — це експортована функція арності 1, що отримує список аргументів.

• FUNCTION типово дорівнює main. Імена — це текст атома без лапок: 1–255 скалярних значень Unicode, коректний UTF-8, без керівних символів і без :. Інші записи — це помилки використання (CLI, код виходу 2) або помилки маніфесту (код виходу 1).
• entry — необов'язковий ключ схеми 1; старіші маніфести лишаються дійсними. Маніфест декодується повністю, тож некоректний entry дає збій навіть у необраних цілях.
• --entry у CLI перевизначає ключ маніфесту й вимагає рівно однієї обраної цілі. Він конфліктує з діями перевірки/друку та --new-project; ці дії ігнорують entry маніфесту (як ігнорують output).
• Явна точка входу перевіряється в кожному режимі компіляції (типовому, --emit, інспекції IR/типів) разом зі звичайною семантичною діагностикою.

Для цілей проєкту підказка також називає ключ маніфесту: ... --entry MODULE[:FUNCTION] or with entry = "MODULE[:FUNCTION]" in this target's [[targets]] table of the project manifest ..., наприклад:

[[targets]]
name = "app"
sources = ["src/*.erl"]
entry = "app:start"   # calls app:start/1; plain "app" calls app:main/1

Аргументи

Entry(Argv) отримує правильний список рядків (списків кодових точок Unicode) без імені програми й початкових опцій runtime, в іншому незмінних і в тому самому порядку, як escript.

• POSIX: байти кожного аргументу декодуються як UTF-8; байт, що не починає коректної послідовності, стає кодовою точкою цього байта (запасний варіант Latin-1).
• Windows: широкий (UTF-16) вектор аргументів CRT, розбитий за тими самими правилами, що й argv; непарний сурогат стає U+FFFD.
• Жодного іншого розбору опцій, розгортання шаблонів (globbing) чи змінних середовища runtime не виконує.

Опції runtime

Runtime читає свої опції зі змінної середовища CLAUSE_FLAGS (слова розділено пробілами й табуляціями, без лапок), а потім із початкових аргументів командного рядка, тож командний рядок має перевагу. Обидва розбираються однаково; значення йде в наступному аргументі або після =.

У командному рядку розбір зупиняється на першому аргументі, що не є опцією runtime, тож prog data --max-atoms 9 передає програмі всі три аргументи. У CLAUSE_FLAGS кожне слово має бути опцією runtime. Недійсне значення, слово в змінній, що не є опцією, або --args-file зупиняють програму до реєстрації будь-якого модуля: clau: runtime failure: <reason>, код виходу 70. Кількість процесів не обмежена, а пам'ять типово не має обмеження. Значення в байтах десяткові без суфіксів і округлюються донизу до цілих слів; програма, що досягає обмеження, завершується збоєм resource_limit, код виходу 70 (обмеження пам'яті runtime).

Статус виходу

Недійсні аргументи halt/1 породжують badarg у того, хто викликає. Коли точка входу завершується, програма виходить: інші процеси зупиняються без подальшого виконання, як із halt/1 в OTP після повернення з escript. Halt у будь-якому процесі завершує програму з його статусом, а збій runtime у будь-якому процесі завершує її з 70; виняток у запущеному процесі завершує лише цей процес (процеси).

halt/0,1, error/1,2,3, exit/1 і throw/1 можна викликати з префіксом erlang: або без нього; локальне визначення чи -compile({no_auto_import, ...}) залишає некваліфіковане ім'я локальним, як в OTP. halt/2 недоступна. halt(N) зберігає молодші 31 біт будь-якого невід'ємного цілого числа, як OTP. Гасло (slogan) — це правильний список щонайбільше з 1 023 кодових точок Unicode. Halt розмотує точку входу через перевірений канал помилок, як помилку, тож зупиняє програму лише після згенерованого прибирання.

Потоки виводу

• stdout: вивід standard_io (io:format/1,2, io:put_chars/1, erlang:display/1). Буферизований; скидається на кожному шляху виходу, окрім abort.
• stderr: звіт про неперехоплений виняток, вивід standard_error, збої runtime і звіти про помилки інших процесів, що аварійно завершилися (процеси).
• Звіт — це один рядок uncaught exception <class>: <reason in ~w form>, за яким пізніше йдуть фрейми стека (крок 15). Його точний текст не є стабільним інтерфейсом; тести зіставляють його за шаблоном.

Об'єкт запуску

Компіляція з явною точкою входу (--entry або entry маніфесту) додає модуль запуску після модулів пакета. З --emit він публікується як clausev1_start.{obj,o,ll,bc} поряд з артефактами модулів (ім'я не може збігтися з артефактом модуля). Він містить сталий abi::v1::StartupDescriptor (startup.hpp): ревізію ABI, ширину терма, кожен дескриптор модуля в порядку джерел, записи модуля/функції точки входу та прапорець escript. Його int main(int, char **) викликає CLAUSE_main_v1 з runtime, яка:

1. Перевіряє дескриптор запуску й кожен дескриптор модуля на ревізію ABI та ширину до реєстрації будь-чого; невідповідність дає код виходу 70.
2. Запускає runtime і реєструє всі модулі; будь-який збій зупиняє все до точки входу й відкидає runtime (код виходу 70), тож жоден код Erlang не виконується з неповним пакетом.
3. Створює процес точки входу, будує argv і ставить виклик M:F/1 у чергу як головний процес, потім виконує його й кожен процес, який він запускає, на кооперативному виконавці (процеси), доки той не завершиться.
4. Відображає результат на статус виходу вище, друкуючи звіти після скидання stdout, потім звільняє кожен процес і завершує роботу runtime на кожному шляху (окрім halt(abort)).

clau -o компонує ці об'єкти сам (компонування). Ручне компонування (рецепт нативної обв'язки без вихідного файлу обв'язки):

& $tool --emit obj --entry app --artifact-dir build/app app.erl helper.erl
clang-cl /MT build/app/*.obj build/debug/lib/clause_runtime.lib /Fe:app.exe

Будь-яке Clang-сумісне компонування об'єктів із Clause::generated_program працює так само (див. tests/compiler/linking/startup.cmake).

Компонування

clau [-O0|-O2|-Os] -o PATH a.erl b.erl ... (або --project FILE [--target T] -o PATH для однієї обраної цілі) компілює пакет у пам'яті, додає об'єкт запуску для точки входу і компонує виконуваний файл:

clau -O2 -o build/demo examples/compile/answer.erl examples/compile/client.erl
./build/demo          # build/demo.exe on Windows

-Os додатково розміщує кожну згенеровану функцію й функцію runtime та кожен об'єкт даних в окремій секції й компонує з --gc-sections (ELF), -dead_strip (Mach-O) або /OPT:REF /OPT:ICF (MSVC), тож код, якого не досягає жоден шлях від точки входу, видаляється.

• PATH відносний щодо місця виклику. Для цілей Windows до імені файлу без розширення додається .exe. Його каталог має існувати.
• Компонувальник: --linker PATH (шлях чи ім'я програми), інакше clang++ або clang з PATH, потім (Windows) %ProgramFiles%/LLVM/bin. Він запускається як <clang> --driver-mode=g++ --target=<triple> -o <staged> <objects> <runtime>, тож Clang обирає компонувальник платформи й бібліотеки runtime C/C++ (на Windows він сам знаходить MSVC і SDK; оболонка розробника не потрібна).
• Runtime: --runtime-library PATH, інакше архів clause_runtime зі збірки, що створила clau (шлях записано відносно виконуваного файлу, наприклад bin/../lib/clause_runtime.lib). Кожен нативний об'єкт в архіві має відповідати архітектурі й формату об'єктів цілі; тому --target-triple для іншої цілі потребує runtime, зібраного для неї.
• Об'єкти й виконуваний файл готуються в приватному каталозі .clause-link-* поряд із виводом, який потім видаляється. Вивід замінюється лише після успішного компонування, тож за будь-якого збою наявний файл лишається без змін. Вивід не може бути каталогом або псевдонімом вхідного файлу.
• Попередження компонувальника передаються в stderr; --linker і --runtime-library вимагають --output або збірки проєкту з компонуванням.
• Збірки проєкту без -o компонують кожну обрану ціль, що має output чи entry, у її вивід із маніфесту, створюючи відсутні каталоги, і замінюють виводи лише після того, як усі обрані цілі скомпоновано (проєкти).

Escript

Вихідний файл, перший рядок якого починається з #!, компілюється як escript у будь-якому режимі й з будь-яким ім'ям файлу (позиційні вхідні файли чи файли .erl проєкту). Правила відповідають escript з OTP 29 для скриптів у вихідних кодах:

• Рядок #! ігнорується. Необов'язковий коментар у рядку 2 і рядок емулятора %%! (рядок 2 або рядок 3 після коментаря) є коментарями; аргументи %%! не можуть застосовуватися до скомпільованого коду й дають попередження.
• Якщо перша форма не -module(...), модулем стає <file name with '.' replaced by '_'>__escript (включно з ?MODULE). OTP додає суфікс із часовою міткою/унікальним значенням; Clause зберігає ім'я детермінованим. Синтезоване оголошення займає рядок 1, тож номери подальших рядків не змінюються.
• main/1 обов'язкова (escript does not define main/1) і неявно експортується; інші функції підлягають звичайним правилам експорту.
• -mode(compile | interpret | debug | native) приймається й ігнорується; інші значення є помилками. Поза escript -mode лишається непідтримуваним.
• Точка входу: без --entry єдиний escript у пакеті є точкою входу (він має перевагу над модулями, що експортують main/1); кілька escript дають неоднозначність.
• Статус виходу як в escript OTP: виняток, що виходить за межі точки входу escript, дає код виходу 127 з escript: exception <class>: <reason> у stderr; інші рядки таблиці статусів виходу застосовуються без змін.
• Файли без #! — звичайні модулі. (escript file.erl в OTP пропустив би їхній перший рядок; Clause цього не робить.) Попередньо скомпільовані escript у вигляді beam і архівів не підтримуються.

Порівняння з OTP

Еталони для фікстур програм виконують точку входу під OTP за тими самими правилами (оракул); той самий оракул генерує еталонні випадки виконуваних файлів, які наскрізний запускач компонує й виконує за кожної політики. Відмінності від escript для звичайних модулів: неперехоплені винятки дають код виходу 1 замість 127, і main/1 має бути експортована. Вихідні коди escript зберігають правила OTP (див. вище).