Skip to content

chore: Make repo compatible to be built on Windows #2352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Oct 9, 2025
Merged

chore: Make repo compatible to be built on Windows #2352

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
ea26d6f
First .
bitsandfoxes Oct 7, 2025
35a8b36
Second, and security bump in samples
bitsandfoxes Oct 7, 2025
3d28a9e
Merge branch 'main' into fix/contrib
bitsandfoxes Oct 7, 2025
620d53a
Updated contributing and targets
bitsandfoxes Oct 7, 2025
8fa7aea
Install .NET before building
bitsandfoxes Oct 7, 2025
cbc168d
Merged main
bitsandfoxes Oct 8, 2025
84272c5
Restructured Contributing, updated samples, fixed unity version logging
bitsandfoxes Oct 8, 2025
15b9f01
Added logmessage if unity version not installed
bitsandfoxes Oct 8, 2025
95f5f6b
Upated installation order, fixed copying on windows
bitsandfoxes Oct 8, 2025
7a2966e
Escape path and replace unzip
bitsandfoxes Oct 8, 2025
8a1082d
More changes to make it platform agnostic
bitsandfoxes Oct 8, 2025
2415caf
Check for destination integrity
bitsandfoxes Oct 8, 2025
b0e22b3
Add cocoa to the download SDK step
bitsandfoxes Oct 8, 2025
9bb7e20
Cannot do that on Windows anyway
bitsandfoxes Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 105 additions & 111 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,178 +1,172 @@
* [Setup](#setup)
* [Development](#development)
* [Package](#package)
* [Tests](#tests)
* [Release](#release)
# Prerequisites

# Basics
Before you start, you need to install the following tools and dependencies.

## Quick Start
## Install Unity

### Install Unity
1. Install [Unity Hub](https://unity3d.com/get-unity/download)
2. Install Unity
* [Optional] Pick the Unity version specified [here](https://github.com/getsentry/sentry-unity/blob/main/samples/unity-of-bugs/ProjectSettings/ProjectVersion.txt#L1) so you don't have to update the sample project
* If you do install a different version or you want to build against a specific version, add it as `UNITY_VERSION` to the path (i.e. `export UNITY_VERSION=2022.3.44f1`)
3. Install iOS Build Module - Required by `Sentry.Unity.Editor.iOS`
4. Optional modules to install, depending on which platfor you're going to target
* Android
* Desktop Platforms
* WebGL

1. Install [Unity Hub](https://unity3d.com/get-unity/download).
2. [Optional] Download the Unity version specified [here](https://github.com/getsentry/sentry-unity/blob/main/samples/unity-of-bugs/ProjectSettings/ProjectVersion.txt#L1).
3. Required modules:
* Android Build Support
* iOS Build Support
* IL2CPP Build Support for your platform
* (optional) WebGL Build Support
4. If you installed a different version than #3: Add that version as `UNITY_VERSION` to the path (i.e. `export UNITY_VERSION=2022.3.44f1`)
## Install .NET

### Install PowerShell Global tool
You can find the pinned version in the `global.json` and download it from [here](https://dotnet.microsoft.com/en-us/download/dotnet/9.0).

After you've downloaded and installed the correct version of the .NET SDK install the PowerShell tool

```
dotnet tool install --global PowerShell
```

### Install GitHub CLI
and follow this up by restoring the workload

```
dotnet workload restore
```

## Install GitHub CLI

You can either download the newest release of [here](https://github.com/cli/cli/releases), or if you're on macOS use `brew install gh`. You'll need to log in through the commandline.

## Get the code
## (Optional) Setup for Building Android SDK

Clone the repo `git clone https://github.com/getsentry/sentry-unity.git` and `cd` into it
Only required if you plan to build the Android SDK yourself (instead of using prebuilt artifacts).

## Download the Native SDKs
* Install Git and ensure is accessible from the `PATH`
* Install [Android Studio](https://developer.android.com/studio)
* Open Android Studio and go to Customize -> All settings...
* Search for "SDK" in the Seachbar
* Select System Settings -> Android SDK
* Install the Android SDK
* Swap tab to SDK Tools
* Check "Show Package Details"
* Under Android SDK Build-Tools check "34"
* Apply
* Install JDK 17
* [Using sdkman](https://sdkman.io/) which manage versions for you. (i.e. `sdk install java 17.0.5-ms`)
* Or [download the OpenJDK](https://openjdk.java.net/install/) directly.
* Additional setup:
* Add `ANDROID_HOME` to your environment variables
* macOS zsh: `export ANDROID_HOME="$HOME/Library/Android/sdk"`
* Windows: `setx ANDROID_HOME "%localappdata%\Android\Sdk"` for a user level install.
* Make sure `java` is on the path. You can check by calling `java --version`
* Windows: Add the `bin` to the path i.e. `$env:PATH = "$env:PATH;$env:JAVA_HOME\bin`

You can save some time on the initial build by downloading the prebuild Native SDK artifacts from the last successful build of the `main` branch (requires [GH CLI](https://cli.github.com/) to be installed locally).
## (Optional) Setup for Building sentry-native

`dotnet msbuild /t:DownloadNativeSDKs src/Sentry.Unity`
Only required if you plan to build sentry-native yourself (instead of using prebuilt artifacts).

## Build the project
Sentry Native is a submodule from Sentry SDK for Unity and to building it following tools are required:

[Optional] The build process tries to infer the Unity version by looking up the unity-of-bugs `ProjectVersion.txt`. If you've got a different version installed you can overwrite this behaviour by setting the `UNITY_VERSION` on the path, i.e. adding `export UNITY_VERSION=2022.3.44f1` to your `.zshenv`.
* Install [CMake](https://cmake.org/download/).
* A supported C/C++ compiler.

To build the whole project (including native SDKs if you've skipped the previous step), run:
# Getting Started

`dotnet build`
## Clone the Repository

> Several projects are used as submodules - [sentry-dotnet](https://github.com/getsentry/sentry-dotnet), [Ben.Demystifier](https://github.com/benaadams/Ben.Demystifier)
> The submodule will be restored as a result of `dotnet build`.
Clone the repo `git clone https://github.com/getsentry/sentry-unity.git` and `cd` into it.

## Advanced Setup
## (Recommended) Download Prebuilt Native SDKs

This section details the setup required to be able to build the individual Native SDKs.
Instead of building the native SDKs for Android, Linux, and Windows yourself, you can save time by downloading prebuilt artifacts from the last successful build of the `main` branch. This requires [GH CLI](https://cli.github.com/) to be installed.

### Setup for building the Java SDK
Run `dotnet msbuild /t:DownloadNativeSDKs src/Sentry.Unity -v:d` to download the native SDKs.

* Install Git and ensure is accessible from the PATH
* Install Java 17
* [Using sdkman](https://sdkman.io/) which manage versions for you. (i.e. `sdk install java 17.0.5-ms`)
* Or [download the OpenJDK](https://openjdk.java.net/install/) directly.
* Add JAVA_HOME to your environment variables (if not using sdkman):
* Windows: `setx JAVA_HOME "C:\Program Files\Java\jdk-17.0.5"`
* Install [Android Studio](https://developer.android.com/studio)
* Open Android Studio and go to Customize -> All settings...
* Search for "SDK" in the Seachbar
* Select System Settings -> Android SDK
* Install the Android SDK
* Swap tab to SDK Tools
* Check "Show Package Details"
* Under Android SDK Build-Tools check "30.0.3"
* Apply
* Add ANDROID_HOME to your environment variables
* macOS zsh: `export ANDROID_HOME="$HOME/Library/Android/sdk"`
* Windows: `setx ANDROID_HOME "C:\Program Files (x86)\Android\android-sdk"` for a machine wide install, `setx ANDROID_HOME "%localappdata%\Android\Sdk"` for a user level install.
# Building the SDK

### Setup for building the Cocoa SDK
## Build the Sentry SDK for Unity

* Install Xcode
* Install Carthage (i.e. `brew install carthage`)
The build process attempts to look up the Unity version to use at `./samples/unity-of-bugs/ProjectSettings/ProjectVersion.txt`. If you've got a different version installed you can overwrite this behaviour by setting the `UNITY_VERSION` on the path, i.e. adding `export UNITY_VERSION=2022.3.44f1` to your `.zshenv`.

### Setup for building Sentry Native
To build the project either run `dotnet build -v:d` from the commandline or open `src/Sentry.Unity.sln` via the IDE of your choice and build the solution from there.

Sentry Native is a sub module from Sentry Unity and for building it, currently requires the following tools:
> Several projects are used as submodules - [sentry-dotnet](https://github.com/getsentry/sentry-dotnet), [Ben.Demystifier](https://github.com/benaadams/Ben.Demystifier)
> The submodule will be automatically restored as a result. If this fails, you can manually do so by calling `git submodule update --init --recursive`.

* Install [CMake](https://cmake.org/download/).
* A supported C/C++ compiler.
> The Sentry SDK for Unity has a dependency on Unity's `TestRunner.dll`. The target `LocateTestRunner` in `Directory.Build.targets` attempts to locate this library inside one of the templates that come with a default installation of Unity via the Hub. If you do not have the templates installed you can unblock yourself from this dependency by unloading the test projects.

Building the SDK will also download and cache Sentry CLI, and the Sentry SDK for Cocoa.

# Testing

## PlayMode and EditMode Tests

### Run tests
You can run tests either from the TestRunner window inside the Editor or from commandline via

```sh
dotnet msbuild /t:"UnityPlayModeTest;UnityEditModeTest" /p:Configuration=Release test/Sentry.Unity.Tests
dotnet msbuild /t:"UnityPlayModeTest;UnityEditModeTest" /p:Configuration=Release test/Sentry.Unity.Tests -v:d
```

### Running CI integration tests locally
## Integration and Smoke Tests

CI makes use of a handful of scripts for creating, exporting, building and smoke-testing builds for desktop and mobile platforms. We've added a script to make use of that functionality to emulate (and debug) our integration tests locally.

```pwsh
pwsh ./test/Scripts.Integration.Test/integration-test.ps1 -Platform "Android-Export" -UnityVersion "6000"
pwsh ./test/Scripts.Integration.Test/integration-test.ps1 -Platform "Android" -UnityVersion "6000"
```

Please refer to the script to make use of any optional parameters.

# Advanced and Troubleshooting
# Development Workflow

## Project Structure

There are two projects involved in `sentry-unity` development. `UPM` package (`src` and `package-dev` folders) and `Unity` project (`samples/unity-of-bugs` folder, `BugFarmScene.unity`) to test the package in.
The relevant structure is as follows:
* The `UPM` package
* `package-dev` is the dev `UPM` package
> The package details/info is in `package.json` [manifest file](https://docs.unity3d.com/Manual/upm-manifestPkg.html). Please, check [Unity package layout](https://docs.unity3d.com/Manual/cus-layout.html) docs for deeper understanding of the package structure.
* `package` contains some prepared meta files used for packaging
* The sample - `samples/unity-of-bugs` is a Unity project used to local testing. The SDK is installed as a local package pointing at `package-dev`
* The source
* `src` contains the source code
* `test` contains the tests and integration test relevants scripts

## Package
## Making Changes and Testing

Folders involved in this stage `src`, `package-dev`, `samples` where
Here's the typical workflow for `UPM` package development:

* `src` - package source code
* `package-dev` - dev `UPM` package
1. Open `src/Sentry.Unity.sln` in your editor of choice, i.e. Rider
> Make sure the projects are restored properly and you have zero errors, otherwise you probably misconfigured `src/Directory.Build.props` or restoring the submodules failed

> The package details/info is in `package.json` [manifest file](https://docs.unity3d.com/Manual/upm-manifestPkg.html). Please, check [Unity package layout](https://docs.unity3d.com/Manual/cus-layout.html) docs for deeper understanding of the package structure.
2. Build the solution: Artifacts (`.dll`s) will be placed inside `src/package-dev` folder

* `samples` - `Unity` sample projects, for dev flow we use `unity-of-bugs`
3. Check `src/package-dev` folder, it should be populated with the outlined content
* `Editor` - `Sentry.Unity.Editor.dll`
* `Runtime` - `Sentry.Unity.dll` and all its dependencies like `Sentry.dll`, `System.Text.Json` and so on
* `Tests`
* `Editor` - `Sentry.Unity.Editor.Tests.dll`
* `Runtime` - `Sentry.Unity.Tests.dll`

Let's outline the needed steps for `UPM` package development flow
4. Open `samples/unity-of-bugs` via the Hub

* open `samples/unity-of-bugs` in `Unity` or run in silent mode via CLI - `Unity -batchmode -projectPath <YOUR_PATH>/samples/unity-of-bugs -exit`
5. Configure `Sentry Unity (dev)` package
* Open `Tools` -> `Sentry` and insert your `DSN`

> The first run will take some time as `Unity` downloads and caches a bunch of pre-included packages and resources.
6. Run the project in the `Unity` Editor by clicking `Play`

> We need to run the project first, so it downloads needed dependencies (namely `UnityEngine.TestRunner.dll` and `UnityEditor.TestRunner.dll`) for `src/tests` projects from `[email protected]` library. After this package is restored, the actual dlls are placed inside `samples/unity-of-bugs/Library/ScriptAssemblies` folder.
7. Click `ThrowNull` or any other button and check errors in `Sentry` web UI

* open `src/Sentry.Unity.sln` in your editor of choice
> Make sure the projects are restored properly and you have zero errors, otherwise you probably misconfigured `src/Directory.Build.props` or didn't restore submodules properly
* build solution, artifacts (`.dll`s) will be placed inside `src/package-dev` folder
* check `src/package-dev` folder, it should be populated with the outlined content
* `Editor` - `Sentry.Unity.Editor.dll`
* `Runtime` - `Sentry.Unity.dll` and all its dependencies like `Sentry.dll`, `System.Text.Json` and so on
* `Tests`
* `Editor` - `Sentry.Unity.Editor.Tests.dll`
* `Runtime` - `Sentry.Unity.Tests.dll`
* open `samples/unity-of-bugs` project in `Unity`, then `Scenes/BugFarmScene` scene
* configure `Sentry Unity (dev)` package
* on the tab `Tools`, select `Sentry` and insert your `DSN` or [Sentry SDK](https://sentry.io/settings/sentry-sdks/projects/sentry-unity/) one `https://[email protected]/4504604988538880`
* configure other settings for your needs
* run the project in `Unity` via clicking `Play`
* click `ThrowNull` or any other button and check errors in `Sentry` web UI
# Advanced Topics

## Tests

The project has `PlayMode` and `EditMode` tests. They should be available (after you finished `Package` stage outlined above) when your open `samples/unity-of-bugs` project.

The tests project are inside `src/test` folder where

* `Directory.Build.props` specific variables and settings (inherits `src/Directory.Build.props`) for test projects
* `Sentry.Unity.Tests` project for `Runtime` Unity tests
* `Sentry.Unity.Editor.Tests` project for `Editor` Unity tests

Build artifacts from the test projects will be placed inside `package-dev/Tests/Editor` and `package-dev/Tests/Runtime` folders.

In order to run the tests

* open `samples/unity-of-bugs` Unity project
* open `TestRunner` via `Windows -> General -> Test Runner`
* run `PlayMode` or `EditMode` tests

### Package validation
## Package Validation

In CI, a workflow validates that the content of the package doesn't change accidentally.
If you intentially want to add or remove files in the final UPM package. You need to accept the diff:

```
pwsh ./test/Scripts.Tests/test-pack-contents.ps1 accept
```pwsh
pwsh ./test/Scripts.Tests/test-pack-contents.ps1 accept
```

## Release
> There is some automation in place that allows you to build, alias, package, and update the snapshot by running `pwsh ./scripts/repack.ps1`. Make sure the repository is in a clean state before doing so as to not add pending changes.

The release is done by pushing the artifact built in CI [to a new repo](https://github.com/getsentry/unity). The artifact is built by using the template files in the `package` directory. In order to make a release, the contents of `package-dev/Editor` and `package-dev/Runtime` folders should be copied into `package`.
## Release

The release is done by pushing the artifact built in CI [to a new repo](https://github.com/getsentry/unity). The artifact is built by using the template files in the `package` directory. The release process automatically moves specific contents of `package-dev` into `package`.
> **Don't** copy `package-dev` specific files like `package.json`, `Runtime/*.asmdef`, `Editor/*.asmdef` into `package`. Those files contain package specific information.
Loading
Loading