Skip to content

Commit e6eb380

Browse files
kzukzu
committed
Restructure samples to demonstrate #include/#ref; update docs + tool metadata
1 parent e74fb46 commit e6eb380

16 files changed

Lines changed: 59 additions & 40 deletions

File tree

‎readme.md‎

Lines changed: 39 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,6 @@
55
[![EULA](https://img.shields.io/badge/EULA-OSMF-blue?labelColor=black&color=C9FF30)](https://github.com/devlooped/oss/blob/main/osmfeula.txt)
66
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/devlooped/oss/blob/main/license.txt)
77

8-
<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
9-
## Open Source Maintenance Fee
10-
11-
To ensure the long-term sustainability of this project, users of this package who generate
12-
revenue must pay an [Open Source Maintenance Fee](https://opensourcemaintenancefee.org).
13-
While the source code is freely available under the terms of the [License](license.txt),
14-
this package and other aspects of the project require [adherence to the Maintenance Fee](osmfeula.txt).
15-
16-
To pay the Maintenance Fee, [become a Sponsor](https://github.com/sponsors/devlooped) at the proper
17-
OSMF tier. A single fee covers all of [Devlooped packages](https://www.nuget.org/profiles/Devlooped).
18-
19-
<!-- https://github.com/devlooped/.github/raw/main/osmf.md -->
208
<!-- #content -->
219

2210
## What is `go#`?
@@ -29,6 +17,7 @@ It shines for:
2917
- Fast iteration with smart caching (subsequent runs are near-instant when nothing changed)
3018
- Easy sharing of small utilities (just the `.cs` file)
3119

20+
3221
## Usage
3322

3423
```console
@@ -39,35 +28,55 @@ dnx go app.cs
3928
dnx go app.cs -- arg1 arg2
4029

4130
# Pass arguments to the underlying `dotnet publish`
42-
dnx go app.cs /p:PublishAot=true -- arg1 arg2
31+
dnx go app.cs /p:MyProp=true -- arg1 arg2
4332
```
4433

45-
## Performance
34+
The default mode publishes the app and then runs the resulting executable,
35+
with smart up-to-date checks of every C# file used to build the app (including
36+
`#include` and `#ref` directives, transitively).
37+
38+
A dev mode is also available for faster iteration, which skips the publish step
39+
and runs the app directly from the build output without the optimizations
40+
applied by dotnet to published executables (i.e. AOT, RID-specific optimizations):
41+
42+
```console
43+
dnx go dev app.cs
4644

47-
The main advantage of `go#` is **fast unchanged re-runs**. The numbers below compare the three common approaches on pristine sources.
45+
# Pass arguments to your app
46+
dnx go dev app.cs -- arg1 arg2
4847

49-
**PublishAot=false**
48+
# Pass arguments to the underlying `dotnet run`
49+
dnx go dev app.cs /p:Configuration=Release -- arg1 arg2
50+
```
5051

51-
| Example | `dotnet run app.cs` | `go app.cs` | `dotnet publish ...; app.exe` |
52-
|--------------------|---------------------|--------------|-------------------------------|
53-
| a) no includes | 1.306s | 0.264s | 5.044s |
54-
| b) #include | 1.169s | 0.198s | 4.857s |
55-
| c) #ref | 4.605s | 0.191s | 6.243s |
56-
| d) #include + #ref | 13.079s | 0.227s | 7.320s |
52+
## Performance
5753

58-
**PublishAot=true** (NativeAOT)
54+
The main advantage of `go#` is **fast unchanged re-runs**.
55+
The two core scenarios for `go#` file-based apps are:
56+
* While tweaking 👉 `dnx go dev app.cs` (optimized `dotnet run app.cs`)
57+
* When stable 👉 `dnx go app.cs` (optimized `dotnet publish app.cs; app[.exe]`)
5958

60-
| Example | `dotnet run app.cs` | `go app.cs` | `dotnet publish ...; app.exe` |
61-
|--------------------|---------------------|--------------|-------------------------------|
62-
| a) no includes | — | 0.227s | 12.436s |
63-
| b) #include | — | 0.164s | 11.145s |
64-
| c) #ref | — | 0.183s | 32.874s |
65-
| d) #include + #ref | — | 0.269s | 21.888s |
59+
The numbers below showcase both scenarios, comparing `go#` to `dotnet run` and
60+
`dotnet publish` for a file-based app with different combinations of `#include` and `#ref` directives.
6661

