From 727d75ae728ba6cc8fc070524264c454aac8404f Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 12 Aug 2021 21:26:10 -0400 Subject: update to .NET 5 and official 64-bit --- docs/technical/mod-package.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/technical/mod-package.md') diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index 7eefc7a4..a3ce8761 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -366,6 +366,7 @@ when you compile it. ## Release notes ## Upcoming release +* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. **The older versions are no longer supported.** * Improved analyzer performance by enabling parallel execution. ## 3.3.0 -- cgit From 217cc7af21a501daabea16dc7331401a19706bf4 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 16 Sep 2021 17:34:31 -0400 Subject: add IgnoreModFilePaths option to package --- docs/technical/mod-package.md | 17 +++++++++++- src/SMAPI.ModBuildConfig/DeployModTask.cs | 32 ++++++++++++++++++++-- .../Framework/ModFileManager.cs | 9 ++++-- src/SMAPI.ModBuildConfig/build/smapi.targets | 1 + 4 files changed, 53 insertions(+), 6 deletions(-) (limited to 'docs/technical/mod-package.md') diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index a3ce8761..0fdd4c4a 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -222,6 +222,20 @@ Whether to configure the project so you can launch or debug the game through the Visual Studio (default `true`). There's usually no reason to change this, unless it's a unit test project. + + + +IgnoreModFilePaths + + +A comma-delimited list of literal file paths to ignore, relative to the mod's `bin` folder. Paths +are case-sensitive, but path delimiters are normalized automatically. For example, this ignores a +set of tilesheets: + +```xml +assets/paths.png, assets/springobjects.png +``` + @@ -366,7 +380,8 @@ when you compile it. ## Release notes ## Upcoming release -* Updated for Stardew Valley 1.5.5 and SMAPI 3.13.0. **The 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. * Improved analyzer performance by enabling parallel execution. ## 3.3.0 diff --git a/src/SMAPI.ModBuildConfig/DeployModTask.cs b/src/SMAPI.ModBuildConfig/DeployModTask.cs index 9ee6be12..0c64aed3 100644 --- a/src/SMAPI.ModBuildConfig/DeployModTask.cs +++ b/src/SMAPI.ModBuildConfig/DeployModTask.cs @@ -8,6 +8,7 @@ using System.Text.RegularExpressions; using Microsoft.Build.Framework; using Microsoft.Build.Utilities; using StardewModdingAPI.ModBuildConfig.Framework; +using StardewModdingAPI.Toolkit.Utilities; namespace StardewModdingAPI.ModBuildConfig { @@ -45,9 +46,12 @@ namespace StardewModdingAPI.ModBuildConfig [Required] public bool EnableModZip { get; set; } - /// Custom comma-separated regex patterns matching files to ignore when deploying or zipping the mod. + /// A comma-separated list of regex patterns matching files to ignore when deploying or zipping the mod. public string IgnoreModFilePatterns { get; set; } + /// A comma-separated list of relative file paths to ignore when deploying or zipping the mod. + public string IgnoreModFilePaths { get; set; } + /********* ** Public methods @@ -70,10 +74,11 @@ namespace StardewModdingAPI.ModBuildConfig try { // parse ignore patterns + string[] ignoreFilePaths = this.GetCustomIgnoreFilePaths().ToArray(); Regex[] ignoreFilePatterns = this.GetCustomIgnorePatterns().ToArray(); // get mod info - ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePatterns, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip); + ModFileManager package = new ModFileManager(this.ProjectDir, this.TargetDir, ignoreFilePaths, ignoreFilePatterns, validateRequiredModFiles: this.EnableModDeploy || this.EnableModZip); // deploy mod files if (this.EnableModDeploy) @@ -157,6 +162,29 @@ namespace StardewModdingAPI.ModBuildConfig } } + /// Get the custom relative file paths provided by the user to ignore. + private IEnumerable GetCustomIgnoreFilePaths() + { + if (string.IsNullOrWhiteSpace(this.IgnoreModFilePaths)) + yield break; + + foreach (string raw in this.IgnoreModFilePaths.Split(',')) + { + string path; + try + { + path = PathUtilities.NormalizePath(raw); + } + catch (Exception ex) + { + this.Log.LogWarning($"[mod build package] Ignored invalid <{nameof(this.IgnoreModFilePaths)}> path {raw}:\n{ex}"); + continue; + } + + yield return path; + } + } + /// Copy the mod files into the game's mod folder. /// The files to include. /// The folder path to create with the mod files. diff --git a/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs b/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs index 3d9b206b..fbb91193 100644 --- a/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs +++ b/src/SMAPI.ModBuildConfig/Framework/ModFileManager.cs @@ -28,10 +28,11 @@ namespace StardewModdingAPI.ModBuildConfig.Framework /// Construct an instance. /// The folder containing the project files. /// The folder containing the build output. + /// The custom relative file paths provided by the user to ignore. /// Custom regex patterns matching files to ignore when deploying or zipping the mod. /// Whether to validate that required mod files like the manifest are present. /// The mod package isn't valid. - public ModFileManager(string projectDir, string targetDir, Regex[] ignoreFilePatterns, bool validateRequiredModFiles) + public ModFileManager(string projectDir, string targetDir, string[] ignoreFilePaths, Regex[] ignoreFilePatterns, bool validateRequiredModFiles) { this.Files = new Dictionary(StringComparer.OrdinalIgnoreCase); @@ -47,7 +48,7 @@ namespace StardewModdingAPI.ModBuildConfig.Framework string relativePath = entry.Item1; FileInfo file = entry.Item2; - if (!this.ShouldIgnore(file, relativePath, ignoreFilePatterns)) + if (!this.ShouldIgnore(file, relativePath, ignoreFilePaths, ignoreFilePatterns)) this.Files[relativePath] = file; } @@ -149,8 +150,9 @@ namespace StardewModdingAPI.ModBuildConfig.Framework /// Get whether a build output file should be ignored. /// The file to check. /// The file's relative path in the package. + /// The custom relative file paths provided by the user to ignore. /// Custom regex patterns matching files to ignore when deploying or zipping the mod. - private bool ShouldIgnore(FileInfo file, string relativePath, Regex[] ignoreFilePatterns) + private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns) { bool IsAssemblyFile(string baseName) { @@ -181,6 +183,7 @@ namespace StardewModdingAPI.ModBuildConfig.Framework || this.EqualsInvariant(file.Name, "Thumbs.db") // custom ignore patterns + || ignoreFilePaths.Any(p => p == relativePath) || ignoreFilePatterns.Any(p => p.IsMatch(relativePath)); } diff --git a/src/SMAPI.ModBuildConfig/build/smapi.targets b/src/SMAPI.ModBuildConfig/build/smapi.targets index 74ac56e6..b254dd7c 100644 --- a/src/SMAPI.ModBuildConfig/build/smapi.targets +++ b/src/SMAPI.ModBuildConfig/build/smapi.targets @@ -94,6 +94,7 @@ TargetDir="$(TargetDir)" GameModsDir="$(GameModsPath)" IgnoreModFilePatterns="$(IgnoreModFilePatterns)" + IgnoreModFilePaths="$(IgnoreModFilePaths)" /> -- cgit From 4a26c96fbe600a4a229a1e63abb716a62dc7f450 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 16 Sep 2021 18:48:59 -0400 Subject: remove GameExecutableName build property from package --- build/find-game-folder.targets | 5 ----- docs/technical/mod-package.md | 24 +++++++++++----------- src/SMAPI.ModBuildConfig/build/smapi.targets | 4 ++-- .../SMAPI.Mods.ConsoleCommands.csproj | 2 +- .../SMAPI.Mods.ErrorHandler.csproj | 2 +- .../SMAPI.Mods.SaveBackup.csproj | 2 +- src/SMAPI.Tests/SMAPI.Tests.csproj | 5 +---- src/SMAPI/SMAPI.csproj | 2 +- 8 files changed, 19 insertions(+), 27 deletions(-) (limited to 'docs/technical/mod-package.md') diff --git a/build/find-game-folder.targets b/build/find-game-folder.targets index 3341226d..3164b071 100644 --- a/build/find-game-folder.targets +++ b/build/find-game-folder.targets @@ -41,9 +41,4 @@ - - - - Stardew Valley - diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index 0fdd4c4a..5eff3d2e 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -29,7 +29,7 @@ change how these work): * **Detect game path:** The package automatically finds your game folder by scanning the default install paths and Windows registry. It adds two MSBuild properties for use in your `.csproj` file if needed: - `$(GamePath)` and `$(GameExecutableName)`. + `$(GamePath)` and `$(GameModsPath)`. * **Add assembly references:** The package adds assembly references to SMAPI, Stardew Valley, xTile, and the game framework @@ -126,15 +126,6 @@ change it. The absolute path to the folder containing the game's installed mods (defaults to `$(GamePath)/Mods`), used when deploying the mod files. - - - -GameExecutableName - - -The filename for the game's executable (i.e. `StardewValley.exe` on Linux/macOS or -`Stardew Valley.exe` on Windows). This is auto-detected, and you should almost never change this. - @@ -382,13 +373,21 @@ when you compile it. ## Upcoming release * 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` build property (since it now has the same value on all platforms). * 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`. + ## 3.3.0 Released 30 March 2021. * Added a build warning when the mod isn't compiled for `Any CPU`. -* Added a `GameFramework` build property set to `MonoGame` or `Xna` based on the platform. This can be overridden to change which framework it references. +* Added a `GameFramework` build property set to `MonoGame` or `Xna` based on the platform. This can + be overridden to change which framework it references. * Added support for building mods against the 64-bit Linux version of the game on Windows. * The package now suppresses the misleading 'processor architecture mismatch' warnings. @@ -396,7 +395,8 @@ Released 30 March 2021. Released 23 September 2020. * Reworked and streamlined how the package is compiled. -* Added [SMAPI-ModTranslationClassBuilder](https://github.com/Pathoschild/SMAPI-ModTranslationClassBuilder) files to the ignore list. +* Added [SMAPI-ModTranslationClassBuilder](https://github.com/Pathoschild/SMAPI-ModTranslationClassBuilder) + files to the ignore list. ### 3.2.1 Released 11 September 2020. diff --git a/src/SMAPI.ModBuildConfig/build/smapi.targets b/src/SMAPI.ModBuildConfig/build/smapi.targets index b254dd7c..6fc62046 100644 --- a/src/SMAPI.ModBuildConfig/build/smapi.targets +++ b/src/SMAPI.ModBuildConfig/build/smapi.targets @@ -48,7 +48,7 @@ **********************************************--> - + @@ -71,7 +71,7 @@ - + diff --git a/src/SMAPI.Mods.ConsoleCommands/SMAPI.Mods.ConsoleCommands.csproj b/src/SMAPI.Mods.ConsoleCommands/SMAPI.Mods.ConsoleCommands.csproj index 65d54599..52439c41 100644 --- a/src/SMAPI.Mods.ConsoleCommands/SMAPI.Mods.ConsoleCommands.csproj +++ b/src/SMAPI.Mods.ConsoleCommands/SMAPI.Mods.ConsoleCommands.csproj @@ -13,8 +13,8 @@ - + diff --git a/src/SMAPI.Mods.ErrorHandler/SMAPI.Mods.ErrorHandler.csproj b/src/SMAPI.Mods.ErrorHandler/SMAPI.Mods.ErrorHandler.csproj index 2ad19df7..78cdb315 100644 --- a/src/SMAPI.Mods.ErrorHandler/SMAPI.Mods.ErrorHandler.csproj +++ b/src/SMAPI.Mods.ErrorHandler/SMAPI.Mods.ErrorHandler.csproj @@ -14,8 +14,8 @@ - + diff --git a/src/SMAPI.Mods.SaveBackup/SMAPI.Mods.SaveBackup.csproj b/src/SMAPI.Mods.SaveBackup/SMAPI.Mods.SaveBackup.csproj index f8908c7d..a8b0dfdb 100644 --- a/src/SMAPI.Mods.SaveBackup/SMAPI.Mods.SaveBackup.csproj +++ b/src/SMAPI.Mods.SaveBackup/SMAPI.Mods.SaveBackup.csproj @@ -13,7 +13,7 @@ - + diff --git a/src/SMAPI.Tests/SMAPI.Tests.csproj b/src/SMAPI.Tests/SMAPI.Tests.csproj index e19105ff..8329b2e1 100644 --- a/src/SMAPI.Tests/SMAPI.Tests.csproj +++ b/src/SMAPI.Tests/SMAPI.Tests.csproj @@ -23,10 +23,7 @@ - - $(GamePath)\$(GameExecutableName).dll - True - + diff --git a/src/SMAPI/SMAPI.csproj b/src/SMAPI/SMAPI.csproj index 16ddb92a..4f9aa9b1 100644 --- a/src/SMAPI/SMAPI.csproj +++ b/src/SMAPI/SMAPI.csproj @@ -29,7 +29,7 @@ - + -- cgit From bf10aeef0afae20e1d79f0772ba41a38fcb572ae Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 16 Sep 2021 18:59:25 -0400 Subject: remove GameFramework build property from package --- docs/technical/mod-package.md | 20 +++++++------------- src/SMAPI.ModBuildConfig/build/smapi.targets | 3 --- src/SMAPI/Constants.cs | 3 +-- src/SMAPI/Framework/ModLoading/AssemblyLoader.cs | 5 ++--- src/SMAPI/Framework/SCore.cs | 2 +- 5 files changed, 11 insertions(+), 22 deletions(-) (limited to 'docs/technical/mod-package.md') diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index 5eff3d2e..2e26275b 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -32,10 +32,10 @@ change how these work): `$(GamePath)` and `$(GameModsPath)`. * **Add assembly references:** - The package adds assembly references to SMAPI, Stardew Valley, xTile, and the game framework - (MonoGame on Linux/macOS, XNA Framework on Windows). It automatically adjusts depending on which OS - you're compiling it on. If you use [Harmony](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Harmony), - it can optionally add a reference to that too. + The package adds assembly references to MonoGame, SMAPI, Stardew Valley, and xTile. It + automatically adjusts depending on which OS you're compiling it on. If you use + [Harmony](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Harmony), it can optionally add + a reference to that too. * **Copy files into the `Mods` folder:** The package automatically copies your mod's DLL and PDB files, `manifest.json`, [`i18n` @@ -129,14 +129,6 @@ The absolute path to the folder containing the game's installed mods (defaults t -GameFramework - - -The game framework for which the mod is being compiled (one of `Xna` or `MonoGame`). This is -auto-detected based on the platform, and you should almost never change this. - - - @@ -373,7 +365,8 @@ when you compile it. ## Upcoming release * 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` build property (since it now has the same value on all platforms). +* Removed the `GameExecutableName` and `GameFramework` build properties (since they now have the + same value on all platforms). * Improved analyzer performance by enabling parallel execution. **Migration guide for mod authors:** @@ -381,6 +374,7 @@ when you compile it. [_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. ## 3.3.0 Released 30 March 2021. diff --git a/src/SMAPI.ModBuildConfig/build/smapi.targets b/src/SMAPI.ModBuildConfig/build/smapi.targets index 6fc62046..8ad298d0 100644 --- a/src/SMAPI.ModBuildConfig/build/smapi.targets +++ b/src/SMAPI.ModBuildConfig/build/smapi.targets @@ -30,9 +30,6 @@ false true false - - Xna - MonoGame diff --git a/src/SMAPI/Constants.cs b/src/SMAPI/Constants.cs index 2c16052b..3ae8661a 100644 --- a/src/SMAPI/Constants.cs +++ b/src/SMAPI/Constants.cs @@ -241,8 +241,7 @@ namespace StardewModdingAPI /// Get metadata for mapping assemblies to the current platform. /// The target game platform. - /// The game framework running the game. - internal static PlatformAssemblyMap GetAssemblyMap(Platform targetPlatform, GameFramework framework) + internal static PlatformAssemblyMap GetAssemblyMap(Platform targetPlatform) { var removeAssemblyReferences = new List(); var targetAssemblies = new List(); diff --git a/src/SMAPI/Framework/ModLoading/AssemblyLoader.cs b/src/SMAPI/Framework/ModLoading/AssemblyLoader.cs index 57a76a35..cb5fa2ae 100644 --- a/src/SMAPI/Framework/ModLoading/AssemblyLoader.cs +++ b/src/SMAPI/Framework/ModLoading/AssemblyLoader.cs @@ -53,16 +53,15 @@ namespace StardewModdingAPI.Framework.ModLoading *********/ /// Construct an instance. /// The current game platform. - /// The game framework running the game. /// Encapsulates monitoring and logging. /// Whether to detect paranoid mode issues. /// Whether to rewrite mods for compatibility. - public AssemblyLoader(Platform targetPlatform, GameFramework framework, IMonitor monitor, bool paranoidMode, bool rewriteMods) + public AssemblyLoader(Platform targetPlatform, IMonitor monitor, bool paranoidMode, bool rewriteMods) { this.Monitor = monitor; this.ParanoidMode = paranoidMode; this.RewriteMods = rewriteMods; - this.AssemblyMap = this.TrackForDisposal(Constants.GetAssemblyMap(targetPlatform, framework)); + this.AssemblyMap = this.TrackForDisposal(Constants.GetAssemblyMap(targetPlatform)); // init resolver this.AssemblyDefinitionResolver = this.TrackForDisposal(new AssemblyDefinitionResolver()); diff --git a/src/SMAPI/Framework/SCore.cs b/src/SMAPI/Framework/SCore.cs index a0467daa..55a7f083 100644 --- a/src/SMAPI/Framework/SCore.cs +++ b/src/SMAPI/Framework/SCore.cs @@ -1473,7 +1473,7 @@ namespace StardewModdingAPI.Framework // load mods IList skippedMods = new List(); - using (AssemblyLoader modAssemblyLoader = new AssemblyLoader(Constants.Platform, Constants.GameFramework, this.Monitor, this.Settings.ParanoidWarnings, this.Settings.RewriteMods)) + using (AssemblyLoader modAssemblyLoader = new AssemblyLoader(Constants.Platform, this.Monitor, this.Settings.ParanoidWarnings, this.Settings.RewriteMods)) { // init HashSet suppressUpdateChecks = new HashSet(this.Settings.SuppressUpdateChecks, StringComparer.OrdinalIgnoreCase); -- cgit From f5807e22be157d908e3b8c65f19acaa16c3588e7 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 16 Sep 2021 22:47:05 -0400 Subject: add BundleExtraAssemblies package option for new .NET 5 reference model --- docs/technical/mod-package.md | 100 +++++++++++++---- src/SMAPI.ModBuildConfig/DeployModTask.cs | 34 +++++- .../Framework/ExtraAssemblyType.cs | 21 ++++ .../Framework/ModFileManager.cs | 124 ++++++++++++++++----- src/SMAPI.ModBuildConfig/build/smapi.targets | 22 ++-- 5 files changed, 244 insertions(+), 57 deletions(-) create mode 100644 src/SMAPI.ModBuildConfig/Framework/ExtraAssemblyType.cs (limited to 'docs/technical/mod-package.md') 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 effect -CopyModReferencesToBuildOutput +BundleExtraAssemblies -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: + + + + + + + + + + + + + + + + + + + + + + +
optionresult
ThirdParty + +Assembly files which don't match any other category. + +
System + +Assembly files whose names start with `Microsoft.*` or `System.*`. + +
Game + +Assembly files which are part of MonoGame, SMAPI, or Stardew Valley. + +
All + +Equivalent to `System, Game, ThirdParty`. + +
+ +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. @@ -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 false @@ -344,9 +394,9 @@ the mod-related package features (see [_configure_](#configure)): false ``` -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 -true +All ``` ## 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 `true` with + `Game`. + * 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 *********/ + /// The name (without extension or path) of the current mod's DLL. + [Required] + public string ModDllName { get; set; } + /// The name of the mod folder. [Required] public string ModFolderName { get; set; } @@ -52,6 +56,9 @@ namespace StardewModdingAPI.ModBuildConfig /// A comma-separated list of relative file paths to ignore when deploying or zipping the mod. public string IgnoreModFilePaths { get; set; } + /// A comma-separated list of values which indicate which extra DLLs to bundle. + 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 } } + /// Parse the extra assembly types which should be bundled with the mod. + 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; + } + /// Get the custom ignore patterns provided by the user. private IEnumerable 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 +{ + /// An extra assembly type for the field. + [Flags] + internal enum ExtraAssemblyTypes + { + /// Don't include extra assemblies. + None = 0, + + /// Assembly files which are part of MonoGame, SMAPI, or Stardew Valley. + Game = 1, + + /// Assembly files whose names start with Microsoft.* or System.*. + System = 2, + + /// Assembly files which don't match any other category. + 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 /// The files that are part of the package. private readonly IDictionary Files; + /// The file extensions used by assembly files. + private readonly ISet AssemblyFileExtensions = new HashSet(StringComparer.OrdinalIgnoreCase) + { + ".dll", + ".exe", + ".pdb", + ".xml" + }; + + /// The DLLs which match the type. + private readonly ISet GameDllNames = new HashSet + { + // 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 /// The folder containing the build output. /// The custom relative file paths provided by the user to ignore. /// Custom regex patterns matching files to ignore when deploying or zipping the mod. + /// The extra assembly types which should be bundled with the mod. + /// The name (without extension or path) for the current mod's DLL. /// Whether to validate that required mod files like the manifest are present. /// The mod package isn't valid. - 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(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 /// The file's relative path in the package. /// The custom relative file paths provided by the user to ignore. /// Custom regex patterns matching files to ignore when deploying or zipping the mod. - private bool ShouldIgnore(FileInfo file, string relativePath, string[] ignoreFilePaths, Regex[] ignoreFilePatterns) + /// The extra assembly types which should be bundled with the mod. + /// The name (without extension or path) for the current mod's DLL. + 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") + /// Get the extra assembly type for a file, assuming that the user specified one or more extra types to bundle. + /// The file to check. + /// The name (without extension or path) for the current mod's DLL. + 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; } /// Get whether a string is equal to another case-insensitively. 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 @@ true false true - false + + + + true @@ -45,17 +48,17 @@ **********************************************--> - - - - + + + + - - + + - + @@ -81,6 +84,7 @@ **********************************************--> -- cgit