diff options
| -rw-r--r-- | docs/technical/mod-package.md | 100 | ||||
| -rw-r--r-- | src/SMAPI.ModBuildConfig/DeployModTask.cs | 34 | ||||
| -rw-r--r-- | src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs | 21 | ||||
| -rw-r--r-- | src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs | 124 | ||||
| -rw-r--r-- | src/SMAPI.ModBuildConfig/build/smapi.targets | 22 |
5 files changed, 244 insertions, 57 deletions
diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index 2e26275b..93e0009d 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -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. diff --git a/src/SMAPI.ModBuildConfig/DeployModTask.cs b/src/SMAPI.ModBuildConfig/DeployModTask.cs index 0c64aed3..140933bd 100644 --- a/src/SMAPI.ModBuildConfig/DeployModTask.cs +++ b/src/SMAPI.ModBuildConfig/DeployModTask.cs @@ -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() { diff --git a/src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs b/src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs new file mode 100644 index 00000000..571bf7c7 --- /dev/null +++ b/src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs @@ -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 + } +} diff --git a/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs b/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs index fbb91193..ad4ffdf9 100644 --- a/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs +++ b/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs @@ -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 + { + 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; + } + + // 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) { - return - this.EqualsInvariant(file.Name, $"{baseName}.dll") - || this.EqualsInvariant(file.Name, $"{baseName}.pdb") - || this.EqualsInvariant(file.Name, $"{baseName}.xnb"); + var type = this.GetExtraAssemblyType(file, modDllName); + if (type != ExtraAssemblyTypes.None && !bundleAssemblyTypes.HasFlag(type)) + return true; } - return - // release zips - this.EqualsInvariant(file.Extension, ".zip") + return false; + } - // unneeded *.deps.json (only SMAPI's top-level one is used) - || file.Name.EndsWith(".deps.json") + /// <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; - // dependencies bundled with SMAPI - || IsAssemblyFile("0Harmony") - || IsAssemblyFile("Newtonsoft.Json") - || IsAssemblyFile("Pathoschild.Stardew.ModTranslationClassBuilder") // not used at runtime + if (baseName == modDllName || !this.AssemblyFileExtensions.Contains(extension)) + return ExtraAssemblyTypes.None; - // code analysis files - || file.Name.EndsWith(".CodeAnalysisLog.xml", StringComparison.OrdinalIgnoreCase) - || file.Name.EndsWith(".lastcodeanalysissucceeded", StringComparison.OrdinalIgnoreCase) + if (this.GameDllNames.Contains(baseName)) + return ExtraAssemblyTypes.Game; - // OS metadata files - || this.EqualsInvariant(file.Name, ".DS_Store") - || this.EqualsInvariant(file.Name, "Thumbs.db") + if (baseName.StartsWith("System.", StringComparison.OrdinalIgnoreCase) || baseName.StartsWith("Microsoft.", StringComparison.OrdinalIgnoreCase)) + return ExtraAssemblyTypes.System; - // custom ignore patterns - || ignoreFilePaths.Any(p => p == relativePath) - || ignoreFilePatterns.Any(p => p.IsMatch(relativePath)); + return ExtraAssemblyTypes.ThirdParty; } /// <summary>Get whether a string is equal to another case-insensitively.</summary> diff --git a/src/SMAPI.ModBuildConfig/build/smapi.targets b/src/SMAPI.ModBuildConfig/build/smapi.targets index 8ad298d0..de00cbe8 100644 --- a/src/SMAPI.ModBuildConfig/build/smapi.targets +++ b/src/SMAPI.ModBuildConfig/build/smapi.targets @@ -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> |