Проєкти TOML

Маніфест проєкту вибирає впорядковані групи вихідних файлів Erlang і незалежно налаштовує кожну ціль. Усі дії CLI приймають проєкти. Див. робочий приклад.

Маніфест (схема 1)

schema_version = 1

[[targets]]
name = "app"
sources = ["main.erl", "src/workers/*.erl", "shared/**/*.erl"]
source_dirs = ["src/support"]
output = "build/app"
entry = "main:main"

[targets.options]
source_search_paths = ["src", "generated"]
include_dirs = ["include", "vendor/include"]
defines = ["DEBUG", "LIMIT=100", 'LABEL="demo"']
enable_features = ["maybe_expr"]
disable_features = ["compr_assign"]

[targets.options.applications]
my_dependency = "vendor/my_dependency"

• Обов'язкові schema_version = 1 і непорожній масив targets. Невідомі ключі, неправильні типи, дублікати назв цілей і порожні рядки відхиляються; неявного перетворення типів немає. Перевіряється весь маніфест, зокрема невибрані цілі.
• Назви цілей: чутливі до регістру ASCII [A-Za-z0-9_][A-Za-z0-9_.-]*, унікальні. Назва — це ціль збирання, а не триплет LLVM.
• sources (файли та шаблони з підстановочними знаками) і source_dirs (рекурсивний пошук .erl) необов'язкові, але цілі потрібен принаймні один запис. Явно задані файли мають закінчуватися на .erl; заголовки — це залежності, а не вхідні дані.
• Поля options — необов'язкові типізовані параметри фронтенду. defines використовують NAME (= true) або NAME=ERLANG_LITERAL_TERM; дублікати є помилками. Можливість не може бути в обох списках можливостей.
• entry (необов'язково) вибирає точку входу виконуваного файлу MODULE[:FUNCTION]; див. виконувані файли. --entry з CLI перевизначає його для однієї вибраної цілі.
• output — місце призначення виконуваного файлу, за замовчуванням <manifest-dir>/build/<target> (.exe у Windows). Ціль з output або entry є виконуваною ціллю (виконувані файли); --emit і режими перевірки/друку ігнорують вивід обох ключів.
• Ще не підтримується: кореневі значення за замовчуванням, успадкування, залежності між цілями, імпорти, профілі, виключення, пакети, стеження, кешування, паралельні збирання. Поля додаються лише разом із їхньою поведінкою.

CLI і вибір цілей

clau [options] <source.erl>...
clau [options] --project <path> [--target <name>]...
clau --new-project <filename>

• Позиційні вихідні файли та --project взаємовиключні. Один --project, будь-яка кількість --target, у будь-якому порядку.
• Без --target: усі цілі в порядку маніфесту. Селектори зберігають свій порядок і перше входження. Невідомі назви дають помилку до будь-якої роботи фронтенду і перелічують доступні назви.
• --project test1 завантажує test1.toml, коли test1 не існує.
• Параметри фронтенду з CLI застосовуються до кожної вибраної цілі. Шляхи з CLI зберігають значення відносно каталогу виклику; шляхи маніфесту задаються відносно маніфесту.
• Без --emit або дії перевірки/друку виконувані цілі компонуються у свої виводи (виконувані файли); інші цілі компілюються в пам'яті.
• -o/--output компонує ціль у вказаний шлях замість її output (компонування); потребує рівно однієї вибраної цілі.
• --verbose трасує файли/включення [pp] і вихідні файли [parse] у stderr.
• Код виходу 2: помилки використання і невідомі цілі. Код виходу 1: невдачі маніфесту, пошуку файлів, фронтенду або створення. Код виходу 0: успіх (попередження дозволені).

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

./build/debug/bin/clau --parse-check --project examples/project/project.toml
./build/debug/bin/clau --print-ast --project examples/project/project.toml --target tests --target app

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

clau --project FILE [--target T]... (без --emit, без дії перевірки/друку) компонує кожну вибрану ціль, що має ключ output або entry або до якої звертаються -o/--entry з CLI, в один виконуваний файл на ціль:

• Місце призначення: -o з CLI (відносно каталогу виклику), інакше output (відносно маніфесту), інакше <manifest-dir>/build/<target>. Для цілей Windows до імені без розширення додається .exe. Відсутні каталоги виводів маніфесту створюються; каталог явного -o має існувати.
• Точка входу: --entry з CLI, entry з маніфесту, інакше автоматичне визначення (вибір точки входу).
• Цілі без output, entry, -o і --entry — це бібліотеки: вони компілюються в пам'яті й нічого не записують, навіть якщо модуль експортує main/1.
• Планування відхиляє вибрані цілі з однаковим місцем призначення; виводи, що збігаються лише після додавання .exe, відхиляються до публікації. Вивід не повинен збігатися з вибраним вихідним файлом або маніфестом.
• Кожна ціль компілюється й компонується у власний проміжний каталог. Виводи замінюються лише після успіху всіх вибраних цілей, у порядку цілей; будь-яка невдача лишає всі наявні виводи без змін. Невдача під час заміни пізнішого виводу може залишити раніші вже заміненими.
• --linker і --runtime-library застосовуються до кожної цілі, що компонується (компонування).

./build/debug/bin/clau --project tests/fixtures/linking/project/project.toml

Створення проєкту

--new-project <filename> записує один анотований маніфест і нічого більше.

• Додає .toml, якщо ім'я ще не закінчується на .toml (без урахування регістру ASCII): demo → demo.toml, demo.config → demo.config.toml.
• Відхиляє порожні імена або імена, схожі на каталоги, повторення і будь-яке поєднання з вихідними файлами, --project, --target, -o, режимами перевірки/друку або параметрами фронтенду.
• Батьківський каталог має існувати. Ніколи не перезаписує (виключне створення); прибирає власний частково записаний файл у разі невдачі запису. У разі успіху друкує шлях створеного файлу.
• Вміст — детермінований UTF-8/LF з коментарями: одна ціль app, sources = [], source_dirs = ["src"], порожні списки параметрів і вивід за замовчуванням для платформи. Він одразу декодується; користувач додає вихідні файли в src.

Шляхи та пошук файлів

• Шлях проєкту розв'язується відносно каталогу виклику; лексичний батьківський каталог маніфесту є базою для всіх шляхів маніфесту (навіть через символьне посилання). Абсолютні шляхи лишаються абсолютними; .. дозволено. Без розгортання оболонки, змінних середовища чи тильди. Для шляхів Windows використовуйте / або буквальні рядки TOML.
• Буквальні відносні вихідні файли спершу шукаються в базі, потім у source_search_paths по порядку. Наявний, але нечитабельний кандидат є помилкою. Шляхи пошуку лише знаходять перелічені файли; вони не перелічують модулі й не впливають на включення.
• Підстановочні знаки: * і ? у межах компонента, ** як цілий компонент. Квадратні та фігурні дужки, заперечення та екранування відхиляються. Зіставлення чутливе до регістру; ? — це одне скалярне значення Unicode дійсного імені UTF-8.
• Приховані записи включаються; знайдені символьні посилання на каталоги пропускаються (явні корені можуть бути символьними посиланнями); символьні посилання на файли розкриваються.
• Порядок: записи sources по порядку, збіги кожного шаблону відсортовано за байтами шляху UTF-8, потім кожне розгортання source_dirs, відсортоване так само. Відсутні буквальні файли, шаблони без збігів і порожні цілі є помилками.
• Усунення дублікатів у межах цілі використовує ідентичність у файловій системі (символьні посилання, жорсткі посилання, псевдоніми за регістром), зберігаючи перше написання. Той самий файл у двох цілях компілюється двічі, бо параметри можуть відрізнятися.
• Лише вибрані цілі звертаються до файлової системи.

Ефективні параметри

Залежність збирання

Приватний для компілятора toml++ 3.4.0 (MIT), лише заголовки, з винятками, невипущений синтаксис вимкнено. SHA-256 архіву 8517f65938a4faae9ccf8ebb36631a38c1cadfb5efa85d9a72e15b9e97d25155.

• macOS: виявляється brew install tomlplusplus (формула 3.4.0).
• Windows: CMake завантажує і перевіряє випуск у thirdparty/.
• Деінде: встановіть його, розпакуйте в thirdparty/tomlplusplus-3.4.0 або передайте -DCLAUSE_TOML_ROOT=<path> (має пріоритет, вимикає завантаження).
• Збирання лише runtime його не шукають.

Обмеження

Розмір маніфесту 1 MiB; щонайбільше 1 024 цілі та 100 000 вузлів TOML. Кожне розгортання вихідних файлів допускає 100 000 відвіданих записів, 128 рівнів каталогів і 16 000 000 переходів підстановочних знаків. Вичерпання є явною помилкою; це межі роботи, а не граничні терміни вводу-виводу.