diff --git a/AGENTS.md b/AGENTS.md index a261b77..541b60b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # runna -Typed build targets for .NET: `Nullean.Runna` (C#, targets are the cases of a `union`) and `Nullean.Runna.Fs` (F#, +Typed build targets for .NET: the `Runna` package (C#, targets are the cases of a `union`) and `Runna.Fs` (F#, targets are DU cases), built on [argh](https://github.com/nullean/argh) for help and argument parsing. The docs site (`docs/`, runna.nullean.net) is a docs-builder site published by `.github/workflows/gh-pages.yml`. @@ -10,7 +10,7 @@ targets are DU cases), built on [argh](https://github.com/nullean/argh) for help class with `Target` properties), the dependency graph, the run plan, parallel stages, help, and the mise, make and just wrappers (`__wrappers sync|check`). - `src/Nullean.Runna.Generator`: the source generator that registers each union's case table. It ships inside the - `Nullean.Runna` package as an analyzer, so a `#:project` reference to `src/Nullean.Runna` does not run it; union + `Runna` package as an analyzer, so a `#:project` reference to `src/Nullean.Runna` does not run it; union targets need the package (or a project reference with `OutputItemType="Analyzer"`, as the tests use). - `src/Nullean.Runna.Fs`: the F# binding over the runtime. `Nullean.Runna` grants it `InternalsVisibleTo` by public key, so both are signed with `build/keys/keypair.snk`. diff --git a/README.md b/README.md index 8d45fa2..7b79402 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@

Typed build targets for .NET: your targets are the cases of a C# union or an F# DU, dependencies run first, and every target gets real --help.

- NuGet + Runna on NuGet + Runna.Fs on NuGet CI Docs

@@ -28,16 +29,21 @@ Runs: pristine-check → test → pkg generate → pkg validate → release-note ## Install ```sh -dotnet add package Nullean.Runna +dotnet add package Runna # C# +dotnet add package Runna.Fs # F# ``` ## Quick start -A file-based app next to your solution is enough. It requires .NET 11. +The same three targets in either language: `test` needs `build`, which needs `clean`. It requires .NET 11. + +### C# + +A file-based app next to your solution is enough. ```csharp #!/usr/bin/env -S dotnet run -- -#:package Nullean.Runna@0.1.0 +#:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591 using Nullean.Runna; @@ -67,16 +73,68 @@ union Target(Clean, Build, Test); ```sh ./build.cs --help -./build.cs test ./build.cs test --graph ``` +### F# + +Targets are the cases of a DU, so a case you forget in `Bind` is a compiler warning (FS0025), and each target body is a +[Proc.Fs](https://www.nuget.org/packages/Proc.Fs) `shell { }` block. Put it in a small project, `build/build.fsproj`: + +```xml + + + Exe + net11.0 + + true + + + + + + +``` + +```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() +``` + +```sh +dotnet run --project build -- --help +dotnet run --project build -- test --graph +``` + +Both print the same help and plan. The package READMEs go further: typed per-target flags, namespaces, pipeline +commands, parallel stages and the [Runna](src/Nullean.Runna/README.md) / [Runna.Fs](src/Nullean.Runna.Fs/README.md) +specifics. + ## Packages | Package | What it is | | |---|---|---| -| [`Nullean.Runna`](src/Nullean.Runna/README.md) | C# build targets as the cases of a `union` | [![NuGet](https://img.shields.io/nuget/v/Nullean.Runna?style=flat-square)](https://www.nuget.org/packages/Nullean.Runna) | -| [`Nullean.Runna.Fs`](src/Nullean.Runna.Fs/README.md) | F# build targets as DU cases | [![NuGet](https://img.shields.io/nuget/v/Nullean.Runna.Fs?style=flat-square)](https://www.nuget.org/packages/Nullean.Runna.Fs) | +| [`Runna`](src/Nullean.Runna/README.md) | C# build targets as the cases of a `union` | [![NuGet](https://img.shields.io/nuget/v/Runna?style=flat-square)](https://www.nuget.org/packages/Runna) | +| [`Runna.Fs`](src/Nullean.Runna.Fs/README.md) | F# build targets as DU cases | [![NuGet](https://img.shields.io/nuget/v/Runna.Fs?style=flat-square)](https://www.nuget.org/packages/Runna.Fs) | ## Learn more diff --git a/build/scripts/Program.fs b/build/scripts/Program.fs index 1902ce5..195c928 100644 --- a/build/scripts/Program.fs +++ b/build/scripts/Program.fs @@ -43,8 +43,9 @@ let private projectsToClean () = ["src"; "tests"; "examples"] |> List.collect (fun d -> Directory.EnumerateFiles(d, "*.?sproj", SearchOption.AllDirectories) |> Seq.toList) -/// Unified artifacts layout (): `.artifacts/bin//release/`, every package being single-TFM -let private assembliesDir (packageId: string) = $".artifacts/bin/{packageId}/release" +/// Unified artifacts layout (): `.artifacts/bin//release/`, every package being single-TFM. +/// The packages are `Runna` and `Runna.Fs`; their projects keep the `Nullean.` prefix, as their namespaces do. +let private assembliesDir (packageId: string) = $".artifacts/bin/Nullean.{packageId}/release" [] let main argv = @@ -79,7 +80,7 @@ let main argv = for id, _ in packageIds () do let report = Path.Combine(output, $"breaking-changes-{id}.md") // quoted: an unquoted | would pipe - sh $"dotnet assembly-differ diff 'previous-nuget|{id}|{version}|{Paths.MainTFM}' 'directory|{assembliesDir id}' -a --target {id} -f github-comment --output {report}" } + sh $"dotnet assembly-differ diff 'previous-nuget|{id}|{version}|{Paths.MainTFM}' 'directory|{assembliesDir id}' -a --target Nullean.{id} -f github-comment --output {report}" } | Docs -> target [] { Documentation.build () Documentation.serve 8080 } diff --git a/docs/index.md b/docs/index.md index df39aae..16a6499 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # runna -`Nullean.Runna` (C#) and `Nullean.Runna.Fs` (F#) are typed build target DSLs built on [argh](https://argh.nullean.net). Targets are union cases +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 @@ -27,7 +27,7 @@ variables and tools before the run starts. The package READMEs cover the target DSLs: -- [`Nullean.Runna`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna/README.md): C# targets as `union` cases, +- [`Runna`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna/README.md): C# targets as `union` cases, or properties on a `RunnaBuild` class. -- [`Nullean.Runna.Fs`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna.Fs/README.md): F# targets as DU +- [`Runna.Fs`](https://github.com/nullean/runna/blob/main/src/Nullean.Runna.Fs/README.md): F# targets as DU cases, with `shell { }` target blocks. diff --git a/docs/runna-landing.html b/docs/runna-landing.html index e2cd6ca..744c914 100644 --- a/docs/runna-landing.html +++ b/docs/runna-landing.html @@ -424,18 +424,18 @@

