diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/release-notes.md | 20 | ||||
| -rw-r--r-- | docs/technical/mod-package.md | 4 | ||||
| -rw-r--r-- | docs/technical/smapi.md | 156 |
3 files changed, 111 insertions, 69 deletions
diff --git a/docs/release-notes.md b/docs/release-notes.md index d50a923d..499fa322 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,11 +1,27 @@ ← [README](README.md) # Release notes +## 3.13.2 +Released 05 December 2021 for Stardew Valley 1.5.5 or later. + +* For players: + * You no longer need .NET 5 to install or use SMAPI. + * The installer now detects when the game folder contains an incompatible legacy game version. + * Updated for the latest Stardew Valley 1.5.5 hotfix. + * Updated compatibility list. + +* For the web UI: + * Fixed the JSON validator marking `.fnt` files invalid in Content Patcher files. + +* For SMAPI maintainers: + * Added [release package scripts](technical/smapi.md) to streamline preparing SMAPI releases. + ## 3.13.1 Released 30 November 2021 for Stardew Valley 1.5.5 or later. -* Improved .NET 5 validation in Windows installer to better explain how to get the right version. -* Fixed installer failing on Windows when run from the game folder. +* For players: + * Improved .NET 5 validation in Windows installer to better explain how to get the right version. + * Fixed installer failing on Windows when run from the game folder. ## 3.13.0 Released 30 November 2021 for Stardew Valley 1.5.5 or later. diff --git a/docs/technical/mod-package.md b/docs/technical/mod-package.md index 93e0009d..41f808a5 100644 --- a/docs/technical/mod-package.md +++ b/docs/technical/mod-package.md @@ -412,7 +412,9 @@ The NuGet package is generated automatically in `StardewModdingAPI.ModBuildConfi when you compile it. ## Release notes -## Upcoming release +## 4.0.0 +Released 30 November 2021. + * 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. * Added `BundleExtraAssemblies` option to copy bundled DLLs into the mod zip/folder. diff --git a/docs/technical/smapi.md b/docs/technical/smapi.md index 29fa43a8..d9aad875 100644 --- a/docs/technical/smapi.md +++ b/docs/technical/smapi.md @@ -11,11 +11,12 @@ This document is about SMAPI itself; see also [mod build package](mod-package.md * [Configuration file](#configuration-file) * [Command-line arguments](#command-line-arguments) * [Compile flags](#compile-flags) -* [For SMAPI developers](#for-smapi-developers) - * [Compiling from source](#compiling-from-source) - * [Debugging a local build](#debugging-a-local-build) - * [Preparing a release](#preparing-a-release) - * [Using a custom Harmony build](#using-a-custom-harmony-build) +* [Compile from source code](#compile-from-source-code) + * [Main project](#main-project) + * [Custom Harmony build](#custom-harmony-build) +* [Prepare a release](#prepare-a-release) + * [On any platform](#on-any-platform) + * [On Windows](#on-windows) * [Release notes](#release-notes) ## Customisation @@ -58,39 +59,42 @@ flag | purpose ---- | ------- `SMAPI_FOR_WINDOWS` | Whether SMAPI is being compiled for Windows; if not set, the code assumes Linux/macOS. Set automatically in `common.targets`. -## For SMAPI developers -### Compiling from source +## Compile from source code +### Main project Using an official SMAPI release is recommended for most users, but you can compile from source -directly if needed. There are no special steps (just open the project and compile), but SMAPI often -uses the latest C# syntax. You may need the latest version of your IDE to compile it. +directly if needed. Just open the project in an IDE like [Visual +Studio](https://visualstudio.microsoft.com/vs/community/) or [Rider](https://www.jetbrains.com/rider/), +and build the `SMAPI` project. The project will automatically adjust the build settings for your +current OS and Stardew Valley install path. -SMAPI uses build configuration derived from the [crossplatform mod config](https://smapi.io/package/readme) -to detect your current OS automatically and load the correct references. Compile output will be -placed in a `bin` folder at the root of the Git repository. - -### Debugging a local build Rebuilding the solution in debug mode will copy the SMAPI files into your game folder. Starting -the `SMAPI` project with debugging from Visual Studio (on macOS or Windows) will launch SMAPI with -the debugger attached, so you can intercept errors and step through the code being executed. That -doesn't work in MonoDevelop on Linux, unfortunately. - -### Preparing a release -To prepare a crossplatform SMAPI release, you'll need to compile it on two platforms: Windows and -Linux. The instructions below assume you have Windows 11, but you can adapt them for -a different setup if needed. - -#### Initial setup -First-time setup on Windows: -1. [Install Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install). -2. Install the needed software in WSL: - 1. Run `sudo apt update` to update the package list. - 2. Install [the .NET 5 SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu) - (for Stardew Valley 1.5.5+) or [`mono-complete`](https://www.mono-project.com/download/stable/) - (for earlier versions). - _You can run `lsb_release -a` to get the Ubuntu version number._ - 3. [Install Steam](https://linuxconfig.org/how-to-install-steam-on-ubuntu-20-04-focal-fossa-linux). - 4. Launch `steam` and install the game like usual. - 5. Download and install your preferred IDE. For the [latest standalone Rider +the `SMAPI` project with debugging from Visual Studio or Rider should launch SMAPI with the +debugger attached, so you can intercept errors and step through the code being executed. + +### Custom Harmony build +SMAPI uses [a custom build of Harmony](https://github.com/Pathoschild/Harmony#readme), which is +included in the `build` folder. To use a different build, just replace `0Harmony.dll` in that +folder before compiling. + +## Prepare a release +### On any platform +**⚠ Ideally we'd have one set of instructions for all platforms. The instructions in this section +will produce a fully functional release for all supported platfrms, _except_ that the application +icon for SMAPI on Windows will disappear due to [.NET runtime bug +3828](https://github.com/dotnet/runtime/issues/3828). Until that's fixed, see the _[on +Windows](#on-windows)_ section below to create a build that retains the icon.** + +#### First-time setup +1. On Windows only: + 1. [Install Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install). + 2. Run `sudo apt update` in WSL to update the package list. + 3. The rest of the instructions below should be run in WSL. +2. Install the required software: + 1. Install the [.NET 5 SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu). + _For Ubuntu-based systems, you can run `lsb_release -a` to get the Ubuntu version number._ + 2. [Install Steam](https://linuxconfig.org/how-to-install-steam-on-ubuntu-20-04-focal-fossa-linux). + 3. Launch `steam` and install the game like usual. + 4. Download and install your preferred IDE. For the [latest standalone Rider version](https://www.jetbrains.com/help/rider/Installation_guide.html#prerequisites): ```sh wget "<download url here>" -O rider-install.tar.gz @@ -98,47 +102,67 @@ First-time setup on Windows: ln -s "/opt/JetBrains Rider-<version>/bin/rider.sh" ./rider.sh ``` - 3. Clone the SMAPI repo in WSL: - ```sh - git clone https://github.com/Pathoschild/SMAPI.git - ``` - -To compile SMAPI in WSL: -1. Run `./rider.sh` to open the Rider GUI. -2. Use the GUI to compile the solution. +3. Clone the SMAPI repo: + ```sh + git clone https://github.com/Pathoschild/SMAPI.git + ``` -To launch the game: -1. Open a WSL terminal. -2. Run these commands to start Steam: +### Launch the game +1. Run these commands to start Steam: ```sh export TERM=xterm steam ``` -3. Launch the game through the Steam UI. +2. Launch the game through the Steam UI. -#### Prepare the release -1. Update the version numbers in `build/common.targets`, `Constants`, and the `manifest.json` for - bundled mods. Make sure you use a [semantic version](https://semver.org). Recommended format: +### Prepare the release +1. Run `build/unix/set-smapi-version.sh` to set the SMAPI version. Make sure you use a [semantic + version](https://semver.org). Recommended format: build type | format | example :--------- | :----------------------- | :------ - dev build | `<version>-alpha.<date>` | `3.0.0-alpha.20171230` - prerelease | `<version>-beta.<date>` | `3.0.0-beta.20171230` - release | `<version>` | `3.0.0` -2. In Windows: - 1. Rebuild the solution with the _release_ solution configuration. - 2. Copy the `bin/SMAPI installer` and `bin/SMAPI installer for developers` folders to Linux. -4. In Linux: - 1. Rebuild the solution with the _release_ solution configuration. - 2. Add the `windows-install.*` files from Windows to the `bin/SMAPI installer` and - `bin/SMAPI installer for developers` folders compiled on Linux. - 3. Rename the folders to `SMAPI <version> installer` and `SMAPI <version> installer for developers`. - 4. Zip the two folders. + dev build | `<version>-alpha.<date>` | `4.0.0-alpha.20251230` + prerelease | `<version>-beta.<date>` | `4.0.0-beta.20251230` + release | `<version>` | `4.0.0` + +2. Run `build/unix/prepare-install-package.sh` to create the release package in the root `bin` + folder. + +### On Windows +#### First-time setup +1. Set up Windows Subsystem for Linux (WSL): + 1. [Install WSL](https://docs.microsoft.com/en-us/windows/wsl/install). + 2. Run `sudo apt update` in WSL to update the package list. + 3. The rest of the instructions below should be run in WSL. +2. Install the required software: + 1. Install the [.NET 5 SDK](https://dotnet.microsoft.com/download/dotnet/5.0). + 2. Install [Stardew Valley](https://www.stardewvalley.net/). +3. Clone the SMAPI repo: + ```sh + git clone https://github.com/Pathoschild/SMAPI.git + ``` -### Custom Harmony build -SMAPI uses [a custom build of Harmony](https://github.com/Pathoschild/Harmony#readme), which is -included in the `build` folder. To use a different build, just replace `0Harmony.dll` in that -folder before compiling. +### Prepare the release +1. Run `build/windows/set-smapi-version.ps1` in PowerShell to set the SMAPI version. Make sure you + use a [semantic version](https://semver.org). Recommended format: + + build type | format | example + :--------- | :----------------------- | :------ + dev build | `<version>-alpha.<date>` | `4.0.0-alpha.20251230` + prerelease | `<version>-beta.<date>` | `4.0.0-beta.20251230` + release | `<version>` | `4.0.0` + +2. Run `build/windows/prepare-install-package.ps1` in PowerShell to create the release package + folders in the root `bin` folder. + +3. Launch WSL and run this script: + ```bash + # edit to match the build created in steps 1-2 + # In WSL, `/mnt/c/example` accesses `C:\example` on the Windows filesystem. + version="4.0.0" + binFolder="/mnt/e/source/_Stardew/SMAPI/bin" + build/windows/finalize-install-package.sh "$version" "$binFolder" + ``` ## Release notes See [release notes](../release-notes.md). |