Merge branch 'main' into feature/current-getting-startedfeature/current-getting-started

5 files changed, 286 insertions, 35 deletions

diff --git a/frontend/src/content/landing.ts b/frontend/src/content/landing.ts
index 553e9f1..c12eb4b 100644
--- a/frontend/src/content/landing.ts
+++ b/frontend/src/content/landing.ts
@@ -26,8 +26,7 @@ export type LandingText = {
 };
 
 // The Tala samples are the programs of Examples/ in the compiler repository, from the namespace line on; a test
-// compares them. Each sample on these pages was built and run with talac 0.6.0, and the terminal samples are
-// what it printed.
+// compares them. The terminal samples are what talac 0.2.0 printed on Windows, the LLVM IR included.
 export const helloWorld = `namespace Examples.HelloWorld;
 
 public class HelloWorld {
@@ -138,7 +137,7 @@ talac: compiler artifact 'GCD.tala' is valid through its requested pipeline boun
 talac: wrote 'GCD.talameta'
 $ cat GCD.talameta
 talameta 1
-compiler 0.6.0
+compiler 0.2.0
 entry Examples.GCD.GCD
 input GCD.tala`;
 const talacStages = `$ talac GCD.tala --entry=Examples.GCD.GCD --emit=core
diff --git a/frontend/src/content/talac.ts b/frontend/src/content/talac.ts
index 88ce7a3..b920184 100644
--- a/frontend/src/content/talac.ts
+++ b/frontend/src/content/talac.ts
@@ -10,11 +10,19 @@ const program = `talac Main.tala Helper.tala --entry=Demo.Program`;
 const check = `talac Helper.tala --emit=metadata`;
 const warnings = `talac Program.tala --entry=Demo.Program --warnings=all,shadow
 talac Program.tala --entry=Demo.Program --warnings=all --warnings=shadow`;
+const incremental = `talac Sources/*.tala --entry=Demo.Program --incremental=.objects
+talac: linked native executable 'Sources/Main.exe', 1 of 13 sources recompiled`;
+const testBuild = `talac Sources/Math.tala Tests/MathTests.tala --test
+PASS Math.Adds
+Tests/MathTests.tala:9:9: expectation failed: Math.Clamp(50, 0, 10) == 9
+    Math.Clamp(50, 0, 10) is 10
+FAIL Math.Clamps (1 failed expectation)
+2 tests, 1 passed, 1 failed`;
 const stages = `talac Main.tala --entry=Demo.Program --emit=xpp
 talac Main.xpp --build=xpp --emit=xmm
 talac Main.xmm --build=xmm --emit=llvm-ir`;
 const record = `talameta 1
-compiler 0.6.0
+compiler 0.2.0
 entry Demo.Program
 input Sources/Main.tala
 input Sources/Helper.tala`;
@@ -25,6 +33,9 @@ const optionTerms = (d: {
   entry: string;
   standard: string;
   target: string;
+  sysroot: string;
+  incremental: string;
+  staticRuntime: string;
   werror: string;
   warnings: string;
   backend: string;
@@ -34,21 +45,26 @@ const optionTerms = (d: {
   emit: string;
   build: string;
   type: string;
+  test: string;
 }) => [
   { term: "--version, -v", detail: d.version },
   { term: "--help, -h", detail: d.help },
   { term: "--entry=Namespace.Class", detail: d.entry },
   { term: "--standard=26", detail: d.standard },
   { term: "--target=<triple>, -t<triple>", detail: d.target },
+  { term: "--sysroot=<path>", detail: d.sysroot },
+  { term: "--incremental=<directory>", detail: d.incremental },
+  { term: "--static-talart-library=true|false", detail: d.staticRuntime },
   { term: "--warnings-as-errors=true|false", detail: d.werror },
   { term: "--warnings=none|low|medium|all[,shadow]", detail: d.warnings },
   { term: "--codegen-backend=llvm", detail: d.backend },
-  { term: "--opt-level=0|1|2|3|g, -O2", detail: d.opt },
+  { term: "--opt-level=0|1|2|3|g|s|z, -O2", detail: d.opt },
   { term: "--llvm-compiler, --llvm-lto, --llvm-args", detail: d.llvm },
   { term: "--xpp-optimization-passes, --xmm-optimization-passes", detail: d.passes },
   { term: "--emit=…", detail: d.emit },
   { term: "--build=…", detail: d.build },
   { term: "--vipkg-type=executable|staticlib|cdylib|talalib", detail: d.type },
+  { term: "--test", detail: d.test },
 ];
 
 const commandLine: DocTopic = {
@@ -80,6 +96,10 @@ const commandLine: DocTopic = {
           entry: "The class whose parameterless public static void Main() starts the program.",
           standard: "The language standard. 26 is the only one and the default.",
           target: "An LLVM target triple. The default is the target of the host.",
+          sysroot: "The system root of the target, for what the build links.",
+          incremental: "A directory that keeps one object per source between builds.",
+          staticRuntime: "Links TalaRT into the output instead of beside it. Default false.",
+          test: "Builds the runner of the [Fact] methods instead of a program.",
           werror: "Turns warnings into errors. Default false.",
           warnings: "The warning level, default medium, and the shadow warning.",
           backend: "The code generator. LLVM is the only one.",
@@ -97,6 +117,18 @@ const commandLine: DocTopic = {
         text: "--entry is required when anything is built from Tala sources, and it cannot be written for a library. An artifact input already carries its entry. A check builds nothing, so one source can be checked without an entry; several sources are one program and still need it.",
       },
       { kind: "code", code: check },
+      { kind: "heading", text: "Incremental builds" },
+      {
+        kind: "text",
+        text: "--incremental builds an executable from one object per source and keeps the objects in the directory. The next build lowers only the sources whose object would differ: a comment changes nothing, a changed body recompiles its source, and a changed signature also recompiles the sources that call it. LLVM optimizes each source alone, so use it for development builds rather than for releases.",
+      },
+      { kind: "code", code: incremental },
+      { kind: "heading", text: "Test builds" },
+      {
+        kind: "text",
+        text: "--test builds a program that runs the [Fact] methods and reports each one. #expect checks a value inside a test. Tazel does this for each test suite.",
+      },
+      { kind: "code", code: testBuild },
       { kind: "heading", text: "Warnings" },
       {
         kind: "text",
@@ -138,6 +170,10 @@ const commandLine: DocTopic = {
           entry: "Die Klasse, deren parameterloses public static void Main() das Programm startet.",
           standard: "Der Sprachstandard. 26 ist der einzige und die Vorgabe.",
           target: "Ein LLVM-Target-Triple. Vorgabe ist das Ziel des Hosts.",
+          sysroot: "Das Systemverzeichnis des Ziels für das, was der Build linkt.",
+          incremental: "Ein Verzeichnis, das zwischen Builds ein Objekt pro Quelle aufbewahrt.",
+          staticRuntime: "Linkt TalaRT in die Ausgabe statt daneben. Vorgabe false.",
+          test: "Baut den Runner der [Fact]-Methoden statt eines Programms.",
           werror: "Macht Warnungen zu Fehlern. Vorgabe false.",
           warnings: "Die Warnstufe, Vorgabe medium, und die Shadow-Warnung.",
           backend: "Der Codegenerator. LLVM ist der einzige.",
@@ -156,6 +192,18 @@ const commandLine: DocTopic = {
         text: "--entry ist nötig, sobald aus Tala-Quellen etwas gebaut wird, und darf für eine Bibliothek nicht angegeben werden. Ein Artefakt bringt seinen Einstieg schon mit. Eine Prüfung baut nichts, daher kann eine einzelne Quelle ohne Einstieg geprüft werden; mehrere Quellen sind ein Programm und brauchen ihn weiterhin.",
       },
       { kind: "code", code: check },
+      { kind: "heading", text: "Inkrementelle Builds" },
+      {
+        kind: "text",
+        text: "--incremental baut eine ausführbare Datei aus einem Objekt pro Quelle und bewahrt die Objekte im Verzeichnis auf. Der nächste Build übersetzt nur die Quellen, deren Objekt sich ändern würde: Ein Kommentar ändert nichts, ein geänderter Rumpf übersetzt seine Quelle neu, und eine geänderte Signatur auch die Quellen, die sie aufrufen. LLVM optimiert jede Quelle für sich, nutzen Sie es also für Entwicklungs-Builds und nicht für Releases.",
+      },
+      { kind: "code", code: incremental },
+      { kind: "heading", text: "Test-Builds" },
+      {
+        kind: "text",
+        text: "--test baut ein Programm, das die [Fact]-Methoden ausführt und jede meldet. #expect prüft einen Wert innerhalb eines Tests. Tazel macht das für jede Testsuite.",
+      },
+      { kind: "code", code: testBuild },
       { kind: "heading", text: "Warnungen" },
       {
         kind: "text",
@@ -197,6 +245,10 @@ const commandLine: DocTopic = {
           entry: "Класс, чей метод public static void Main() без параметров запускает программу.",
           standard: "Стандарт языка. 26 — единственный и значение по умолчанию.",
           target: "Целевая тройка LLVM. По умолчанию — платформа системы.",
+          sysroot: "Системный каталог цели для того, что компонует сборка.",
+          incremental: "Каталог, в котором между сборками хранится по объекту на исходник.",
+          staticRuntime: "Встраивает TalaRT в результат, а не кладёт рядом. По умолчанию false.",
+          test: "Собирает запускающую программу методов [Fact] вместо обычной программы.",
           werror: "Превращает предупреждения в ошибки. По умолчанию false.",
           warnings: "Уровень предупреждений, по умолчанию medium, и предупреждение shadow.",
           backend: "Генератор кода. LLVM — единственный.",
@@ -214,6 +266,18 @@ const commandLine: DocTopic = {
         text: "--entry обязателен, когда что-либо собирается из исходников Tala, и его нельзя указывать для библиотеки. Артефакт уже содержит свою точку входа. Проверка ничего не собирает, поэтому один исходник можно проверить без точки входа; несколько исходников — это одна программа, и им она по-прежнему нужна.",
       },
       { kind: "code", code: check },
+      { kind: "heading", text: "Инкрементальные сборки" },
+      {
+        kind: "text",
+        text: "--incremental собирает исполняемый файл из отдельных объектов для каждого исходника и хранит их в каталоге. Следующая сборка обрабатывает только исходники, чей объект изменился бы: комментарий ничего не меняет, изменённое тело перекомпилирует свой исходник, а изменённая сигнатура — ещё и исходники, которые её вызывают. LLVM оптимизирует каждый исходник отдельно, поэтому это подходит для разработки, а не для релизов.",
+      },
+      { kind: "code", code: incremental },
+      { kind: "heading", text: "Тестовые сборки" },
+      {
+        kind: "text",
+        text: "--test собирает программу, которая выполняет методы [Fact] и сообщает о каждом. #expect проверяет значение внутри теста. Tazel делает это для каждого набора тестов.",
+      },
+      { kind: "code", code: testBuild },
       { kind: "heading", text: "Предупреждения" },
       {
         kind: "text",
@@ -254,6 +318,10 @@ const commandLine: DocTopic = {
           entry: "המחלקה שה-public static void Main() שלה, ללא פרמטרים, מתחיל את התוכנית.",
           standard: "תקן השפה. 26 הוא היחיד וברירת המחדל.",
           target: "משולש מטרה של LLVM. ברירת המחדל היא המטרה של המערכת.",
+          sysroot: "שורש המערכת של המטרה, עבור מה שהבנייה מקשרת.",
+          incremental: "תיקייה ששומרת אובייקט אחד לכל קובץ מקור בין בניות.",
+          staticRuntime: "מקשר את TalaRT לתוך הפלט במקום לצידו. ברירת מחדל false.",
+          test: "בונה את מריץ שיטות ה-[Fact] במקום תוכנית.",
           werror: "הופך אזהרות לשגיאות. ברירת מחדל false.",
           warnings: "רמת האזהרות, ברירת מחדל medium, ואזהרת shadow.",
           backend: "מחולל הקוד. LLVM הוא היחיד.",
@@ -271,6 +339,18 @@ const commandLine: DocTopic = {
         text: "‎--entry נדרש בכל בנייה מקבצי Tala, ואי אפשר לכתוב אותו עבור ספרייה. תוצר כבר נושא את נקודת הכניסה שלו. בדיקה אינה בונה דבר, ולכן אפשר לבדוק קובץ מקור אחד בלי נקודת כניסה; כמה קבצים הם תוכנית אחת ועדיין זקוקים לה.",
       },
       { kind: "code", code: check },
+      { kind: "heading", text: "בניות מצטברות" },
+      {
+        kind: "text",
+        text: "‎--incremental בונה קובץ הרצה מאובייקט אחד לכל קובץ מקור ושומר את האובייקטים בתיקייה. הבנייה הבאה מעבדת רק קבצים שהאובייקט שלהם היה משתנה: הערה אינה משנה דבר, גוף שהשתנה מהדר מחדש את הקובץ שלו, וחתימה שהשתנתה מהדרת מחדש גם את הקבצים שקוראים לה. ‏LLVM מבצע אופטימיזציה לכל קובץ בנפרד, ולכן זה מתאים לפיתוח ולא לגרסאות.",
+      },
+      { kind: "code", code: incremental },
+      { kind: "heading", text: "בניות בדיקה" },
+      {
+        kind: "text",
+        text: "‎--test בונה תוכנית שמריצה את שיטות ה-[Fact] ומדווחת על כל אחת. ‏#expect בודק ערך בתוך בדיקה. ‏Tazel עושה זאת עבור כל חבילת בדיקה.",
+      },
+      { kind: "code", code: testBuild },
       { kind: "heading", text: "אזהרות" },
       {
         kind: "text",
diff --git a/frontend/src/content/talafmt.ts b/frontend/src/content/talafmt.ts
index 6d549ca..021b758 100644
--- a/frontend/src/content/talafmt.ts
+++ b/frontend/src/content/talafmt.ts
@@ -5,7 +5,7 @@ import type { Locale } from "../locales";
 import type { LandingText, WhyTab } from "./landing";
 import type { DocRoute, DocTopic } from "./types";
 
-// talafmt.tala.run. The facts follow the README of Progmasoft/talafmt, version 0.1.0; commands are the same in every
+// talafmt.tala.run. The facts follow the README of Progmasoft/talafmt; commands are the same in every
 // language and only the prose is translated.
 const inPlace = `talafmt Program.tala Library.tala`;
 const check = `talafmt --check Program.tala Library.tala`;
@@ -332,8 +332,8 @@ const layout: DocTopic = {
       },
       {
         kind: "note",
-        title: "Version 0.1.0",
-        text: "talafmt accepts what the compiler it is built with accepts; version 0.1.0 is built with the compiler of Tala 0.1.0.",
+        title: "Compiler",
+        text: "talafmt accepts what the compiler it is built with accepts.",
       },
     ],
   },
@@ -362,8 +362,8 @@ const layout: DocTopic = {
       },
       {
         kind: "note",
-        title: "Version 0.1.0",
-        text: "talafmt akzeptiert, was der Compiler akzeptiert, mit dem es gebaut ist; Version 0.1.0 ist mit dem Compiler von Tala 0.1.0 gebaut.",
+        title: "Compiler",
+        text: "talafmt akzeptiert, was der Compiler akzeptiert, mit dem es gebaut ist.",
       },
     ],
   },
@@ -392,8 +392,8 @@ const layout: DocTopic = {
       },
       {
         kind: "note",
-        title: "Версия 0.1.0",
-        text: "talafmt принимает то, что принимает компилятор, с которым он собран; версия 0.1.0 собрана с компилятором Tala 0.1.0.",
+        title: "Компилятор",
+        text: "talafmt принимает то, что принимает компилятор, с которым он собран.",
       },
     ],
   },
@@ -421,8 +421,8 @@ const layout: DocTopic = {
       },
       {
         kind: "note",
-        title: "גרסה 0.1.0",
-        text: "talafmt מקבל את מה שהמהדר שאיתו הוא נבנה מקבל; גרסה 0.1.0 נבנתה עם המהדר של Tala 0.1.0.",
+        title: "מהדר",
+        text: "talafmt מקבל את מה שהמהדר שאיתו הוא נבנה מקבל.",
       },
     ],
   },
diff --git a/frontend/src/content/talalint.ts b/frontend/src/content/talalint.ts
index 6cf8b7c..5d19b7e 100644
--- a/frontend/src/content/talalint.ts
+++ b/frontend/src/content/talalint.ts
@@ -5,7 +5,7 @@ import type { Locale } from "../locales";
 import type { LandingText, WhyTab } from "./landing";
 import type { DocRoute, DocTopic } from "./types";
 
-// talalint.tala.run. The facts follow the README of Progmasoft/talalint, version 0.1.0; commands and check names are
+// talalint.tala.run. The facts follow the README of Progmasoft/talalint; commands and check names are
 // the same in every language and only the prose is translated.
 const report = `talalint Program.tala Library.tala`;
 const fix = `talalint --fix Program.tala`;
@@ -302,7 +302,7 @@ const checksTopic: DocTopic = {
     nav: "What it checks",
     title: "What it checks · Talalint",
     description:
-      "The checks of talalint 0.1.0: the compiler's diagnostics and its own checks of the physical source.",
+      "The checks of talalint: the compiler's diagnostics and its own checks of the physical source.",
     section: "TALALINT / CHECKS",
     heading: "What talalint checks",
     lead: "talalint reports what the compiler it is built with reports, and adds checks of its own on the physical source.",
@@ -320,7 +320,7 @@ const checksTopic: DocTopic = {
       { kind: "heading", text: "Diagnostics of the compiler" },
       {
         kind: "text",
-        text: "Version 0.1.0 is built with the compiler of Tala 0.1.0. Its diagnostics arrive under the compiler check with the compiler's code:",
+        text: "The diagnostics of the compiler arrive under the compiler check with the compiler's code:",
       },
       { kind: "code", code: checks },
       {
@@ -334,7 +334,7 @@ const checksTopic: DocTopic = {
     nav: "Was es prüft",
     title: "Was es prüft · Talalint",
     description:
-      "Die Prüfungen von talalint 0.1.0: die Diagnosen des Compilers und eigene Prüfungen der physischen Quelle.",
+      "Die Prüfungen von talalint: die Diagnosen des Compilers und eigene Prüfungen der physischen Quelle.",
     section: "TALALINT / PRÜFUNGEN",
     heading: "Was talalint prüft",
     lead: "talalint meldet, was der Compiler meldet, mit dem es gebaut ist, und ergänzt eigene Prüfungen der physischen Quelle.",
@@ -352,7 +352,7 @@ const checksTopic: DocTopic = {
       { kind: "heading", text: "Diagnosen des Compilers" },
       {
         kind: "text",
-        text: "Version 0.1.0 ist mit dem Compiler von Tala 0.1.0 gebaut. Seine Diagnosen erscheinen unter der Prüfung compiler mit dem Code des Compilers:",
+        text: "Die Diagnosen des Compilers erscheinen unter der Prüfung compiler mit dem Code des Compilers:",
       },
       { kind: "code", code: checks },
       {
@@ -366,7 +366,7 @@ const checksTopic: DocTopic = {
     nav: "Что он проверяет",
     title: "Что он проверяет · Talalint",
     description:
-      "Проверки talalint 0.1.0: диагностика компилятора и собственные проверки физического текста.",
+      "Проверки talalint: диагностика компилятора и собственные проверки физического текста.",
     section: "TALALINT / ПРОВЕРКИ",
     heading: "Что проверяет talalint",
     lead: "talalint сообщает то, о чём сообщает компилятор, с которым он собран, и добавляет собственные проверки физического текста.",
@@ -384,7 +384,7 @@ const checksTopic: DocTopic = {
       { kind: "heading", text: "Диагностика компилятора" },
       {
         kind: "text",
-        text: "Версия 0.1.0 собрана с компилятором Tala 0.1.0. Его диагностика приходит в проверке compiler с кодом компилятора:",
+        text: "Диагностика компилятора приходит в проверке compiler с кодом компилятора:",
       },
       { kind: "code", code: checks },
       {
@@ -397,7 +397,7 @@ const checksTopic: DocTopic = {
   "he-IL": {
     nav: "מה הוא בודק",
     title: "מה הוא בודק · Talalint",
-    description: "הבדיקות של talalint 0.1.0: האבחונים של המהדר ובדיקות משלו על הטקסט הפיזי.",
+    description: "הבדיקות של talalint: האבחונים של המהדר ובדיקות משלו על הטקסט הפיזי.",
     section: "TALALINT / בדיקות",
     heading: "מה talalint בודק",
     lead: "talalint מדווח את מה שהמהדר שאיתו הוא נבנה מדווח, ומוסיף בדיקות משלו על הטקסט הפיזי.",
@@ -414,7 +414,7 @@ const checksTopic: DocTopic = {
       { kind: "heading", text: "האבחונים של המהדר" },
       {
         kind: "text",
-        text: "גרסה 0.1.0 נבנתה עם המהדר של Tala 0.1.0. האבחונים שלו מגיעים תחת הבדיקה compiler עם הקוד של המהדר:",
+        text: "האבחונים של המהדר מגיעים תחת הבדיקה compiler עם הקוד של המהדר:",
       },
       { kind: "code", code: checks },
       {
diff --git a/frontend/src/content/tazel.ts b/frontend/src/content/tazel.ts
index c6789ff..c53bd87 100644
--- a/frontend/src/content/tazel.ts
+++ b/frontend/src/content/tazel.ts
@@ -11,6 +11,22 @@ tazel lint -- --fix`;
 const selection = `tazel build --vipkg Name          tazel build -p Name
 tazel build --executable Name     tazel build -e Name
 tazel build --library Name        tazel build -l Name`;
+const machine = `tazel build --jobs 8 --cpus 6 --memory 16g
+tazel test --keep-going --profile build/trace.json
+tazel build --remote-executor https://build.example.com`;
+const custom = `# tazel_custom.txt
+fetch:
+    ("cargo" "fetch")
+    ("tazel" "fetch");
+
+npm-dev-sh: s('npm dev');
+
+build no-cache: ("tazel" "build" "--no-cache");
+build with: ("tazel" "build" <1> <2>);
+test all: ("tazel" "test" <*>);`;
+const customRuns = `tazel custom fetch
+tazel custom build no-cache
+tazel custom build with -e MyApp`;
 const locking = `tazel lock create-dump --path reviews/Locks.sql
 tazel lock graph --locked
 tazel lock graph --invert Publisher.Name
@@ -35,6 +51,18 @@ const compiler = `compiler {
     lto = LlvmLto.NONE
   }
 }`;
+const execution = `execution {
+  jobs = 8
+  cpus = 6
+  memory = "16g"
+  keepGoing = true
+  incremental = true
+
+  remote {
+    url = "https://build.example.com"
+    token = System.getenv("TAZEL_REMOTE_TOKEN")
+  }
+}`;
 const dependencies = `dependencies {
   dependency("Publisher") {
     name = "Toml"
@@ -60,11 +88,16 @@ const commandTerms = (
     | "build"
     | "run"
     | "test"
+    | "fetch"
+    | "custom"
     | "resolve"
     | "dump"
     | "graph"
     | "fmt"
     | "lint"
+    | "cache"
+    | "remote"
+    | "daemon"
     | "version"
     | "help"
     | "registry",
@@ -75,11 +108,16 @@ const commandTerms = (
   { term: "tazel build", detail: d.build },
   { term: "tazel run [-- arguments]", detail: d.run },
   { term: "tazel test", detail: d.test },
+  { term: "tazel fetch", detail: d.fetch },
+  { term: "tazel custom [name] [arguments]", detail: d.custom },
   { term: "tazel lock resolve", detail: d.resolve },
   { term: "tazel lock create-dump [--path File]", detail: d.dump },
   { term: "tazel lock graph [options]", detail: d.graph },
   { term: "tazel fmt [-- options]", detail: d.fmt },
   { term: "tazel lint [--workspace] [-- options]", detail: d.lint },
+  { term: "tazel cache status, clean, push, pull, keygen, serve", detail: d.cache },
+  { term: "tazel remote serve", detail: d.remote },
+  { term: "tazel jvm start-daemon, restart-daemon, stop-daemon", detail: d.daemon },
   { term: "tazel version", detail: d.version },
   { term: "tazel help [command]", detail: d.help },
   {
@@ -108,18 +146,46 @@ const commands: DocTopic = {
             "Builds the executables into the output directory of the build mode, under the name of the target.",
           run: "Builds the executables and runs them; what follows -- goes to the program.",
           test: "Builds and runs the test suites.",
+          fetch:
+            "Fetches plugins of ViGet into .tazel/plugins ahead of time, and fails if a local package is missing.",
+          custom: "Runs a command of tazel_custom.txt, or lists them.",
           resolve: "Records the declared dependencies in LOCK.sqlite3.",
           dump: "Writes the lockfile as SQL text: to LOCK.dump, or to the file --path names. The folder of that file has to exist.",
           graph:
             "Prints the dependency graph and renews LOCK.sqlite3 first, unless --locked forbids it.",
           fmt: "Formats the sources with talafmt.",
           lint: "Lints the sources with talalint.",
+          cache:
+            "Show, clean, send or fetch the results of the build cache, and serve one for a team.",
+          remote: "Compiles for other machines, on the sources they send.",
+          daemon: "Keep Tazel warm between commands, or stop it.",
           version: "Prints the version of Tazel.",
           help: "Prints the help, or the help of one command.",
           registry:
             "Commands that need ViGet or a library build; they are refused by name until those exist.",
         }),
       },
+      { kind: "heading", text: "Spending the machine" },
+      {
+        kind: "text",
+        text: "check, build, run and test run compiler runs and test suites side by side, one job per processor. --jobs, --cpus and --memory limit them, --keep-going goes on after a failure, and --profile writes a trace for chrome://tracing or Perfetto. Each project's plugin steps, compilations and test suites are units of one graph, so a unit waits only for what it depends on.",
+      },
+      { kind: "code", code: machine },
+      {
+        kind: "text",
+        text: "--remote-executor compiles on another machine, one you trust, that runs tazel remote serve. Programs and test suites still run here, and if the server cannot help, Tazel warns once and compiles here.",
+      },
+      { kind: "heading", text: "Custom commands" },
+      {
+        kind: "text",
+        text: "tazel custom runs the commands of tazel_custom.txt, from the current folder or the nearest one above it. They need no project file and do not have to involve Tazel.",
+      },
+      { kind: "code", code: custom },
+      { kind: "code", code: customRuns },
+      {
+        kind: "text",
+        text: "Steps run in order. (...) starts a program directly, with no shell, and s(...) hands one command line to CMD on Windows and sh elsewhere. A name may hold several words, and the longest name that fits wins. <N> passes the Nth argument, from 1, and <*> passes all of them; neither works in s(...). The name and its arguments are at most 191 words.",
+      },
       { kind: "heading", text: "Selecting targets" },
       {
         kind: "text",
@@ -150,7 +216,7 @@ const commands: DocTopic = {
       {
         kind: "note",
         title: "Not implemented yet",
-        text: "Library targets, projects with dependencies, test suites, .vipkg creation and every command that needs ViGet are refused by name with exit code 1. check, build and run compile for the host.",
+        text: "Library targets, projects with dependencies, .vipkg creation and every command that needs packages of ViGet are refused by name with exit code 1. check, build and run compile for the host.",
       },
     ],
   },
@@ -173,18 +239,46 @@ const commands: DocTopic = {
             "Baut die ausführbaren Dateien in das Ausgabeverzeichnis des Build-Modus, unter dem Namen des Ziels.",
           run: "Baut die ausführbaren Dateien und startet sie; was nach -- folgt, geht an das Programm.",
           test: "Baut die Testsuiten und führt sie aus.",
+          fetch:
+            "Holt Plugins aus ViGet vorab nach .tazel/plugins und schlägt fehl, wenn ein lokales Paket fehlt.",
+          custom: "Führt einen Befehl aus tazel_custom.txt aus oder listet sie auf.",
           resolve: "Hält die deklarierten Abhängigkeiten in LOCK.sqlite3 fest.",
           dump: "Schreibt die Lockdatei als SQL-Text: nach LOCK.dump oder in die Datei, die --path nennt. Deren Ordner muss bereits existieren.",
           graph:
             "Gibt den Abhängigkeitsgraphen aus und erneuert vorher LOCK.sqlite3, außer --locked verbietet es.",
           fmt: "Formatiert die Quellen mit talafmt.",
           lint: "Prüft die Quellen mit talalint.",
+          cache:
+            "Zeigen, leeren, senden oder holen die Ergebnisse des Build-Caches und stellen einen für ein Team bereit.",
+          remote: "Kompiliert für andere Rechner die Quellen, die sie schicken.",
+          daemon: "Halten Tazel zwischen Befehlen warm oder beenden es.",
           version: "Gibt die Version von Tazel aus.",
           help: "Gibt die Hilfe aus, oder die Hilfe eines Befehls.",
           registry:
             "Befehle, die ViGet oder einen Bibliotheks-Build brauchen; sie werden mit Namen abgelehnt, bis es beides gibt.",
         }),
       },
+      { kind: "heading", text: "Die Maschine nutzen" },
+      {
+        kind: "text",
+        text: "check, build, run und test führen Compiler-Läufe und Testsuiten nebeneinander aus, ein Job pro Prozessor. --jobs, --cpus und --memory begrenzen sie, --keep-going macht nach einem Fehler weiter, und --profile schreibt einen Trace für chrome://tracing oder Perfetto. Plugin-Schritte, Kompilierungen und Testsuiten eines Projekts sind Einheiten eines Graphen, daher wartet eine Einheit nur auf das, wovon sie abhängt.",
+      },
+      { kind: "code", code: machine },
+      {
+        kind: "text",
+        text: "--remote-executor kompiliert auf einem anderen Rechner, dem Sie vertrauen und auf dem tazel remote serve läuft. Programme und Testsuiten laufen weiterhin hier, und wenn der Server nicht helfen kann, warnt Tazel einmal und kompiliert hier.",
+      },
+      { kind: "heading", text: "Eigene Befehle" },
+      {
+        kind: "text",
+        text: "tazel custom führt die Befehle aus tazel_custom.txt aus, aus dem aktuellen Ordner oder dem nächsten darüber. Sie brauchen keine Projektdatei und müssen Tazel nicht betreffen.",
+      },
+      { kind: "code", code: custom },
+      { kind: "code", code: customRuns },
+      {
+        kind: "text",
+        text: "Schritte laufen der Reihe nach. (...) startet ein Programm direkt, ohne Shell, und s(...) gibt eine Befehlszeile an CMD unter Windows und sonst an sh. Ein Name darf mehrere Wörter haben, und der längste passende Name gilt. <N> übergibt das N-te Argument, ab 1, und <*> alle; beides geht nicht in s(...). Name und Argumente sind zusammen höchstens 191 Wörter.",
+      },
       { kind: "heading", text: "Ziele auswählen" },
       {
         kind: "text",
@@ -215,7 +309,7 @@ const commands: DocTopic = {
       {
         kind: "note",
         title: "Noch nicht umgesetzt",
-        text: "Bibliotheksziele, Projekte mit Abhängigkeiten, Testsuiten, die Erstellung von .vipkg und jeder Befehl, der ViGet braucht, werden mit Namen und Exit-Code 1 abgelehnt. check, build und run kompilieren für den Host.",
+        text: "Bibliotheksziele, Projekte mit Abhängigkeiten, die Erstellung von .vipkg und jeder Befehl, der Pakete aus ViGet braucht, werden mit Namen und Exit-Code 1 abgelehnt. check, build und run kompilieren für den Host.",
       },
     ],
   },
@@ -236,18 +330,46 @@ const commands: DocTopic = {
           build: "Собирает исполняемые файлы в каталог результатов режима сборки под именем цели.",
           run: "Собирает исполняемые файлы и запускает их; всё после -- передаётся программе.",
           test: "Собирает и запускает наборы тестов.",
+          fetch:
+            "Заранее загружает плагины ViGet в .tazel/plugins и завершается ошибкой, если локального пакета нет.",
+          custom: "Запускает команду из tazel_custom.txt или выводит их список.",
           resolve: "Записывает объявленные зависимости в LOCK.sqlite3.",
           dump: "Записывает lock-файл в виде SQL-текста: в LOCK.dump или в файл, указанный в --path. Его каталог должен уже существовать.",
           graph:
             "Выводит граф зависимостей и сначала обновляет LOCK.sqlite3, если --locked этого не запрещает.",
           fmt: "Форматирует исходники с помощью talafmt.",
           lint: "Проверяет исходники с помощью talalint.",
+          cache:
+            "Показывают, очищают, отправляют или получают результаты кэша сборки и обслуживают кэш для команды.",
+          remote: "Компилирует для других машин присланные ими исходники.",
+          daemon: "Держат Tazel запущенным между командами или останавливают его.",
           version: "Выводит версию Tazel.",
           help: "Выводит справку или справку по одной команде.",
           registry:
             "Команды, которым нужны ViGet или сборка библиотек; пока их нет, они отклоняются по имени.",
         }),
       },
+      { kind: "heading", text: "Ресурсы машины" },
+      {
+        kind: "text",
+        text: "check, build, run и test выполняют запуски компилятора и наборы тестов параллельно, по одной задаче на процессор. --jobs, --cpus и --memory их ограничивают, --keep-going продолжает работу после сбоя, а --profile записывает трассировку для chrome://tracing или Perfetto. Шаги плагинов, компиляции и наборы тестов проекта — единицы одного графа, поэтому единица ждёт только то, от чего зависит.",
+      },
+      { kind: "code", code: machine },
+      {
+        kind: "text",
+        text: "--remote-executor компилирует на другой машине, которой вы доверяете и на которой работает tazel remote serve. Программы и наборы тестов по-прежнему выполняются здесь, а если сервер не может помочь, Tazel предупреждает один раз и компилирует здесь.",
+      },
+      { kind: "heading", text: "Свои команды" },
+      {
+        kind: "text",
+        text: "tazel custom запускает команды из tazel_custom.txt, найденного в текущем каталоге или ближайшем выше. Файл проекта им не нужен, и они не обязаны быть связаны с Tazel.",
+      },
+      { kind: "code", code: custom },
+      { kind: "code", code: customRuns },
+      {
+        kind: "text",
+        text: "Шаги выполняются по порядку. (...) запускает программу напрямую, без оболочки, а s(...) передаёт одну командную строку в CMD в Windows и в sh в остальных системах. Имя может состоять из нескольких слов, и выбирается самое длинное подходящее. <N> передаёт N-й аргумент, начиная с 1, а <*> — все; в s(...) они не работают. Имя вместе с аргументами — не более 191 слова.",
+      },
       { kind: "heading", text: "Выбор целей" },
       {
         kind: "text",
@@ -278,7 +400,7 @@ const commands: DocTopic = {
       {
         kind: "note",
         title: "Пока не реализовано",
-        text: "Библиотечные цели, проекты с зависимостями, наборы тестов, создание .vipkg и все команды, которым нужен ViGet, отклоняются по имени с кодом выхода 1. check, build и run компилируют для текущей системы.",
+        text: "Библиотечные цели, проекты с зависимостями, создание .vipkg и все команды, которым нужны пакеты ViGet, отклоняются по имени с кодом выхода 1. check, build и run компилируют для текущей системы.",
       },
     ],
   },
@@ -299,16 +421,42 @@ const commands: DocTopic = {
           build: "בונה את קובצי ההרצה לתיקיית הפלט של מצב הבנייה, בשם היעד.",
           run: "בונה את קובצי ההרצה ומריץ אותם; מה שאחרי ‎-- עובר לתוכנית.",
           test: "בונה ומריץ את חבילות הבדיקה.",
+          fetch: "מוריד מראש תוספים של ViGet אל ‎.tazel/plugins, ונכשל אם חבילה מקומית חסרה.",
+          custom: "מריץ פקודה מתוך tazel_custom.txt, או מציג את רשימתן.",
           resolve: "רושם את התלויות המוצהרות ב-LOCK.sqlite3.",
           dump: "כותב את קובץ הנעילה כטקסט SQL: ל-LOCK.dump, או לקובץ ש-‎--path מציין. התיקייה של הקובץ חייבת להיות קיימת.",
           graph: "מדפיס את גרף התלויות ומחדש קודם את LOCK.sqlite3, אלא אם ‎--locked אוסר זאת.",
           fmt: "מעצב את קבצי המקור עם talafmt.",
           lint: "בודק את קבצי המקור עם talalint.",
+          cache: "מציגות, מנקות, שולחות או מורידות את תוצאות מטמון הבנייה, ומגישות