Update multi-file 'dotnet run file' documentation

documentation/general/dotnet-run-file.md

@@ -10,12 +10,6 @@ dotnet run file.cs
 > [!NOTE]
 > This document describes the ideal final state, but the feature will be implemented in [stages](#stages).
 
-> [!CAUTION]
-> The current implementation has been limited to single file support for the initial preview
-> (as if the implicit project file had `<EnableDefaultItems>false</EnableDefaultItems>` and an explicit `<Compile Include="file.cs" />`),
-> but this proposal describes a situation where all files in the target directory are included.
-> Once a final decision is made, the proposal will be updated.
-
 ## Motivation
 
 File-based programs
@@ -29,7 +23,8 @@ Previous file-based approaches like scripting are a variant of C# and as such ha
 
 ## Implicit project file
 
-The [guiding principle](#guiding-principle) implies that we can think of file-based programs as having an implicit project file.
+The [guiding principle](#guiding-principle) implies that we can think of file-based programs as having an implicit project file
+(also known as a virtual project file because it exists only in memory unless the file-based program is converted to a project-based program).
 
 The implicit project file is the default project that would be created by running `dotnet new console`.
 This means that the behavior of `dotnet run file.cs` can change between SDK versions if the `dotnet new console` template changes.
@@ -43,20 +38,26 @@ In fact, this command simply materializes the [implicit project file](#implicit-
 This action should not change the behavior of the target program.
 
 ```ps1
-dotnet project convert
+dotnet project convert file.cs
 ```
 
+The command takes a path which can be either
+- path to the entry-point file in case of single entry-point programs, or
+- path to the target directory (then all entry points are converted;
+  it is not possible to convert just a single entry point in multi-entry-point program).
+
 ## Target path
 
 The path passed to `dotnet run ./some/path.cs` is called *the target path*.
-If it is a file, it is called *the target file*.
-*The target directory* is the directory of the target file, or the target path if it is not a file.
+The target path must be a file which has the `.cs` file extension, but we could allow folders as well in the future.
+*The target directory* is the directory of the target file.
 
-We can consider adding an option like `dotnet run --from-stdin` which would read the C# file from the standard input.
+We can consider adding an option like `dotnet run --cs-from-stdin` which would read the C# file from the standard input
+(or `dotnet run -` although then it's unclear which programming language the input is in)
 In this case, the current working directory would not be used to search for project or other C# files,
 the compilation would consist solely of the single file read from the standard input.
 Similarly, it could be possible to specify the whole C# source text in a command-like argument
-like `dotnet run --code 'Console.WriteLine("Hi")'`.
+like `dotnet run --cs-code 'Console.WriteLine("Hi")'`.
 
 ## Integration into the existing `dotnet run` command
 
@@ -65,8 +66,7 @@ specifically `file.cs` is passed as the first command-line argument to the targe
 We preserve this behavior to avoid a breaking change.
 The file-based build and run kicks in only when:
 - a project file cannot be found (in the current directory or via the `--project` option), and
-- if the target path is a file, it has the `.cs` file extension, and
-- the target path (file or directory) exists.
+- if the target file exists and has the `.cs` file extension.
 
 > [!NOTE]
 > This means that `dotnet run path` stops working when a file-based program [grows up](#grow-up) into a project-based program.
@@ -85,7 +85,8 @@ The file-based build and run kicks in only when:
 
 File-based programs are processed by `dotnet run` equivalently to project-based programs unless specified otherwise in this document.
 For example, the remaining command-line arguments after the first argument (the target path) are passed through to the target app
-(except for the arguments recognized by `dotnet run` unless they are after the `--` separator).
+(except for the arguments recognized by `dotnet run` unless they are after the `--` separator)
+and working directory is not changed (e.g., `cd /x/ && dotnet run /y/file.cs` runs the program in directory `/x/`).
 
 ## Entry points
 
@@ -97,6 +98,11 @@ to check whether the file contains an entry point (top-level statements or a val
 (We cannot simply use Roslyn APIs to detect entry points ourselves because parsing depends on conditional symbols like those from `<DefineConstants>`
 and we can reliably know the set of those only after invoking MSBuild, and doing that up front would be an unnecessary performance hit just to detect entry points.)
 
+Similarly, during [grow up](#grow-up), we ask Roslyn via MSBuild to give us the set of entry-point files
+(we can also use this to ask user during the conversion whether they want to continue despite compilation errors if there are any).
+
+## Multiple C# files
+
 Because of the [implicit project file](#implicit-project-file),
 other files in the target directory or its subdirectories are included in the compilation.
 For example, other `.cs` files but also `.resx` (embedded resources).
@@ -135,9 +141,9 @@ That's because it might be perfectly reasonable to have file-based programs nest
 
 ### Multiple entry points
 
-If there are multiple entry-point files in the target directory, the target path must be a file
-(an error is reported if it points to a directory instead).
-Then the build ignores other entry-point files.
+If there are multiple entry-point files in the target directory, the build ignores other entry-point files.
+It is an error to have an entry-point file in a subdirectory of the target directory
+(because it is unclear how such program should be converted to a project-based one).
 
 Thanks to this, it is possible to have a structure like
 ```
@@ -147,7 +153,7 @@ App/Program2.cs
 ```
 where either `Program1.cs` or `Program2.cs` can be run and both of them have access to `Util.cs`.
 
-In this case, there are multiple implicit projects
+Behind the scenes, there are multiple implicit projects
 (and during [grow up](#grow-up), multiple project files are materialized
 and the original C# files are moved to the corresponding project subdirectories):
 ```
@@ -161,26 +167,31 @@ App/Program2/Program2.csproj
 The generated folders might need to be named differently to avoid clashes with existing folders.
 
 The entry-point projects (`Program1` and `Program2` in our example)
-have the shared `.cs` files source-included via `<Content Include="../Shared/**/*.cs" />`.
-We could consider having the projects directly in the top-level folder instead
-but that might result in clashes of build outputs that are not project-scoped, like `project.assets.json`.
-If we did that though, it would be enough to exclude the other entry points rather than including all the shared `.cs` files.
-
-Unless the [artifacts output layout][artifacts-output] is used (which is recommended),
-those implicit projects mean that build artifacts are placed under those implicit directories
-even though they don't exist on disk prior to build:
-```
-App/Program1/bin/
-App/Program1/obj/
-App/Program2/bin/
-App/Program2/obj/
+have the shared `.cs` files source-included via `<Compile Include="../Shared/**/*.cs" />`.
+
+We could consider using `InternalsVisibleTo` attribute but that might result in slight differences between single- and multi-entry-point programs
+(if not now then perhaps in the future if [some "more internal" accessibility](https://github.com/dotnet/csharplang/issues/6794) is added to C# which doesn't respect `InternalsVisibleTo`)
+which would be undesirable when users start with a single entry point and later add another.
+Also, `InternalsVisibleTo` needs to be added into a C# file as an attribute, or via a complex-looking `AssemblyAttribute` item group into the `.csproj` like:
+
+```xml
+<ItemGroup>
+  <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleToAttribute" _Parameter1="App.Shared" />
+</ItemGroup>
 ```
 
+## Build outputs
+
+Build outputs are placed in a temp directory under a subdirectory whose name is hashed file path of the entry point
+and which is restricted to the current user per [runtime guidelines][temp-guidelines].
+Apart from keeping the source directory clean, this also avoids clashes of build outputs that are not project-scoped, like `project.assets.json`, in the case of multiple entry-point files.
+
 ## Directives for project metadata
 
-It is possible to specify some project metadata via [ignored C# directives][ignored-directives].
+It is possible to specify some project metadata via *project directives*
+which are [ignored][ignored-directives] by the C# language but recognized by the SDK CLI.
 Directives `sdk`, `package`, and `property` are translated into `<Project Sdk="...">`, `<PackageReference>`, and `<Property>` project elements, respectively.
-Other directives result in a warning, reserving them for future use.
+Other directives result in an error, reserving them for future use.
 
 ```cs
 #:sdk Microsoft.NET.Sdk.Web
@@ -189,7 +200,8 @@ Other directives result in a warning, reserving them for future use.
 #:package System.CommandLine 2.0.0-*
 ```
 
-The value must be separated from the name of the directive by white space and any leading and trailing white space is not considered part of the value.
+The value must be separated from the name of the directive by white space (`@` is additionally allowed separator for the package directive)
+and any leading and trailing white space is not considered part of the value.
 Any value can optionally have two parts separated by a space (more whitespace characters could be allowed in the future).
 The value of the first `#:sdk` is injected into `<Project Sdk="{0}">` with the separator (if any) replaced with `/`,
 and the subsequent `#:sdk` directive values are split by the separator and injected as `<Sdk Name="{0}" Version="{1}" />` elements (or without the `Version` attribute if there is no separator).
@@ -203,10 +215,13 @@ Because these directives are limited by the C# language to only appear before th
 dotnet CLI can look for them via a regex or Roslyn lexer without any knowledge of defined conditional symbols
 and can do that efficiently by stopping the search when it sees the first "C# token".
 
-We do not limit these directives to appear only in entry point files.
-Indeed, it might be beneficial to let a non-entry-point file like `Util.cs` be self-contained and have all the `#:package`s it needs specified in it,
-which also makes it possible to share it independently or symlink it to multiple script folders.
-This is also similar to `global using`s which users usually put into a single file but don't have to.
+It is an error if a project directive appears in a non-entry-point file.
+Otherwise it is unclear how the CLI would determine which files to parse directives from
+(presumably we would want to exclude other entry points but the CLI defers to the compiler to detect entry points).
+We could relax this in the future because it would allow:
+- a non-entry-point file like `Util.cs` to be self-contained and have all the `#:package`s it needs specified in it,
+- which would also make it possible to share it independently or symlink it to multiple script folders,
+- and it would be similar to `global using`s which users usually put into a single file but don't have to.
 
 We could consider deduplicating `#:` directives
 (e.g., properties could be concatenated via `;`, more specific package versions could override less specific ones),
@@ -266,6 +281,10 @@ or as the first argument if it makes sense for them.
 We could also add `dotnet compile` command that would be the equivalent of `dotnet build` but for file-based programs
 (because "compiling" might make more sense for file-based programs than "building").
 
+`dotnet clean` could be extended to support cleaning [the output directory](#build-outputs),
+e.g., via `dotnet clean --file-based-program <path-to-entry-point>`
+or `dotnet clean --all-file-based-programs`.
+
 ### `dotnet package add`
 
 Adding package references via `dotnet package add` could be supported for file-based programs as well,
@@ -313,3 +332,4 @@ Instead of implicitly including files from the target directory, the importing c
 [artifacts-output]: https://learn.microsoft.com/dotnet/core/sdk/artifacts-output
 [ignored-directives]: https://github.com/dotnet/csharplang/blob/main/proposals/ignored-directives.md
 [shebang]: https://en.wikipedia.org/wiki/Shebang_%28Unix%29
+[temp-guidelines]: https://github.com/dotnet/runtime/blob/d0e6ce8332a514d70b635ca4829bf863157256fe/docs/design/security/unix-tmp.md