From 0680cee5f8f523893093be818da99c6dc48b480b Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Fri, 13 Nov 2026 05:46:56 +0100 Subject: [PATCH] Add a getting-started page, and fix the shebang that made ./build.cs fail The docs had no install step and no first build: the target DSLs lived only in the package READMEs, which suited a section of argh's site but not runna's own. Getting started installs Runna or Runna.Fs and builds the same three targets in C# and in F#, with the help and plan they print. The landing page's get-started links go there. Every C# example started with `#!/usr/bin/env -S dotnet run --`, which turns `./build.cs` into `dotnet run -- ./build.cs` and fails looking for a project. The shebang is now `#!/usr/bin/env -S dotnet --`, which passes every argument, --help included, to the script. Also: "per Make target" in the make page names the tool runna. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- docs/_docset.yml | 1 + docs/getting-started.md | 147 ++++++++++++++++++ docs/index.md | 6 +- docs/makefile.md | 2 +- docs/runna-landing.html | 8 +- plans/top-level-field-dsl.md | 2 +- src/Nullean.Runna/README.md | 2 +- .../skills/nullean-runna/SKILL.md | 2 +- 9 files changed, 161 insertions(+), 11 deletions(-) create mode 100644 docs/getting-started.md diff --git a/README.md b/README.md index 7b79402..5f358c1 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ The same three targets in either language: `test` needs `build`, which needs `cl A file-based app next to your solution is enough. ```csharp -#!/usr/bin/env -S dotnet run -- +#!/usr/bin/env -S dotnet -- #:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591 diff --git a/docs/_docset.yml b/docs/_docset.yml index b1a424b..ecd2a26 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -6,6 +6,7 @@ branding: toc: - file: index.md + - file: getting-started.md - file: running.md - file: graph.md - file: parallel.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..e679736 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,147 @@ +# Getting started + +runna turns a set of build targets into a command line: each target is a type, dependencies run first, and every +target gets `--help` from its doc comment. It requires .NET 11. + +```bash +dotnet add package Runna # C# +dotnet add package Runna.Fs # F# +``` + +Both examples below define the same three targets: `test` needs `build`, which needs `clean`. + +## C# + +A [file-based app](https://learn.microsoft.com/dotnet/core/sdk/file-based-apps) next to your solution is enough. Save +this as `build.cs`: + +```csharp +#!/usr/bin/env -S dotnet -- +#:package Runna@0.2.0 +#:property GenerateDocumentationFile=true +#:property NoWarn=CS1591 +using Nullean.Runna; +using static Nullean.Runna.Shell; + +var app = new RunnaApp("build"); + +app.Bind(t => t.Value switch +{ + Clean => app.Target(() => Exec("dotnet clean")), + Build => app.Target([new Clean()], () => Exec("dotnet build")), + Test => app.Target([new Build()], () => Exec("dotnet test")), + _ => throw new InvalidOperationException($"unmapped target {t.Value}") +}); + +return await app.RunAsync(args); + +/// Delete build output +record Clean; +/// Build the solution +record Build; +/// Build, then run the tests +record Test; + +union Target(Clean, Build, Test); +``` + +Targets are the cases of a C# `union`, one `record` each, and the `/// ` becomes the target's description. +Make the file executable once, then run it like any CLI: + +```bash +chmod +x build.cs +./build.cs --help +./build.cs test +``` + +`dotnet run build.cs -- test` works the same, on every platform. + +## F# + +F# targets are the cases of a DU, so a case you forget in `Bind` is a compiler warning (FS0025). Each target body is +a [Proc.Fs](https://www.nuget.org/packages/Proc.Fs) `shell { }` block. Put the build in a small project, +`build/build.fsproj`: + +```xml + + + Exe + net11.0 + + true + + + + + + +``` + +and `build/Program.fs`: + +```fsharp +open Nullean.Runna.Fs +open Proc.Fs + +type Target = + /// Delete build output + | Clean + /// Build the solution + | Build + /// Build, then run the tests + | Test + +[] +let main argv = + let app = RunnaApp("build", None) + + app.Bind <| function + | Clean -> target [] { sh $"dotnet clean" } + | Build -> target [Clean] { sh $"dotnet build" } + | Test -> target [Build] { sh $"dotnet test" } + + app.RunAsync(argv).GetAwaiter().GetResult() +``` + +```bash +dotnet run --project build -- --help +dotnet run --project build -- test +``` + +## What it prints + +Either one prints the same help, with each target's dependencies: + +```text +build + + Usage: + build [options] [ [options]...] + + Targets: (atomic steps — can also be run directly) + clean Delete build output + build Build the solution (depends on: clean) + test Build, then run the tests (depends on: build) +``` + +and `test --graph` draws what `test` would run, without running it: + +```text +test Build, then run the tests +└─ build + └─ clean + +Runs: clean → build → test +``` + +## Next + +- [Choosing what runs](running.md): several targets on one command line, `-s` and `--skip`. +- [Drawing the plan](graph.md): `--graph` as a tree, Mermaid or JSON. +- [Running targets side by side](parallel.md): parallel stages, `-j` and `--keep-going`. +- [Conditions, ordering and cleanup](modifiers.md): `OnlyWhen`, `After`, `Cleanup`, `NeedsEnv` and `NeedsTool`. +- [Wrappers](wrappers.md): one task per target for mise, make and just. + +The package READMEs cover the rest of the DSL, such as typed per-target flags, global options, namespaces and pipeline +commands: [`Runna`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna/README.md) for C# and +[`Runna.Fs`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna.Fs/README.md) for F#. diff --git a/docs/index.md b/docs/index.md index 16a6499..b36d00e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ # runna -The `Runna` (C#) and `Runna.Fs` (F#) packages are typed build target DSLs built on [argh](https://argh.nullean.net). Targets are union cases -(or DU cases in F#), dependencies run first, and every target gets Argh-style `--help`. +The `Runna` (C#) and `Runna.Fs` (F#) packages are typed build target DSLs built on [argh](https://argh.nullean.net). +Targets are union cases (or DU cases in F#), dependencies run first, and every target gets Argh-style `--help`. ```bash ./build.cs --help @@ -12,6 +12,8 @@ The `Runna` (C#) and `Runna.Fs` (F#) packages are typed build target DSLs built ./build.cs release --skip docs ``` +[**Getting started**](getting-started.md) - Install, and a first build in C# and in F#. + [**Choosing what runs**](running.md) - Several targets on one command line, `-s` and `--skip`. [**Running targets side by side**](parallel.md) - Parallel stages, `-j`, `--keep-going`, and the output of targets diff --git a/docs/makefile.md b/docs/makefile.md index b7bef55..8378e59 100644 --- a/docs/makefile.md +++ b/docs/makefile.md @@ -1,6 +1,6 @@ # make -`__wrappers sync` writes `.runna/runna.mk`, a GNU make include with one phony target per Make target. Include it from +`__wrappers sync` writes `.runna/runna.mk`, a GNU make include with one phony target per runna target. Include it from the Makefile: ```makefile diff --git a/docs/runna-landing.html b/docs/runna-landing.html index 744c914..2e42e0d 100644 --- a/docs/runna-landing.html +++ b/docs/runna-landing.html @@ -405,7 +405,7 @@ github → @@ -439,7 +439,7 @@

