Skip to content

Commit 5ac9e44

Browse files
bitsandfoxesbitsandfoxes
authored
chore: Make repo compatible to be built on Windows (#2352)
1 parent 6dbb3c1 commit 5ac9e44

File tree

6 files changed

+140
-127
lines changed

6 files changed

+140
-127
lines changed

‎CONTRIBUTING.md‎

Lines changed: 105 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,172 @@
1-
* [Setup](#setup)
2-
* [Development](#development)
3-
* [Package](#package)
4-
* [Tests](#tests)
5-
* [Release](#release)
1+
# Prerequisites
62

7-
# Basics
3+
Before you start, you need to install the following tools and dependencies.
84

9-
## Quick Start
5+
## Install Unity
106

11-
### Install Unity
7+
1. Install [Unity Hub](https://unity3d.com/get-unity/download)
8+
2. Install Unity
9+
* [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
10+
* 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`)
11+
3. Install iOS Build Module - Required by `Sentry.Unity.Editor.iOS`
12+
4. Optional modules to install, depending on which platfor you're going to target
13+
* Android
14+
* Desktop Platforms
15+
* WebGL
1216

13-
1. Install [Unity Hub](https://unity3d.com/get-unity/download).
14-
2. [Optional] Download the Unity version specified [here](https://github.com/getsentry/sentry-unity/blob/main/samples/unity-of-bugs/ProjectSettings/ProjectVersion.txt#L1).
15-
3. Required modules:
16-
* Android Build Support
17-
* iOS Build Support
18-
* IL2CPP Build Support for your platform
19-
* (optional) WebGL Build Support
20-
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`)
17+
## Install .NET
2118

22-
### Install PowerShell Global tool
19+
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).
20+
21+
After you've downloaded and installed the correct version of the .NET SDK install the PowerShell tool
2322

2423
```
2524
dotnet tool install --global PowerShell
2625
```
2726

28-
### Install GitHub CLI
27+
and follow this up by restoring the workload
28+
29+
```
30+
dotnet workload restore
31+
```
32+
33+
## Install GitHub CLI
2934

3035
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.
3136

32-
## Get the code
37+
## (Optional) Setup for Building Android SDK
3338

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

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

38-
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).
61+
## (Optional) Setup for Building sentry-native
3962

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

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

44-
[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`.
67+
* Install [CMake](https://cmake.org/download/).
68+
* A supported C/C++ compiler.
4569

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

48-
`dotnet build`
72+
## Clone the Repository
4973

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

53-
## Advanced Setup
76+
## (Recommended) Download Prebuilt Native SDKs
5477

55-
This section details the setup required to be able to build the individual Native SDKs.
78+
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.
5679

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

59-
* Install Git and ensure is accessible from the PATH
60-
* Install Java 17
61-
* [Using sdkman](https://sdkman.io/) which manage versions for you. (i.e. `sdk install java 17.0.5-ms`)
62-
* Or [download the OpenJDK](https://openjdk.java.net/install/) directly.
63-
* Add JAVA_HOME to your environment variables (if not using sdkman):
64-
* Windows: `setx JAVA_HOME "C:\Program Files\Java\jdk-17.0.5"`
65-
* Install [Android Studio](https://developer.android.com/studio)
66-
* Open Android Studio and go to Customize -> All settings...
67-
* Search for "SDK" in the Seachbar
68-
* Select System Settings -> Android SDK
69-
* Install the Android SDK
70-
* Swap tab to SDK Tools
71-
* Check "Show Package Details"
72-
* Under Android SDK Build-Tools check "30.0.3"
73-
* Apply
74-
* Add ANDROID_HOME to your environment variables
75-
* macOS zsh: `export ANDROID_HOME="$HOME/Library/Android/sdk"`
76-
* 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.
82+
# Building the SDK
7783

78-
### Setup for building the Cocoa SDK
84+
## Build the Sentry SDK for Unity
7985

80-
* Install Xcode
81-
* Install Carthage (i.e. `brew install carthage`)
86+
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`.
8287

83-
### Setup for building Sentry Native
88+
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.
8489

85-
Sentry Native is a sub module from Sentry Unity and for building it, currently requires the following tools:
90+
> Several projects are used as submodules - [sentry-dotnet](https://github.com/getsentry/sentry-dotnet), [Ben.Demystifier](https://github.com/benaadams/Ben.Demystifier)
91+
> The submodule will be automatically restored as a result. If this fails, you can manually do so by calling `git submodule update --init --recursive`.
8692
87-
* Install [CMake](https://cmake.org/download/).
88-
* A supported C/C++ compiler.
93+
> 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.
94+
95+
Building the SDK will also download and cache Sentry CLI, and the Sentry SDK for Cocoa.
96+
97+
# Testing
98+
99+
## PlayMode and EditMode Tests
89100

90-
### Run tests
101+
You can run tests either from the TestRunner window inside the Editor or from commandline via
91102

92103
```sh
93-
dotnet msbuild /t:"UnityPlayModeTest;UnityEditModeTest" /p:Configuration=Release test/Sentry.Unity.Tests
104+
dotnet msbuild /t:"UnityPlayModeTest;UnityEditModeTest" /p:Configuration=Release test/Sentry.Unity.Tests -v:d
94105
```
95106

96-
### Running CI integration tests locally
107+
## Integration and Smoke Tests
97108

98109
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.
99110

100111
```pwsh
101-
pwsh ./test/Scripts.Integration.Test/integration-test.ps1 -Platform "Android-Export" -UnityVersion "6000"
112+
pwsh ./test/Scripts.Integration.Test/integration-test.ps1 -Platform "Android" -UnityVersion "6000"
102113
```
103114

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

106-
# Advanced and Troubleshooting
117+
# Development Workflow
107118

108119
## Project Structure
109120

110-
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.
121+
The relevant structure is as follows:
122+
* The `UPM` package
123+
* `package-dev` is the dev `UPM` package
124+
> 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.
125+
* `package` contains some prepared meta files used for packaging
126+
* 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`
127+
* The source
128+
* `src` contains the source code
129+
* `test` contains the tests and integration test relevants scripts
111130

112-
## Package
131+
## Making Changes and Testing
113132

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

116-
* `src` - package source code
117-
* `package-dev` - dev `UPM` package
135+
1. Open `src/Sentry.Unity.sln` in your editor of choice, i.e. Rider
136+
> 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
118137
119-
> 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.
138+
2. Build the solution: Artifacts (`.dll`s) will be placed inside `src/package-dev` folder
120139

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

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

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

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

129-
> 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.
154+
7. Click `ThrowNull` or any other button and check errors in `Sentry` web UI
130155

131-
* open `src/Sentry.Unity.sln` in your editor of choice
132-
> 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
133-
* build solution, artifacts (`.dll`s) will be placed inside `src/package-dev` folder
134-
* check `src/package-dev` folder, it should be populated with the outlined content
135-
* `Editor` - `Sentry.Unity.Editor.dll`
136-
* `Runtime` - `Sentry.Unity.dll` and all its dependencies like `Sentry.dll`, `System.Text.Json` and so on
137-
* `Tests`
138-
* `Editor` - `Sentry.Unity.Editor.Tests.dll`
139-
* `Runtime` - `Sentry.Unity.Tests.dll`
140-
* open `samples/unity-of-bugs` project in `Unity`, then `Scenes/BugFarmScene` scene
141-
* configure `Sentry Unity (dev)` package
142-
* 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`
143-
* configure other settings for your needs
144-
* run the project in `Unity` via clicking `Play`
145-
* click `ThrowNull` or any other button and check errors in `Sentry` web UI
156+
# Advanced Topics
146157

147-
## Tests
148-
149-
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.
150-
151-
The tests project are inside `src/test` folder where
152-
153-
* `Directory.Build.props` specific variables and settings (inherits `src/Directory.Build.props`) for test projects
154-
* `Sentry.Unity.Tests` project for `Runtime` Unity tests
155-
* `Sentry.Unity.Editor.Tests` project for `Editor` Unity tests
156-
157-
Build artifacts from the test projects will be placed inside `package-dev/Tests/Editor` and `package-dev/Tests/Runtime` folders.
158-
159-
In order to run the tests
160-
161-
* open `samples/unity-of-bugs` Unity project
162-
* open `TestRunner` via `Windows -> General -> Test Runner`
163-
* run `PlayMode` or `EditMode` tests
164-
165-
### Package validation
158+
## Package Validation
166159

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

170-
```
171-
pwsh ./test/Scripts.Tests/test-pack-contents.ps1 accept
163+
```pwsh
164+
pwsh ./test/Scripts.Tests/test-pack-contents.ps1 accept
172165
```
173166

174-
## Release
167+
> 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.
175168
176-
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`.
169+
## Release
177170

171+
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`.
178172
> **Don't** copy `package-dev` specific files like `package.json`, `Runtime/*.asmdef`, `Editor/*.asmdef` into `package`. Those files contain package specific information.

0 commit comments

Comments
 (0)