Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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`.

Expand All @@ -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`.
Expand Down
72 changes: 65 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
<p align="center">Typed build targets for .NET: your targets are the cases of a C# <code>union</code> or an F# DU, dependencies run first, and every target gets real <code>--help</code>.</p>

<p align="center">
<a href="https://www.nuget.org/packages/Nullean.Runna"><img src="https://img.shields.io/nuget/v/Nullean.Runna?style=flat-square" alt="NuGet"></a>
<a href="https://www.nuget.org/packages/Runna"><img src="https://img.shields.io/nuget/v/Runna?style=flat-square&label=Runna" alt="Runna on NuGet"></a>
<a href="https://www.nuget.org/packages/Runna.Fs"><img src="https://img.shields.io/nuget/v/Runna.Fs?style=flat-square&label=Runna.Fs" alt="Runna.Fs on NuGet"></a>
<a href="https://github.com/nullean/runna/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/nullean/runna/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
<a href="https://runna.nullean.net"><img src="https://img.shields.io/badge/docs-runna.nullean.net-20a0a0?style=flat-square" alt="Docs"></a>
</p>
Expand All @@ -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;
Expand Down Expand Up @@ -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
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net11.0</TargetFramework>
<!-- the /// comments become each target's description in the help -->
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<ItemGroup>
<Compile Include="Program.fs" />
<PackageReference Include="Runna.Fs" Version="0.2.0" />
</ItemGroup>
</Project>
```

```fsharp
open Nullean.Runna.Fs
open Proc.Fs

type Target =
/// Delete build output
| Clean
/// Build the solution
| Build
/// Build, then run the tests
| Test

[<EntryPoint>]
let main argv =
let app = RunnaApp<Target>("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

Expand Down
7 changes: 4 additions & 3 deletions build/scripts/Program.fs
Original file line number Diff line number Diff line change
Expand Up @@ -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 (<UseArtifactsOutput>): `.artifacts/bin/<Project>/release/`, every package being single-TFM
let private assembliesDir (packageId: string) = $".artifacts/bin/{packageId}/release"
/// Unified artifacts layout (<UseArtifactsOutput>): `.artifacts/bin/<Project>/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"

[<EntryPoint>]
let main argv =
Expand Down Expand Up @@ -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 }
Expand Down
6 changes: 3 additions & 3 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
20 changes: 10 additions & 10 deletions docs/runna-landing.html
Original file line number Diff line number Diff line change
Expand Up @@ -424,18 +424,18 @@ <h1>runna build.<br/>runna <em>test</em>.</h1>
</p>
<div class="pkg-commands">
<div class="pkg-row">
<button class="pkg-cmd" data-pkg="Nullean.Runna" onclick="copyPkg(this)">
<span class="pkg-cmd-text"><span class="pkg-cmd-dim">dotnet add package </span>Nullean.Runna</span>
<button class="pkg-cmd" data-pkg="Runna" onclick="copyPkg(this)">
<span class="pkg-cmd-text"><span class="pkg-cmd-dim">dotnet add package </span>Runna</span>
<span class="pkg-cmd-icon" aria-hidden="true">⎘</span>
</button>
<a class="pkg-nuget" href="https://www.nuget.org/packages/Nullean.Runna" target="_blank" rel="noopener" title="View on NuGet">nuget ↗</a>
<a class="pkg-nuget" href="https://www.nuget.org/packages/Runna" target="_blank" rel="noopener" title="View on NuGet">nuget ↗</a>
</div>
<div class="pkg-row">
<button class="pkg-cmd" data-pkg="Nullean.Runna.Fs" onclick="copyPkg(this)">
<span class="pkg-cmd-text"><span class="pkg-cmd-dim">dotnet add package </span>Nullean.Runna.Fs</span>
<button class="pkg-cmd" data-pkg="Runna.Fs" onclick="copyPkg(this)">
<span class="pkg-cmd-text"><span class="pkg-cmd-dim">dotnet add package </span>Runna.Fs</span>
<span class="pkg-cmd-icon" aria-hidden="true">⎘</span>
</button>
<a class="pkg-nuget" href="https://www.nuget.org/packages/Nullean.Runna.Fs" target="_blank" rel="noopener" title="View on NuGet">nuget ↗</a>
<a class="pkg-nuget" href="https://www.nuget.org/packages/Runna.Fs" target="_blank" rel="noopener" title="View on NuGet">nuget ↗</a>
</div>
</div>
<div class="actions">
Expand Down Expand Up @@ -559,7 +559,7 @@ <h2 class="section-title">C# or F#.<br/>Then run it.</h2>
<div class="code-panel" data-lang="csharp">
<div class="code-panel-head">build.cs</div>
<pre><span class="c-kw">#!/usr/bin/env -S dotnet run --</span>
<span class="c-kw">#:package</span> Nullean.Runna@0.1.0
<span class="c-kw">#:package</span> Runna@0.2.0
<span class="c-kw">#:property</span> GenerateDocumentationFile=true
<span class="c-kw">#:property</span> NoWarn=CS1591
<span class="c-kw">using</span> <span class="c-ns">Nullean.Runna</span>;
Expand Down Expand Up @@ -621,8 +621,8 @@ <h2 class="section-title">C# or F#.<br/>Then run it.</h2>
</p>
<p class="section-sub">
The package READMEs cover the full DSL:
<a href="https://github.com/nullean/runna/blob/main/src/Nullean.Runna/README.md">Nullean.Runna</a> for C# and
<a href="https://github.com/nullean/runna/blob/main/src/Nullean.Runna.Fs/README.md">Nullean.Runna.Fs</a> for F#.
<a href="https://github.com/nullean/runna/blob/main/src/Nullean.Runna/README.md">Runna</a> for C# and
<a href="https://github.com/nullean/runna/blob/main/src/Nullean.Runna.Fs/README.md">Runna.Fs</a> for F#.
</p>
</div>
</section>
Expand Down Expand Up @@ -657,7 +657,7 @@ <h2>runna build.<br/>Ship it.</h2>
<text x="12" y="23" font-family="JetBrains Mono, ui-monospace, monospace" font-size="13" font-weight="700" fill="#1F9E9E">&gt; nullean_</text>
</svg>
</a>
<span>Nullean.Runna — MIT licensed</span>
<span>runna — MIT licensed</span>
</span>
<span>
<a href="running/">choosing what runs</a> ·
Expand Down
2 changes: 1 addition & 1 deletion plans/top-level-field-dsl.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
4 changes: 2 additions & 2 deletions src/Nullean.Runna.Fs/Nullean.Runna.Fs.fsproj
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@
<SignAssembly>true</SignAssembly>
<AssemblyOriginatorKeyFile>..\..\build\keys\keypair.snk</AssemblyOriginatorKeyFile>