runna build.
runna test.

@@ -558,7 +558,7 @@

C# or F#.
Then run it.

build.cs
-
#!/usr/bin/env -S dotnet run --
+
#!/usr/bin/env -S dotnet --
 #:package Runna@0.2.0
 #:property GenerateDocumentationFile=true
 #:property NoWarn=CS1591
@@ -633,7 +633,7 @@ 

C# or F#.
Then run it.

runna build.
Ship it.

Typed targets, dependencies first, and help you never have to write.

diff --git a/plans/top-level-field-dsl.md b/plans/top-level-field-dsl.md index 3c63f97..8417d4a 100644 --- a/plans/top-level-field-dsl.md +++ b/plans/top-level-field-dsl.md @@ -44,7 +44,7 @@ Two C# language features do all the work: ## Worked example ```csharp -#!/usr/bin/env dotnet run +#!/usr/bin/env -S dotnet -- #:package Runna@0.2.0 using Nullean.Runna; diff --git a/src/Nullean.Runna/README.md b/src/Nullean.Runna/README.md index 5ca76ef..da15650 100644 --- a/src/Nullean.Runna/README.md +++ b/src/Nullean.Runna/README.md @@ -17,7 +17,7 @@ Or, in a file-based app such as `build.cs`, `#:package Runna@` as below ## Quick start ```csharp -#!/usr/bin/env -S dotnet run -- +#!/usr/bin/env -S dotnet -- #:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591 diff --git a/src/Nullean.Runna/skills/nullean-runna/SKILL.md b/src/Nullean.Runna/skills/nullean-runna/SKILL.md index 368966a..9ce78b3 100644 --- a/src/Nullean.Runna/skills/nullean-runna/SKILL.md +++ b/src/Nullean.Runna/skills/nullean-runna/SKILL.md @@ -13,7 +13,7 @@ maps each case to what it runs. For F#, use the `Runna.Fs` package (skill `nulle ## The calls you need ```csharp -#!/usr/bin/env -S dotnet run -- +#!/usr/bin/env -S dotnet -- #:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591