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 ++++++++++++++++++++++++++++++++---------- 1 file changed, 78 insertions(+), 22 deletions(-) (limited to 'docs/technical') 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. -- cgit