<PackageId>Nullean.Runna.Fs</PackageId>
<Title>Nullean.Runna.Fs - F# DU-based build target DSL</Title>
<PackageId>Runna.Fs</PackageId>
<Title>Runna.Fs - F# DU-based build target DSL</Title>
<Description>F# DU/match binding over Nullean.Runna — exhaustive, typed, namespaced build targets.</Description>
<PackageTags>build;make;targets;build-automation;fsharp</PackageTags>
</PropertyGroup>
Expand Down
8 changes: 4 additions & 4 deletions src/Nullean.Runna.Fs/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
4 changes: 2 additions & 2 deletions src/Nullean.Runna/Nullean.Runna.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
<SignAssembly>true</SignAssembly>
<AssemblyOriginatorKeyFile>..\..\build\keys\keypair.snk</AssemblyOriginatorKeyFile>

<PackageId>Nullean.Runna</PackageId>
<Title>Nullean.Runna - typed namespaced build target DSL</Title>
<PackageId>Runna</PackageId>
<Title>Runna - typed namespaced build target DSL</Title>
<Description>Property-dispatch build target DSL with Argh-quality help and per-target typed CLI arguments.</Description>
<PackageTags>build;make;targets;build-automation;cli</PackageTags>
</PropertyGroup>
Expand Down
12 changes: 6 additions & 6 deletions src/Nullean.Runna/README.md
Original file line number Diff line number Diff line change
@@ -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@<version>` as below. It requires .NET 11.
Or, in a file-based app such as `build.cs`, `#:package Runna@<version>` 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;
Expand Down Expand Up @@ -219,7 +219,7 @@ and [just](https://runna.nullean.net/just).

`RunnaApp.Execute<TBuild>(args)` discovers targets from a `RunnaBuild` class instead: `Target` properties, `[Flag]` and `[GlobalOption]` properties, and nested `Namespace` classes. A dependency on a `Target<T>` 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

Expand Down
4 changes: 2 additions & 2 deletions src/Nullean.Runna/skills/nullean-runna/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
Loading