add BundleExtraAssemblies package option for new .NET 5 reference model

This commit is contained in:
Jesse Plamondon-Willard 2021-09-16 22:47:05 -04:00
parent bf10aeef0a
commit f5807e22be
No known key found for this signature in database
GPG Key ID: CF8B1456B3E29F49
5 changed files with 244 additions and 57 deletions

View File

@ -39,10 +39,9 @@ change how these work):
* **Copy files into the `Mods` folder:**
The package automatically copies your mod's DLL and PDB files, `manifest.json`, [`i18n`
files](https://stardewvalleywiki.com/Modding:Translations) (if any), the `assets` folder (if
any), and [build output](https://stackoverflow.com/a/10828462/262123) into your game's `Mods`
folder when you rebuild the code, with a subfolder matching the mod's project name. That lets you
try the mod in-game right after building it.
files](https://stardewvalleywiki.com/Modding:Translations) (if any), and the `assets` folder (if
any) into the `Mods` folder when you rebuild the code, with a subfolder matching the mod's project
name. That lets you try the mod in-game right after building it.
* **Create release zip:**
The package adds a zip file in your project's `bin` folder when you rebuild the code, in the
@ -189,11 +188,63 @@ The folder path where the release zip is created (defaults to the project's `bin
<th>effect</th>
</tr>
<tr>
<td><code>CopyModReferencesToBuildOutput</code></td>
<td><code>BundleExtraAssemblies</code></td>
<td>
Whether to copy game and framework DLLs into the mod folder (default `false`). This is useful for
unit test projects, but not needed for mods that'll be run through SMAPI.
**Most mods should not change this option.**
By default (when this is _not_ enabled), only the mod files [normally considered part of the
mod](#Features) will be added to the release `.zip` and copied into the `Mods` folder (i.e.
"deployed"). That includes the assembly files (`*.dll`, `*.pdb`, and `*.xml`) for your mod project,
but any other DLLs won't be deployed.
Enabling this option will add _all_ dependencies to the build output, then deploy _some_ of them
depending on the comma-separated value(s) you set:
<table>
<tr>
<th>option</th>
<th>result</th>
</tr>
<tr>
<td><code>ThirdParty</code></td>
<td>
Assembly files which don't match any other category.
</td>
</tr>
<tr>
<td><code>System</code></td>
<td>
Assembly files whose names start with `Microsoft.*` or `System.*`.
</td>
</tr>
<tr>
<td><code>Game</code></td>
<td>
Assembly files which are part of MonoGame, SMAPI, or Stardew Valley.
</td>
</tr>
<tr>
<td><code>All</code></td>
<td>
Equivalent to `System, Game, ThirdParty`.
</td>
</tr>
</table>
Most mods should omit the option. Some mods may need `ThirdParty` if they bundle third-party DLLs
with their mod. The other options are mainly useful for unit tests.
When enabling this option, you should **manually review which files get deployed** and use the
`IgnoreModFilePaths` or `IgnoreModFilePatterns` options to exclude files as needed.
</td>
</tr>
@ -327,16 +378,15 @@ The configuration will check your custom path first, then fall back to the defau
still compile on a different computer).
### How do I change which files are included in the mod deploy/zip?
For custom files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123).
(If your project references another mod, make sure the reference is [_not_ marked 'copy
local'](https://msdn.microsoft.com/en-us/library/t1zz5y8c(v=vs.100).aspx).)
To exclude a file the package copies by default, see `IgnoreModFilePatterns` under
[_configure_](#configure).
* For normal files, you can [add/remove them in the build output](https://stackoverflow.com/a/10828462/262123).
* For assembly files (`*.dll`, `*.exe`, `*.pdb`, or `*.xml`), see the
[`BundleExtraAssemblies` option](#configure).
* To exclude a file which the package copies by default, see the [`IgnoreModFilePaths` or
`IgnoreModFilePatterns` options](#configure).
### Can I use the package for non-mod projects?
You can use the package in non-mod projects too (e.g. unit tests or framework DLLs). Just disable
the mod-related package features (see [_configure_](#configure)):
Yep, this works in unit tests and framework projects too. Just disable the mod-related package
features (see [_configure_](#configure)):
```xml
<EnableGameDebugging>false</EnableGameDebugging>
@ -344,9 +394,9 @@ the mod-related package features (see [_configure_](#configure)):
<EnableModZip>false</EnableModZip>
```
If you need to copy the referenced DLLs into your build output, add this too:
To copy referenced DLLs into your build output for unit tests, add this too:
```xml
<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>
<BundleExtraAssemblies>All</BundleExtraAssemblies>
```
## For SMAPI developers
@ -363,18 +413,24 @@ when you compile it.
## Release notes
## Upcoming release
* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. **Older versions are no longer supported.**
* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. (Older versions are no longer supported.)
* Added `IgnoreModFilePaths` option to ignore literal paths.
* Removed the `GameExecutableName` and `GameFramework` build properties (since they now have the
same value on all platforms).
* Added `BundleExtraAssemblies` option to copy bundled DLLs into the mod zip/folder.
* Removed the `GameExecutableName` and `GameFramework` options (since they now have the same value
on all platforms).
* Removed the `CopyModReferencesToBuildOutput` option (superseded by `BundleExtraAssemblies`).
* Improved analyzer performance by enabling parallel execution.
**Migration guide for mod authors:**
1. See [_migrate to 64-bit_](https://stardewvalleywiki.com/Modding:Migrate_to_64-bit_on_Windows) and
[_migrate to Stardew Valley 1.5.5_](https://stardewvalleywiki.com/Modding:Migrate_to_Stardew_Valley_1.5.5).
2. Possible changes in your `.csproj` or `.targets` files:
* If you use `$(GameExecutableName)`, replace it with `Stardew Valley`.
* If you use `$(GameFramework)`, replace it with `MonoGame` and remove any XNA-specific logic.
* Replace `$(GameExecutableName)` with `Stardew Valley`.
* Replace `$(GameFramework)` with `MonoGame` and remove any XNA Framework-specific logic.
* Replace `<CopyModReferencesToBuildOutput>true</CopyModReferencesToBuildOutput>` with
`<BundleExtraAssemblies>Game</BundleExtraAssemblies>`.
* If you need to bundle extra DLLs besides your mod DLL, see the [`BundleExtraAssemblies`
documentation](#configure).
## 3.3.0
Released 30 March 2021.

View File

@ -18,6 +18,10 @@ namespace StardewModdingAPI.ModBuildConfig
/*********
** Accessors
*********/
/// <summary>The name (without extension or path) of the current mod's DLL.</summary>
[Required]
public string ModDllName { get; set; }
/// <summary>The name of the mod folder.</summary>
[Required]
public string ModFolderName { get; set; }
@ -52,6 +56,9 @@ namespace StardewModdingAPI.ModBuildConfig
/// <summary>A comma-separated list of relative file paths to ignore when deploying or zipping the mod.</summary>
public string IgnoreModFilePaths { get; set; }
/// <summary>A comma-separated list of <see cref="ExtraAssemblyTypes"/> values which indicate which extra DLLs to bundle.</summary>
public string BundleExtraAssemblies { get; set; }
/*********
** Public methods
@ -73,12 +80,15 @@ namespace StardewModdingAPI.ModBuildConfig
try
{
// parse extra DLLs to bundle
ExtraAssemblyTypes bundleAssemblyTypes = this.GetExtraAssembliesToBundleOption();
// parse ignore patterns
string[] ignoreFilePaths = this.GetCustomIgnoreFilePaths().ToArray();
Regex[] ignoreFilePatterns = this.GetCustomIgnorePatterns().ToArray();
// get mod info
ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip);
ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, this.ModDllName, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip);
// deploy mod files
if (this.EnableModDeploy)
@ -139,6 +149,28 @@ namespace StardewModdingAPI.ModBuildConfig
}
}
/// <summary>Parse the extra assembly types which should be bundled with the mod.</summary>
private ExtraAssemblyTypes GetExtraAssembliesToBundleOption()
{
ExtraAssemblyTypes flags = ExtraAssemblyTypes.None;
if (!string.IsNullOrWhiteSpace(this.BundleExtraAssemblies))
{
foreach (string raw in this.BundleExtraAssemblies.Split(','))
{
if (!Enum.TryParse(raw, out ExtraAssemblyTypes type))
{
this.Log.LogWarning($"[mod build package] Ignored invalid <{nameof(this.BundleExtraAssemblies)}> value '{raw}', expected one of '{string.Join("', '", Enum.GetNames(typeof(ExtraAssemblyTypes)))}'.");
continue;
}
flags |= type;
}
}
return flags;
}
/// <summary>Get the custom ignore patterns provided by the user.</summary>
private IEnumerable<Regex> GetCustomIgnorePatterns()
{

View File

@ -0,0 +1,21 @@
using System;
namespace StardewModdingAPI.ModBuildConfig.Framework
{
/// <summary>An extra assembly type for the <see cref="DeployModTask.BundleExtraAssemblies"/> field.</summary>
[Flags]
internal enum ExtraAssemblyTypes
{
/// <summary>Don't include extra assemblies.</summary>
None = 0,
/// <summary>Assembly files which are part of MonoGame, SMAPI, or Stardew Valley.</summary>
Game = 1,
/// <summary>Assembly files whose names start with <c>Microsoft.*</c> or <c>System.*</c>.</summary>
System = 2,
/// <summary>Assembly files which don't match any other category.</summary>
ThirdParty = 4
}
}

View File

@ -21,6 +21,45 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
/// <summary>The files that are part of the package.</summary>
private readonly IDictionary<string, FileInfo> Files;
/// <summary>The file extensions used by assembly files.</summary>
private readonly ISet<string> AssemblyFileExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
".dll",
".exe",
".pdb",
".xml"
};
/// <summary>The DLLs which match the <see cref="ExtraAssemblyTypes.Game"/> type.</summary>
private readonly ISet<string> GameDllNames = new HashSet<string>
{
// SMAPI
"0Harmony",
"Mono.Cecil",
"Mono.Cecil.Mdb",
"Mono.Cecil.Pdb",
"MonoMod.Common",
"Newtonsoft.Json",
"StardewModdingAPI",
"SMAPI.Toolkit",
"SMAPI.Toolkit.CoreInterfaces",
"TMXTile",
// game + framework
"BmFont",
"FAudio-CS",
"GalaxyCSharp",
"GalaxyCSharpGlue",
"Lidgren.Network",
"MonoGame.Framework",
"SkiaSharp",
"Stardew Valley",
"StardewValley.GameData",
"Steamworks.NET",
"TextCopy",
"xTile"
};
/*********
** Public methods
@ -30,9 +69,11 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
/// <param name="targetDir">The folder containing the build output.</param>
/// <param name="ignoreFilePaths">The custom relative file paths provided by the user to ignore.</param>
/// <param name="ignoreFilePatterns">Custom regex patterns matching files to ignore when deploying or zipping the mod.</param>
/// <param name="bundleAssemblyTypes">The extra assembly types which should be bundled with the mod.</param>
/// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
/// <param name="validateRequiredModFiles">Whether to validate that required mod files like the manifest are present.</param>
/// <exception cref="UserErrorException">The mod package isn't valid.</exception>
public ModFileManager(string projectDir, string targetDir, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, bool validateRequiredModFiles)
public ModFileManager(string projectDir, string targetDir, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, ExtraAssemblyTypes bundleAssemblyTypes, string modDllName, bool validateRequiredModFiles)
{
this.Files = new Dictionary<string, FileInfo>(StringComparer.OrdinalIgnoreCase);
@ -48,7 +89,7 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
string relativePath = entry.Item1;
FileInfo file = entry.Item2;
if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns))
if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns, bundleAssemblyTypes, modDllName))
this.Files[relativePath] = file;
}
@ -152,39 +193,70 @@ namespace StardewModdingAPI.ModBuildConfig.Framework
/// <param name="relativePath">The file's relative path in the package.</param>
/// <param name="ignoreFilePaths">The custom relative file paths provided by the user to ignore.</param>
/// <param name="ignoreFilePatterns">Custom regex patterns matching files to ignore when deploying or zipping the mod.</param>
private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns)
/// <param name="bundleAssemblyTypes">The extra assembly types which should be bundled with the mod.</param>
/// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, ExtraAssemblyTypes bundleAssemblyTypes, string modDllName)
{
bool IsAssemblyFile(string baseName)
// apply custom patterns
if (ignoreFilePaths.Any(p => p == relativePath) || ignoreFilePatterns.Any(p => p.IsMatch(relativePath)))
return true;
// ignore unneeded files
{
return
this.EqualsInvariant(file.Name, $"{baseName}.dll")
|| this.EqualsInvariant(file.Name, $"{baseName}.pdb")
|| this.EqualsInvariant(file.Name, $"{baseName}.xnb");
bool shouldIgnore =
// release zips
this.EqualsInvariant(file.Extension, ".zip")
// *.deps.json (only SMAPI's top-level one is used)
|| file.Name.EndsWith(".deps.json")
// code analysis files
|| file.Name.EndsWith(".CodeAnalysisLog.xml", StringComparison.OrdinalIgnoreCase)
|| file.Name.EndsWith(".lastcodeanalysissucceeded", StringComparison.OrdinalIgnoreCase)
// translation class builder (not used at runtime)
|| (
file.Name.StartsWith("Pathoschild.Stardew.ModTranslationClassBuilder")
&& this.AssemblyFileExtensions.Contains(file.Extension)
)
// OS metadata files
|| this.EqualsInvariant(file.Name, ".DS_Store")
|| this.EqualsInvariant(file.Name, "Thumbs.db");
if (shouldIgnore)
return true;
}
return
// release zips
this.EqualsInvariant(file.Extension, ".zip")
// check for bundled assembly types
// When bundleAssemblyTypes is set, *all* dependencies are copied into the build output but only those which match the given assembly types should be bundled.
if (bundleAssemblyTypes != ExtraAssemblyTypes.None)
{
var type = this.GetExtraAssemblyType(file, modDllName);
if (type != ExtraAssemblyTypes.None && !bundleAssemblyTypes.HasFlag(type))
return true;
}
// unneeded *.deps.json (only SMAPI's top-level one is used)
|| file.Name.EndsWith(".deps.json")
return false;
}
// dependencies bundled with SMAPI
|| IsAssemblyFile("0Harmony")
|| IsAssemblyFile("Newtonsoft.Json")
|| IsAssemblyFile("Pathoschild.Stardew.ModTranslationClassBuilder") // not used at runtime
/// <summary>Get the extra assembly type for a file, assuming that the user specified one or more extra types to bundle.</summary>
/// <param name="file">The file to check.</param>
/// <param name="modDllName">The name (without extension or path) for the current mod's DLL.</param>
private ExtraAssemblyTypes GetExtraAssemblyType(FileInfo file, string modDllName)
{
string baseName = Path.GetFileNameWithoutExtension(file.Name);
string extension = file.Extension;
// code analysis files
|| file.Name.EndsWith(".CodeAnalysisLog.xml", StringComparison.OrdinalIgnoreCase)
|| file.Name.EndsWith(".lastcodeanalysissucceeded", StringComparison.OrdinalIgnoreCase)
if (baseName == modDllName || !this.AssemblyFileExtensions.Contains(extension))
return ExtraAssemblyTypes.None;
// OS metadata files
|| this.EqualsInvariant(file.Name, ".DS_Store")
|| this.EqualsInvariant(file.Name, "Thumbs.db")
if (this.GameDllNames.Contains(baseName))
return ExtraAssemblyTypes.Game;
// custom ignore patterns
|| ignoreFilePaths.Any(p => p == relativePath)
|| ignoreFilePatterns.Any(p => p.IsMatch(relativePath));
if (baseName.StartsWith("System.", StringComparison.OrdinalIgnoreCase) || baseName.StartsWith("Microsoft.", StringComparison.OrdinalIgnoreCase))
return ExtraAssemblyTypes.System;
return ExtraAssemblyTypes.ThirdParty;
}
/// <summary>Get whether a string is equal to another case-insensitively.</summary>

View File

@ -29,7 +29,10 @@
<EnableModZip Condition="'$(EnableModZip)' == ''">true</EnableModZip>
<EnableHarmony Condition="'$(EnableHarmony)' == ''">false</EnableHarmony>
<EnableGameDebugging Condition="'$(EnableGameDebugging)' == ''">true</EnableGameDebugging>
<CopyModReferencesToBuildOutput Condition="'$(CopyModReferencesToBuildOutput)' == '' OR ('$(CopyModReferencesToBuildOutput)' != 'true' AND '$(CopyModReferencesToBuildOutput)' != 'false')">false</CopyModReferencesToBuildOutput>
<BundleExtraAssemblies Condition="'$(BundleExtraAssemblies)' == ''"></BundleExtraAssemblies>
<!-- coppy referenced DLLs into build output -->
<CopyLocalLockFileAssemblies Condition="$(BundleExtraAssemblies.Contains('ThirdParty')) OR $(BundleExtraAssemblies.Contains('Game')) OR $(BundleExtraAssemblies.Contains('System')) OR $(BundleExtraAssemblies.Contains('All'))">true</CopyLocalLockFileAssemblies>
</PropertyGroup>
<PropertyGroup Condition="'$(OS)' == 'Windows_NT' AND '$(EnableGameDebugging)' == 'true'">
@ -45,17 +48,17 @@
**********************************************-->
<ItemGroup>
<!-- game -->
<Reference Include="Stardew Valley" HintPath="$(GamePath)\Stardew Valley.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="StardewValley.GameData" HintPath="$(GamePath)\StardewValley.GameData.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="MonoGame.Framework" HintPath="$(GamePath)\MonoGame.Framework.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="xTile" HintPath="$(GamePath)\xTile.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="Stardew Valley" HintPath="$(GamePath)\Stardew Valley.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<Reference Include="StardewValley.GameData" HintPath="$(GamePath)\StardewValley.GameData.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<Reference Include="MonoGame.Framework" HintPath="$(GamePath)\MonoGame.Framework.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<Reference Include="xTile" HintPath="$(GamePath)\xTile.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<!-- SMAPI -->
<Reference Include="StardewModdingAPI" HintPath="$(GamePath)\StardewModdingAPI.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="SMAPI.Toolkit.CoreInterfaces" HintPath="$(GamePath)\smapi-internal\SMAPI.Toolkit.CoreInterfaces.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="StardewModdingAPI" HintPath="$(GamePath)\StardewModdingAPI.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<Reference Include="SMAPI.Toolkit.CoreInterfaces" HintPath="$(GamePath)\smapi-internal\SMAPI.Toolkit.CoreInterfaces.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
<!-- Harmony -->
<Reference Include="0Harmony" Condition="'$(EnableHarmony)' == 'true'" HintPath="$(GamePath)\smapi-internal\0Harmony.dll" Private="$(CopyModReferencesToBuildOutput)" />
<Reference Include="0Harmony" Condition="'$(EnableHarmony)' == 'true'" HintPath="$(GamePath)\smapi-internal\0Harmony.dll" Private="$(BundleExtraAssemblies.Contains('Game'))" />
</ItemGroup>
@ -81,6 +84,7 @@
**********************************************-->
<Target Name="AfterBuild">
<DeployModTask
ModDllName="$(TargetName)"
ModFolderName="$(ModFolderName)"
ModZipPath="$(ModZipPath)"
@ -92,6 +96,8 @@
GameModsDir="$(GameModsPath)"
IgnoreModFilePatterns="$(IgnoreModFilePatterns)"
IgnoreModFilePaths="$(IgnoreModFilePaths)"
BundleExtraAssemblies="$(BundleExtraAssemblies)"
/>
</Target>
</Project>