67-
**Observation**: `go#` re-runs are fast (~0.16–0.27s) — just launching the cached executable when no changes are detected in any of the input files (including the `#include` and `#ref` dependencies).
62+
<-- include src/Benchmarks/BenchmarkDotNet.Artifacts/results/GoBenchmarks-report-github.md -->
6863

6964
<!-- #content -->
7065
---
66+
67+
<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
68+
## Open Source Maintenance Fee
69+
70+
To ensure the long-term sustainability of this project, users of this package who generate
71+
revenue must pay an [Open Source Maintenance Fee](https://opensourcemaintenancefee.org).
72+
While the source code is freely available under the terms of the [License](license.txt),
73+
this package and other aspects of the project require [adherence to the Maintenance Fee](osmfeula.txt).
74+
75+
To pay the Maintenance Fee, [become a Sponsor](https://github.com/sponsors/devlooped) at the proper
76+
OSMF tier. A single fee covers all of [Devlooped packages](https://www.nuget.org/profiles/Devlooped).
77+
78+
<!-- https://github.com/devlooped/.github/raw/main/osmf.md -->
79+
---
7180
<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->
7281
# Sponsors
7382

samples/incref/app.cs renamed to samples/#include + #ref/app.cs

File renamed without changes.

‎samples/#include + #ref/app.stamp‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
input=C:/Code/go/samples/#include + #ref/reflib.cs
2+
bin=C:/Users/kzu/AppData/Local/Temp/dotnet/runfile/reflib-8aae09897a040a6d1bac9731dbdc2f1e0e630f1a5564244c139eb4a6ba497fa5/bin/release/reflib.dll
3+
input=C:/Code/go/samples/#include + #ref/inclib.cs
4+
input=C:/Code/go/samples/#include + #ref/app.cs
5+
bin=C:/Users/kzu/AppData/Local/Temp/dotnet/runfile/app-36bda31a755da169e4319c50303dc3a86879b4ffca15bc4e32a93e0c791f393a/bin/release/app.dll
6+
app=C:/Code/go/samples/#include + #ref/artifacts/app/app.exe

samples/incref/inclib.cs renamed to samples/#include + #ref/inclib.cs

File renamed without changes.

samples/incref/reflib.cs renamed to samples/#include + #ref/reflib.cs

File renamed without changes.

samples/include/app.cs renamed to samples/#include/app.cs

File renamed without changes.

‎samples/#include/app.stamp‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
input=C:/Code/go/samples/#include/lib.cs
2+
input=C:/Code/go/samples/#include/app.cs
3+
bin=C:/Users/kzu/AppData/Local/Temp/dotnet/runfile/app-ad05c52a3b8ea6d3b51fad72efbcebeb3461c93f01c5d1ea5b5dc26fb183842b/bin/release/app.dll
4+
app=C:/Code/go/samples/#include/artifacts/app/app.exe

samples/include/lib.cs renamed to samples/#include/lib.cs

File renamed without changes.

samples/ref/app.cs renamed to samples/#ref/app.cs

File renamed without changes.

‎samples/#ref/app.stamp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
input=C:/Code/go/samples/#ref/lib.cs
2+
bin=C:/Users/kzu/AppData/Local/Temp/dotnet/runfile/lib-0fc901df1b6f03463d8171d60610a6a0bf15e0a24483673932fc5fbfcf9e2a12/bin/release/lib.dll
3+
input=C:/Code/go/samples/#ref/app.cs
4+
bin=C:/Users/kzu/AppData/Local/Temp/dotnet/runfile/app-5e3076bfd25050b7f63e7ee4a1ecfe190f67b6b664cee3fa56de0f7bdc26348c/bin/release/app.dll
5+
app=C:/Code/go/samples/#ref/artifacts/app/app.exe

0 commit comments

Comments
 (0)