Рабочая область: mx.work

Один модуль — один mx.mod. Сама Mercury состоит из множества модулей, разрабатываемых вместе. Рабочая область позволяет собирать их совместно: каждый участник находит остальные в их каталогах, без промежуточного выпуска версий.

Зачем нужна рабочая область

Без рабочей области модуль, которому нужна ещё не выпущенная правка другого модуля, должен указать это в собственном mx.mod: добавить строку replace с путём к каталогу. Рабочая область задаёт это один раз для всех участников, в файле, который не нужно включать в каждый модуль. Правила взяты из Go: парсер и средство вывода mx.work перенесены из Go go.work с заменой go на mx, а команды mx work — из go work.

Файл

Рабочая область Mercury находится в fiberfx/mx.work. Первые строки:

// The workspace of the eighteen modules: sixteen public, and two private, @fiberfx/hypercompiler and @fiberfx/hyperscript-lsap (hyperscript-lsap.1). Regenerate with mx work use ./*/.
mx 0.1.0

use (
	./analytics
	./cms
	./content
	./core

Блок use продолжается остальными каталогами восемнадцати модулей, по одному на строку, и закрывается ). В mx.work четыре директивы: mx, toolchain, use и replace.

Участник — это каталог, в котором package.json содержит name, как участник рабочей области Go — каталог с go.mod, содержащим строку module. Участник без имени отклоняется: error reading <dir>/package.json: missing name.

Рядом могут находиться два объекта:

• mx.work.sum — контрольные суммы рабочей области. Строка добавляется сюда, только если её ещё нет ни в одном mx.sum участников.
• vendor/ — если его создала команда mx work vendor.

Как mx находит рабочую область

mx ищет рабочую область в следующем порядке:

1. -workfile <path>, если команда принимает этот флаг;
2. MXWORK: off отключает все рабочие области; любое другое значение, кроме auto, должно быть абсолютным путём к файлу, иначе mx отказывает с invalid MXWORK: not an absolute path;
3. ближайший mx.work в текущем каталоге или выше по дереву.

Так, fiberfx/hypergraph входит в рабочую область, потому что выше расположен fiberfx/mx.work. Вне рабочей области команды mx work отказывают:

mx: no mx.work file found
	(run 'mx work init' first or specify path using MXWORK environment variable)

Рабочая область меняет и другие команды. Если у всех участников mx.work есть mx.mod, команды mx install и mx verify работают со всей областью. MXWORK=off оставляет участника самостоятельным.

Команды mx work

usage: mx work edit|use|init|sync|vendor …

Флаги используют один дефис, как в Go: -r или -json. mx также принимает --json и -name=value. Неизвестный флаг отклоняется, например: mx: flag provided but not defined: -nope.

Чтение и правка через mx work edit

mx work edit требует хотя бы один флаг. Без флагов команда отвечает mx: no flags specified (see 'mx work edit').

Чтение без изменений:

• -print выводит файл в том виде, в котором его записал бы mx. При запуске в fiberfx/ вывод побайтово совпадает с fiberfx/mx.work.
• -json выводит JSON: Mx, список Use с DiskPath каждого участника и Selected — выбранные рабочей областью версии.
• Совместное использование -json и -print отклоняется: mx: cannot use both -json and -print.

Правка с записью файла:

• -use <dir> и -dropuse <dir> добавляют или удаляют участника;
• -replace old[@v]=new[@w] и -dropreplace old[@v] добавляют или удаляют replace. Разделитель — =, а не =>; новый путь без версии должен указывать на локальный каталог;
• -mx <version> и -toolchain <name> задают соответствующие строки, а none удаляет их;
• -fmt перезаписывает файл в каноническом формате.

Если вместе с правкой указать -print или -json, mx выведет изменённый файл, но не запишет его. Это позволяет предварительно просмотреть любую правку.

sync и vendor

mx work sync выполняет выбор минимальных версий по mx.mod всех участников, затем повышает версии в строках require каждого участника до выбранных. Разрешение зависимостей всех участников завершается до записи любого файла, поэтому отказ оставляет всю рабочую область без изменений. Lock-файл не читается и не записывается.

mx work vendor [-o outdir] записывает зависимости рабочей области в один каталог, по умолчанию vendor/ рядом с mx.work. Поскольку целевой каталог будет заменён, его безопасность проверяется до чтения любого участника: -o, содержащий рабочую область, её mx.work или участника, отклоняется с refusing to replace <dir>: it holds the workspace.

mx build, mx check, mx run и mx resolve принимают --mod vendor. Любое другое значение отклоняется: mx <command>: --mod <value> is not vendor.