Support attribute trimming opt-in (#1839)

* Support attribute opt-in

* Update docs

* Rename test attributes to match

* Don't pass native SDK assemblies to tests

on Windows

* Update LinkTask

* PR feedback

- Don't warn on duplicate attributes
- Remove comment
- Fix typos and wording
- Use static array
- Rename CheckIsTrimmable -> IsTrimmable

* PR feedback: rename options

- --trim-action -> --trim-mode
-- --default-action -> --action

* Fix ILLink.Tasks test

* PR feedback

- Add plenty of comments
- RootNonTrimmableAssemblies -> ProcessReferencesStep
- Make -reference order stable using List instead of HashSet

* PR feedback

Make GetInputAssemblyPaths private

3 files changed, 25 insertions, 9 deletions

diff --git a/docs/error-codes.md b/docs/error-codes.md
index 3a66bde74..c674f363c 100644
--- a/docs/error-codes.md
+++ b/docs/error-codes.md
@@ -129,6 +129,10 @@ the error code. For example:
 
 #### `IL1038`: Exported type '{type.Name}' cannot be resolved
 
+#### `IL1039`: Reference assembly '{assemblyPath}' could not be loaded
+
+- A reference assembly input passed via -reference could not be loaded.
+
 ----
 ## Warning Codes
 
@@ -1510,6 +1514,15 @@ This is technically possible if a custom assembly defines `DynamicDependencyAttr
   </linker>
   ```
 
+#### `IL2102`: Invalid AssemblyMetadata("IsTrimmable", ...) attribute in assembly 'assembly'. Value must be "True"
+
+- AssemblyMetadataAttribute may be used at the assembly level to turn on trimming for the assembly. The only supported value is "True", but the attribute contained an unsupported value.
+
+  ``` C#
+  // IL2102: Invalid AssemblyMetadata("IsTrimmable", "False") attribute in assembly 'assembly'. Value must be "True"
+  [assembly: AssemblyMetadata("IsTrimmable", "False")] 
+  ```
+
 ## Single-File Warning Codes
 
 #### `IL3000`: 'member' always returns an empty string for assemblies embedded in a single-file app. If the path to the app directory is needed, consider calling 'System.AppContext.BaseDirectory'
diff --git a/docs/illink-options.md b/docs/illink-options.md
index 52d1ea2f9..edd02d7cc 100644
--- a/docs/illink-options.md
+++ b/docs/illink-options.md
@@ -58,22 +58,25 @@ The linker can do the following things on all or individual assemblies
 - `delete`- remove them from the output
 - `save` - save them in memory without linking
 
-You can specify an action per assembly using `-p` option like this:
+You can specify an action per assembly using `--action` option like this:
 
-`illink -p link Foo`
+`illink --action link Foo`
 
 or
 
-`illink -p skip System.Windows.Forms`
+`illink --action skip System.Windows.Forms`
 
-Or you can specify what to do for the core assemblies.
+Or you can specify what to do for the trimmed assemblies.
 
-Core assemblies are the assemblies that belong to the base class library,
-like `System.Private.CoreLib.dll`, `System.dll` or `System.Windows.Forms.dll`.
+A trimmable assembly is any assembly that includes the attribute `System.Reflection.AssemblyMetadata("IsTrimmable", "True")`.
 
-You can specify what action to do on the core assemblies with the option:
+You can specify what action to do on the trimmed assemblies with the option:
 
-`-c skip|copy|link`
+`--trim-mode skip|copy|copyused|link`
+
+You can specify what action to do on assemblies without such an attribute with the option:
+
+`--action copy|link`
 
 ### The output directory
 
diff --git a/docs/illink-tasks.md b/docs/illink-tasks.md
index 50b8883ba..e6566f114 100644
--- a/docs/illink-tasks.md
+++ b/docs/illink-tasks.md
@@ -58,7 +58,7 @@ The linker can be invoked as an MSBuild task, `ILLink`. We recommend not using t
         RootAssemblyNames="@(LinkerRootAssemblies)"
         RootDescriptorFiles="@(LinkerRootDescriptors)"
         OutputDirectory="output"
-        ExtraArgs="-t -c link" />
+        ExtraArgs="-t --trim-mode link" />
 ```
 
 ## Default Linking Behavior