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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]
#:property GenerateDocumentationFile=true
#:property NoWarn=CS1591
Expand Down
1 change: 1 addition & 0 deletions docs/_docset.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ branding:

toc:
- file: index.md
- file: getting-started.md
- file: running.md
- file: graph.md
- file: parallel.md
Expand Down
147 changes: 147 additions & 0 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -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 [email protected]
#:property GenerateDocumentationFile=true
#:property NoWarn=CS1591
using Nullean.Runna;
using static Nullean.Runna.Shell;

var app = new RunnaApp<Target>("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);

/// <summary>Delete build output</summary>
record Clean;
/// <summary>Build the solution</summary>
record Build;
/// <summary>Build, then run the tests</summary>
record Test;

union Target(Clean, Build, Test);
```

Targets are the cases of a C# `union`, one `record` each, and the `/// <summary>` 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
<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>
```

and `build/Program.fs`:

```fsharp

Check warning on line 82 in docs/getting-started.md

View workflow job for this annotation

GitHub Actions / docs

Unknown language: 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()
```

```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 <command|target> [options] [<target> [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#.
6 changes: 4 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/makefile.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/runna-landing.html
Original file line number Diff line number Diff line change
Expand Up @@ -405,7 +405,7 @@
<ul class="nav-links">
<li><a href="#features">features</a></li>
<li><a href="#quickstart">quick start</a></li>
<li><a href="running/">docs</a></li>
<li><a href="getting-started/">docs</a></li>
</ul>
<a class="nav-cta" href="https://github.com/nullean/runna">github →</a>
</div>
Expand Down Expand Up @@ -439,7 +439,7 @@ <h1>runna build.<br/>runna <em>test</em>.</h1>
</div>
</div>
<div class="actions">
<a class="btn-primary" href="running/">get started →</a>
<a class="btn-primary" href="getting-started/">get started →</a>
</div>
</div>

Expand Down Expand Up @@ -558,7 +558,7 @@ <h2 class="section-title">C# or F#.<br/>Then run it.</h2>
</div>
<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>
<pre><span class="c-kw">#!/usr/bin/env -S dotnet --</span>
<span class="c-kw">#:package</span> [email protected]
<span class="c-kw">#:property</span> GenerateDocumentationFile=true
<span class="c-kw">#:property</span> NoWarn=CS1591
Expand Down Expand Up @@ -633,7 +633,7 @@ <h2 class="section-title">C# or F#.<br/>Then run it.</h2>
<h2>runna build.<br/>Ship it.</h2>
<p>Typed targets, dependencies first, and help you never have to write.</p>
<div class="actions">
<a class="btn-primary" href="running/">get started →</a>
<a class="btn-primary" href="getting-started/">get started →</a>
<a class="btn-secondary" href="https://github.com/nullean/runna">view on github</a>
</div>
</div>
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 @@ -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 [email protected]

using Nullean.Runna;
Expand Down
2 changes: 1 addition & 1 deletion src/Nullean.Runna/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Or, in a file-based app such as `build.cs`, `#:package Runna@<version>` as below
## Quick start

```csharp
#!/usr/bin/env -S dotnet run --
#!/usr/bin/env -S dotnet --
#:package [email protected]
#:property GenerateDocumentationFile=true
#:property NoWarn=CS1591
Expand Down
2 changes: 1 addition & 1 deletion src/Nullean.Runna/skills/nullean-runna/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]
#:property GenerateDocumentationFile=true
#:property NoWarn=CS1591
Expand Down
Loading