com.elestrago.unity.generated-code-dump 1.0.0

package/Documentation~/examples/dump-in-batch-mode.md

@@ -0,0 +1,43 @@
+# Generated Code Dump — Example: Dump in batch mode
+
+## When to use it
+
+Use it in CI, or as an agent without the Editor window, when you need the whole dump on disk. Turn the per-user setting on, then start Unity in batch mode: with `-quit`, Unity exits only after the dump is complete.
+
+## Snippet
+
+```bash
+PROJECT=/path/to/project
+UNITY=~/Unity/Hub/Editor/6000.0.65f1/Editor/Unity   # your Unity Editor binary
+SETTINGS="$PROJECT/UserSettings/GeneratedCodeDumpSettings.json"
+DUMP="$PROJECT/Library/GeneratedCodeDump"
+
+# Turn the dump on for this checkout, then start Unity; it quits once the dump is done.
+mkdir -p "$PROJECT/UserSettings"
+printf '{"enabled": true}\n' > "$SETTINGS"
+"$UNITY" -batchmode -nographics -projectPath "$PROJECT" -quit -logFile "$PROJECT/dump.log" \
+  || echo "Unity exited with an error: see dump.log"
+
+# Read the dump's log lines, check that it ran and no job is left, and list the result.
+grep '\[Generated Code Dump\]' "$PROJECT/dump.log"
+if ! grep -q '\[Generated Code Dump\] queued' "$PROJECT/dump.log"; then echo "no dump ran: see dump.log"
+elif grep -q '^job' "$DUMP/.work/jobs.txt"; then echo "dump incomplete"
+else echo "dump complete"; fi
+ls "$DUMP"
+
+# Optional: turn it off again, so later batch runs on this machine skip the dump.
+rm "$SETTINGS"
+```
+
+## What you'll see
+
+- The log shows `[Generated Code Dump] queued <N> assemblies, at most <M> compiling at once; output in Library/GeneratedCodeDump/`, where `<N>` counts the queued assemblies and `<M>` is how many compile at once. Unity quits once the dump is done, and `Library/GeneratedCodeDump/` holds one folder per assembly that has generated files, next to `.work/`, the dump's own bookkeeping folder.
+- A batch-mode start with the dump on always runs a *full dump*: a *replay* of every assembly that loads an *analyzer*. A replay runs Unity's compiler once more for one assembly to collect its generated files; an analyzer is a compiler plug-in DLL, which is how source generators ship. See [When a dump runs](../manual.md#when-a-dump-runs).
+- Batch mode has no background thread. The Editor's own thread starts the compiler processes and waits for them, so the dump is complete before `-quit` takes effect. See [Batch mode and CI](../manual.md#batch-mode-and-ci).
+- The wait has a cap: 300 seconds per round of compiles, where a round is as many assemblies as compile at once. For 11 assemblies at 6 at once that is 2 rounds, so at most 600 seconds. Past the cap the log says `[Generated Code Dump] stopped waiting after <seconds> s; the rest of the dump finishes in the next Editor session.` The unfinished *jobs* (one line per requested replay) stay in `.work/jobs.txt`, and the snippet prints `dump incomplete`. The next Editor start with the dump on, batch mode included, picks them up. See [Batch mode and CI](../manual.md#batch-mode-and-ci).
+- A single compiler that runs for more than 300 seconds is stopped and its output ignored, with the warning `[Generated Code Dump] <Assembly>: the compiler ran for over 300 s, so it was stopped and its output is ignored.` See [Warnings and failures](../manual.md#warnings-and-failures).
+- A file whose path is over the OS limit even with every name cut short is skipped, with the warning `[Generated Code Dump] <Assembly>: <N> files skipped: their path is over the <limit>-character limit of this OS; move the project to a shorter path.` and then the skipped paths. `<limit>` is 259 on Windows and 1023 on macOS and Linux. See [Long paths](../manual.md#long-paths).
+- On this repository's example project, on a machine with 12 logical CPUs, a full dump queued 11 assemblies and compiled 6 at once. Compiling took about 1.7 seconds of a 7.5-second batch run (start, import, dump, quit). See [Performance](../manual.md#performance).
+- The settings file is the only switch; there is no command-line flag. While it is on, every batch run of the project, `-runTests` and builds included, runs the same full dump at start and waits for it. See [Batch mode and CI](../manual.md#batch-mode-and-ci).
+
+For contributors: [GeneratedCodeDumper](../api.md#generatedcodedumper), [GeneratedCodeDumpJobs](../api.md#generatedcodedumpjobs)

package/Documentation~/examples/dump-now.md

@@ -0,0 +1,29 @@
+# Generated Code Dump — Example: Dump Now and Open Folder
+
+## When to use it
+
+Use `Tools/Generated Code Dump/Dump Now` for a one-off refresh of the whole dump; it works even while the dump is off. `Tools/Generated Code Dump/Open Folder` opens `Library/GeneratedCodeDump/` in your file browser, and both are also buttons on the `Preferences/Generated Code Dump` page.
+
+## Snippet
+
+```bash
+# First click Tools/Generated Code Dump/Dump Now in the Editor.
+# Then, from the project root, wait until no job is left and list the result.
+DUMP=Library/GeneratedCodeDump
+while grep -q '^job' "$DUMP/.work/jobs.txt" 2>/dev/null; do sleep 1; done
+ls "$DUMP"
+# The Editor log on Linux; on macOS it is ~/Library/Logs/Unity/Editor.log,
+# on Windows %LOCALAPPDATA%\Unity\Editor\Editor.log
+grep '\[Generated Code Dump\]' ~/.config/unity3d/Editor.log | tail -n 5
+```
+
+## What you'll see
+
+- The Console logs `[Generated Code Dump] queued <N> assemblies, at most <M> compiling at once; output in Library/GeneratedCodeDump/`, where `<N>` counts the queued assemblies and `<M>` is how many compile at once. Dump Now runs a *full dump*: a *replay* of every assembly of Unity's latest compile that loads an *analyzer*. A replay runs Unity's compiler once more for one assembly to collect its generated files; an analyzer is a compiler plug-in DLL, which is how source generators ship. See [When a dump runs](../manual.md#when-a-dump-runs).
+- The Editor does not wait. Each replay is a separate compiler process; a background thread starts them and collects their output every 250 ms (four times a second), so the dump keeps going while the Editor is in the background. At most one compiler runs per two logical CPUs, never fewer than 1 or more than 8: 6 on a machine with 12 logical CPUs. See [Performance](../manual.md#performance).
+- Each queued replay is a *job*, one line starting with `job` in `.work/jobs.txt` (`.work/` is the dump's own bookkeeping folder). When all are done, the file holds only its `next <id>` line (the id the next job will get), which is what the snippet's loop waits for. See [When a dump runs](../manual.md#when-a-dump-runs).
+- Each finished assembly's folder is updated to match the new output, and `.work/<Assembly>/` keeps only that replay's compiler arguments (`replay.rsp`) and error log (`errors.sarif`). On Windows `.work/` is hidden, so Open Folder shows only the assembly folders. See [How it works](../manual.md#how-it-works).
+- Neither Dump Now nor Open Folder turns the dump on, so while it is off, later compiles do not refresh the output. They are the only two actions that create anything under `Library/GeneratedCodeDump/` while it is off; Open Folder creates the folder if it is missing. See [Turning it on and off](../manual.md#turning-it-on-and-off).
+- If Unity's compiler or its build folder `Library/Bee/artifacts` is missing, Dump Now logs one warning, such as `[Generated Code Dump] Unity's C# compiler was not found at <path>.`, and queues nothing. The compiler is `DotNetSdkRoslyn/csc.dll`, run with `NetCoreRuntime/dotnet`, both inside the Unity Editor install: under `Editor/Data/` on Windows and Linux, and `Unity.app/Contents/` on macOS. See [Warnings and failures](../manual.md#warnings-and-failures).
+
+For contributors: [GeneratedCodeMenuItems](../api.md#generatedcodemenuitems), [GeneratedCodeDumper](../api.md#generatedcodedumper), [GeneratedCodeDumpFinisher](../api.md#generatedcodedumpfinisher), [GeneratedCodeDumpJobs](../api.md#generatedcodedumpjobs)

package/Documentation~/examples/read-the-dump.md

@@ -0,0 +1,63 @@
+# Generated Code Dump — Example: Read the dump
+
+## When to use it
+
+Use it when you or an AI agent want to see what a source generator really wrote, instead of guessing from the attributes and `partial` declarations. The dump is in `Library/GeneratedCodeDump/`, and grepping the header lines of its files finds a file even when its name was cut short to fit the OS path limit.
+
+## Snippet
+
+```bash
+DUMP=Library/GeneratedCodeDump
+ls "$DUMP"                                                            # one folder per assembly that has generated files
+find "$DUMP/Assembly-CSharp" -type f | sort                           # one assembly's files, one folder per generator assembly
+grep -rl --exclude-dir=.work "Hint: .*ExampleBehaviour" "$DUMP"       # every file whose hint name mentions the type, cut or not
+grep -rl --exclude-dir=.work "partial class ExampleBehaviour" "$DUMP" # the generated parts of one type
+grep -rh --exclude-dir=.work "Dumped: " "$DUMP" | sort | uniq -c      # when the files were dumped
+```
+
+Part of the real dump of this repository's example project, for `Assembly-CSharp` and one asmdef assembly, made by its test generators (`Assets/Example/Generators/`, built from `External/`, not shipped). It is an excerpt: the project's other assemblies are left out. Paths are inside `Library/GeneratedCodeDump/`:
+
+```text
+Assembly-CSharp/GeneratedCodeDump.TestGenerators.Classic/Aux_.g.cs
+Assembly-CSharp/GeneratedCodeDump.TestGenerators.Classic/ExampleBehaviour.generated.cs
+Assembly-CSharp/GeneratedCodeDump.TestGenerators.Classic/ExampleBehaviour~31a944ea.generated.cs
+Assembly-CSharp/GeneratedCodeDump.TestGenerators.Incremental/Example.ExampleBehaviour.Dumpable.g.cs
+Assembly-CSharp/GeneratedCodeDump.TestGenerators.Incremental/Summary.Info.g.cs
+Assembly-CSharp/Unity.SourceGenerators/AssemblyMonoScriptTypes.generated.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Classic/Aux_.g.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Classic/DeepRecord.generated.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Classic/DeepRecord~5fee0560.generated.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Classic/ModuleService.generated.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Incremental/GeneratedCodeDump.Example.Module.Deep.DeepRecord.Dumpable.g.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Incremental/GeneratedCodeDump.Example.Module.ModuleService.Dumpable.g.cs
+GeneratedCodeDump.Example.Module/GeneratedCodeDump.TestGenerators.Incremental/Summary.Info.g.cs
+GeneratedCodeDump.Example.Module/Unity.SourceGenerators/AssemblyMonoScriptTypes.generated.cs
+```
+
+The head of `Assembly-CSharp/GeneratedCodeDump.TestGenerators.Incremental/Example.ExampleBehaviour.Dumpable.g.cs` (the `Dumped:` time changes with every dump):
+
+```csharp
+// <auto-generated/>
+// Dumped: 2026-09-12 10:15:03 UTC
+// Assembly: Assembly-CSharp
+// Generator: GeneratedCodeDump.TestGenerators.Incremental / GeneratedCodeDump.TestGenerators.Incremental.DumpableGenerator
+// Hint: Example.ExampleBehaviour.Dumpable.g.cs
+namespace Example
+{
+	partial class ExampleBehaviour
+```
+
+## What you'll see
+
+- The first folder is the compiled assembly: `Assembly-CSharp`, or an asmdef name such as `GeneratedCodeDump.Example.Module`. The second is the *generator assembly*, the DLL the source generator ships in, such as `Unity.SourceGenerators` for Unity's own. See [Reading the output](../manual.md#reading-the-output).
+- The file name is the *hint name*: the name the generator gave the file, kept exactly as one flat name, with no namespace folders. `Example.ExampleBehaviour.Dumpable.g.cs` is one. See [Reading the output](../manual.md#reading-the-output).
+- `ExampleBehaviour~31a944ea.generated.cs` sits next to `ExampleBehaviour.generated.cs` because two generators in one generator assembly gave the same hint name. One of them gets a *short hash*: a `~` and 8 hex digits computed from that generator's full type name and the hint name, the same on every machine. `DeepRecord~5fee0560.generated.cs` is the same case in the other assembly; which of the two gets the hash is in [Reading the output](../manual.md#reading-the-output).
+- `Aux_.g.cs` was `Aux.g.cs`. `AUX` is a reserved device name on Windows, so the dump adds an `_`. See [Reading the output](../manual.md#reading-the-output).
+- Every file gets four header lines with full names: `Dumped:` (when the compiler that produced it started, in UTC), `Assembly:`, `Generator:` (generator assembly, then the generator's full type name) and `Hint:`. They follow a `// <auto-generated/>` line as above, close a `// <auto-generated>` comment block, or else come first. The file's BOM and line endings are kept. See [Reading the output](../manual.md#reading-the-output).
+- The greps pass `--exclude-dir=.work` to skip `.work/`, the dump's own bookkeeping folder next to the assembly folders. It holds no generated code.
+- A path too long for the OS is cut in this order, stopping as soon as it fits: the assembly folder, then the generator folder, then the file name. Each cut keeps the start of the name and adds a short hash (a *cut name*). The header lines keep the full names, so the `Hint:` grep above still finds a cut file. A file that still does not fit is skipped with the warning `[Generated Code Dump] <Assembly>: <N> files skipped: their path is over the <limit>-character limit of this OS; move the project to a shorter path.`, where `<limit>` is 259 on Windows and 1023 on macOS and Linux. See [Long paths](../manual.md#long-paths).
+- Only assemblies that load an *analyzer*, a compiler plug-in DLL such as a source generator, are *replayed*: compiled once more to collect the generated files. Unity's own `Unity.SourceGenerators` runs on most assemblies, so most of them get an `AssemblyMonoScriptTypes.generated.cs`.
+- Each replay syncs its assembly's whole folder: a file the generators no longer produce is deleted, and an assembly with no generated files has no folder. See [Reading the output](../manual.md#reading-the-output).
+- A file open in another program during a dump is not replaced, so it keeps its older `Dumped:` line; the Console warns and the next dump tries again. See [Warnings and failures](../manual.md#warnings-and-failures).
+
+For contributors: [GeneratedCodeDumpOutput](../api.md#generatedcodedumpoutput), [GeneratedCodeDumpNames](../api.md#generatedcodedumpnames), [GeneratedCodeDumpPathBudget](../api.md#generatedcodedumppathbudget), [GeneratedCodeDumpPaths](../api.md#generatedcodedumppaths)

package/Documentation~/examples/turn-on-the-dump.md

@@ -0,0 +1,33 @@
+# Generated Code Dump — Example: Turn on the dump
+
+## When to use it
+
+Use it when you want the dump for yourself in this project: it is off until you turn it on. In the Editor, click `Tools/Generated Code Dump/Enabled` (checked while on) or tick `Dump generated code` on the `Preferences/Generated Code Dump` page; without the Editor window, for example as an AI agent, write the settings file from a shell as below.
+
+## Snippet
+
+```bash
+# From the project root. The menu, the Preferences toggle and this command all write the same file,
+# and both an open Editor and later batch-mode runs read it.
+mkdir -p UserSettings
+printf '{"enabled": true}\n' > UserSettings/GeneratedCodeDumpSettings.json
+
+# To turn it off again, write false, or delete the file (no file means off).
+# printf '{"enabled": false}\n' > UserSettings/GeneratedCodeDumpSettings.json
+
+# The switch is yours alone, so check that git leaves UserSettings/ out.
+git check-ignore -q UserSettings/GeneratedCodeDumpSettings.json && echo "ignored" || echo "add /[Uu]ser[Ss]ettings/ to .gitignore"
+```
+
+## What you'll see
+
+- An open Editor picks up the change within about a second, even while it is in the background. If `UserSettings/` did not exist yet, it notices the new folder too. A closed Editor reads the file when it next starts, and so does a batch-mode run. See [Turning it on and off](../manual.md#turning-it-on-and-off).
+- The switch is the file `UserSettings/GeneratedCodeDumpSettings.json`, in Unity's per-user folder. It survives deleting `Library/`, and each developer turns the dump on for themselves. If the last line of the snippet does not print `ignored`, add `/[Uu]ser[Ss]ettings/` to `.gitignore`, or the switch gets committed.
+- Turning it on starts a *full dump*. The Console logs `[Generated Code Dump] queued <N> assemblies, at most <M> compiling at once; output in Library/GeneratedCodeDump/`, where `<N>` is the number of assemblies to compile again and `<M>` how many compile at the same time. The file `Library/GeneratedCodeDump/.work/enabled-session` appears.
+- A full dump is a *replay* of every assembly that loads an *analyzer*. A replay runs Unity's own compiler again for one assembly and keeps the files its source generators write. An analyzer is a plug-in DLL for the compiler; source generators ship as analyzers, so an assembly without one has nothing to dump.
+- Every later Editor start with the dump on runs a full dump too. The `enabled-session` file is how the dump tells a new Editor start from a domain reload. See [When a dump runs](../manual.md#when-a-dump-runs).
+- After each compile, only the assemblies it rebuilt, and of those only the ones that load an analyzer, are replayed. An assembly that failed to compile is skipped until it compiles again. If you delete `Library/GeneratedCodeDump/` while the dump is on, the next domain reload runs a full dump. See [When a dump runs](../manual.md#when-a-dump-runs).
+- A file that is not a JSON object with `enabled` set to `true` or `false` counts as off, and the Console warns `[Generated Code Dump] <full path> is not valid: expected {"enabled": true} or false. The dump is off.` It warns again only when the file changes and is still invalid. The exact file format is in [Turning it on and off](../manual.md#turning-it-on-and-off).
+- Turning the dump off drops the replays that have not started yet. `Library/GeneratedCodeDump/` stays as it is, but later compiles no longer refresh it. See [Turning it on and off](../manual.md#turning-it-on-and-off).
+
+For contributors: [GeneratedCodeMenuItems](../api.md#generatedcodemenuitems), [GeneratedCodeDumpSettingsProvider](../api.md#generatedcodedumpsettingsprovider), [GeneratedCodeDumpSettings](../api.md#generatedcodedumpsettings), [GeneratedCodeDumpSettingsFile](../api.md#generatedcodedumpsettingsfile), [GeneratedCodeDumpSettingsWatcher](../api.md#generatedcodedumpsettingswatcher), [GeneratedCodeDumpSession](../api.md#generatedcodedumpsession)

package/Documentation~/examples.md

@@ -0,0 +1,24 @@
+<!-- examples:curated -->
+
+# Generated Code Dump — Examples
+
+Four short tasks. Each one stands on its own, gives a shell snippet (run from the Unity project root unless it sets `$PROJECT`), and says what you'll see afterwards.
+
+There is no C# API to call. You drive the package with the `Tools/Generated Code Dump/` menu, the `Preferences/Generated Code Dump` page, or the per-user settings file `UserSettings/GeneratedCodeDumpSettings.json`. All three change the same switch.
+
+## Contents
+
+| Example | You want to… |
+|---------|--------------|
+| [Turn on the dump](examples/turn-on-the-dump.md) | switch the dump on or off for yourself in this project, from the Editor or from a shell |
+| [Read the dump](examples/read-the-dump.md) | find and read the code a source generator wrote for a type, even when its file name was cut short |
+| [Dump Now and Open Folder](examples/dump-now.md) | refresh the whole dump once, even while it is off, and open its folder |
+| [Dump in batch mode](examples/dump-in-batch-mode.md) | get a complete dump from CI or an agent, with no Editor window |
+
+## Notes
+
+- Paths are relative to the Unity project root, unless a snippet sets `$PROJECT`.
+- The switch is yours alone. It lives in `UserSettings/`, Unity's per-user folder, which Unity's standard `.gitignore` keeps out of version control. A missing or invalid file means off. See [Turning it on and off](manual.md#turning-it-on-and-off).
+- The dump is in `Library/GeneratedCodeDump/`: one folder per assembly that has generated files, then one per generator assembly (the DLL a source generator ships in), then the files. Next to them sits `.work/`, the dump's own bookkeeping folder, so pass `--exclude-dir=.work` when you grep. See [Reading the output](manual.md#reading-the-output).
+- The dump never changes Unity's own compile output under `Library/Bee/` and never breaks the project's compile. Every problem shows up as a Console warning that starts with `[Generated Code Dump]`. See [Warnings and failures](manual.md#warnings-and-failures).
+- These pages are written by hand. The `<!-- examples:curated -->` marker on the first line tells the `unity-package-docs` skill to leave this index and every example page as they are.