runna build.
runna test.

- - nuget ↗ + nuget ↗
- - nuget ↗ + nuget ↗
@@ -559,7 +559,7 @@

C# or F#.
Then run it.

build.cs
#!/usr/bin/env -S dotnet run --
-#:package Nullean.Runna@0.1.0
+#:package Runna@0.2.0
 #:property GenerateDocumentationFile=true
 #:property NoWarn=CS1591
 using Nullean.Runna;
@@ -621,8 +621,8 @@ 

C# or F#.
Then run it.

The package READMEs cover the full DSL: - Nullean.Runna for C# and - Nullean.Runna.Fs for F#. + Runna for C# and + Runna.Fs for F#.

@@ -657,7 +657,7 @@

runna build.
Ship it.

> nullean_ - Nullean.Runna — MIT licensed + runna — MIT licensed choosing what runs · diff --git a/plans/top-level-field-dsl.md b/plans/top-level-field-dsl.md index de87e80..3c63f97 100644 --- a/plans/top-level-field-dsl.md +++ b/plans/top-level-field-dsl.md @@ -45,7 +45,7 @@ Two C# language features do all the work: ```csharp #!/usr/bin/env dotnet run -#:package Nullean.Runna@0.1.0 +#:package Runna@0.2.0 using Nullean.Runna; using static ProcNet.Proc; diff --git a/src/Nullean.Runna.Fs/Nullean.Runna.Fs.fsproj b/src/Nullean.Runna.Fs/Nullean.Runna.Fs.fsproj index fc315e3..7a86701 100644 --- a/src/Nullean.Runna.Fs/Nullean.Runna.Fs.fsproj +++ b/src/Nullean.Runna.Fs/Nullean.Runna.Fs.fsproj @@ -13,8 +13,8 @@ true ..\..\build\keys\keypair.snk - Nullean.Runna.Fs - Nullean.Runna.Fs - F# DU-based build target DSL + Runna.Fs + Runna.Fs - F# DU-based build target DSL F# DU/match binding over Nullean.Runna — exhaustive, typed, namespaced build targets. build;make;targets;build-automation;fsharp diff --git a/src/Nullean.Runna.Fs/README.md b/src/Nullean.Runna.Fs/README.md index 62b3a0d..1de0b52 100644 --- a/src/Nullean.Runna.Fs/README.md +++ b/src/Nullean.Runna.Fs/README.md @@ -1,18 +1,18 @@ -# Nullean.Runna.Fs +# Runna.Fs ![runna](https://raw.githubusercontent.com/nullean/runna/main/docs/images/png/runna-lockup-544x278.png) Typed, namespaced, exhaustive F# build targets. Your targets are DU cases, and a case you forget to handle in `Bind` is a compiler warning (FS0025). Target blocks are [Proc.Fs](https://www.nuget.org/packages/Proc.Fs) `shell { }` blocks, so commands are `sh $"…"` lines. -[![NuGet](https://img.shields.io/nuget/v/Nullean.Runna.Fs?style=flat-square)](https://www.nuget.org/packages/Nullean.Runna.Fs) +[![NuGet](https://img.shields.io/nuget/v/Runna.Fs?style=flat-square)](https://www.nuget.org/packages/Runna.Fs) ## Install ```sh -dotnet add package Nullean.Runna.Fs +dotnet add package Runna.Fs ``` -Requires .NET 11. The package pulls in `Nullean.Runna` (the underlying C# engine) and `Proc.Fs` transitively. +Requires .NET 11. The package pulls in `Runna` (the underlying C# engine) and `Proc.Fs` transitively. ## Quick start diff --git a/src/Nullean.Runna/Nullean.Runna.csproj b/src/Nullean.Runna/Nullean.Runna.csproj index a60b4f6..52f4f96 100644 --- a/src/Nullean.Runna/Nullean.Runna.csproj +++ b/src/Nullean.Runna/Nullean.Runna.csproj @@ -11,8 +11,8 @@ true ..\..\build\keys\keypair.snk - Nullean.Runna - Nullean.Runna - typed namespaced build target DSL + Runna + Runna - typed namespaced build target DSL Property-dispatch build target DSL with Argh-quality help and per-target typed CLI arguments. build;make;targets;build-automation;cli diff --git a/src/Nullean.Runna/README.md b/src/Nullean.Runna/README.md index 64d9971..5ca76ef 100644 --- a/src/Nullean.Runna/README.md +++ b/src/Nullean.Runna/README.md @@ -1,24 +1,24 @@ -# Nullean.Runna +# Runna ![runna](https://raw.githubusercontent.com/nullean/runna/main/docs/images/png/runna-lockup-544x278.png) Typed build targets for .NET, with [Argh](https://github.com/nullean/argh)-quality help. Your targets are the cases of a C# `union`; each one runs commands, and dependencies run first. -[![NuGet](https://img.shields.io/nuget/v/Nullean.Runna?style=flat-square)](https://www.nuget.org/packages/Nullean.Runna) +[![NuGet](https://img.shields.io/nuget/v/Runna?style=flat-square)](https://www.nuget.org/packages/Runna) ## Install ```sh -dotnet add package Nullean.Runna +dotnet add package Runna ``` -Or, in a file-based app such as `build.cs`, `#:package Nullean.Runna@` as below. It requires .NET 11. +Or, in a file-based app such as `build.cs`, `#:package Runna@` as below. It requires .NET 11. ## Quick start ```csharp #!/usr/bin/env -S dotnet run -- -#:package Nullean.Runna@0.1.0 +#:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591 using Nullean.Runna; @@ -219,7 +219,7 @@ and [just](https://runna.nullean.net/just). `RunnaApp.Execute(args)` discovers targets from a `RunnaBuild` class instead: `Target` properties, `[Flag]` and `[GlobalOption]` properties, and nested `Namespace` classes. A dependency on a `Target` names its value with `With`: `.DependsOn(Test.With(new("Unit")))`. [`build.cs`](https://github.com/nullean/argh/blob/main/build.cs) in this repository is a complete example. -For F#, see [`Nullean.Runna.Fs`](https://www.nuget.org/packages/Nullean.Runna.Fs). +For F#, see [`Runna.Fs`](https://www.nuget.org/packages/Runna.Fs). ## Learn more diff --git a/src/Nullean.Runna/skills/nullean-runna/SKILL.md b/src/Nullean.Runna/skills/nullean-runna/SKILL.md index 0ee94fe..368966a 100644 --- a/src/Nullean.Runna/skills/nullean-runna/SKILL.md +++ b/src/Nullean.Runna/skills/nullean-runna/SKILL.md @@ -8,13 +8,13 @@ description: >- # Nullean.Runna A typed build target runner on top of Nullean.Argh: each target is a record, the records form a `union`, and `Bind` -maps each case to what it runs. For F#, use `Nullean.Runna.Fs` (skill `nullean-runna-fs`). +maps each case to what it runs. For F#, use the `Runna.Fs` package (skill `nullean-runna-fs`). ## The calls you need ```csharp #!/usr/bin/env -S dotnet run -- -#:package Nullean.Runna@0.1.0 +#:package Runna@0.2.0 #:property GenerateDocumentationFile=true #:property NoWarn=CS1591 using Nullean.Runna;