Skip to content

Commit 4b32271

Browse files
SimonDarksideJSimonDarksideJ
committed
Checkpoint
1 parent 7206ab2 commit 4b32271

16 files changed

+283
-544
lines changed

‎articles/getting_started/1_setting_up_your_development_environment_unix.md

Lines changed: 0 additions & 125 deletions
This file was deleted.

‎articles/getting_started/1_setting_up_your_os_for_development_macos.md

Lines changed: 77 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,101 @@
11
---
2-
title: Setting up your development environment for Visual Studio on Windows
3-
description: This section provides a step-by-step guide for setting up your development environment on Windows.
2+
title: Setting up your OS for development on MacOS
3+
description: This section provides a step-by-step guide for setting up your development environment on Mac.
44
---
55

6-
MonoGame can work with most .NET compatible tools, but we recommend [Visual Studio 2022](https://visualstudio.microsoft.com/vs/)
6+
To develop with MonoGame in C#, you will need to install the .NET SDK. As of MonoGame 3.8.2 the minimum supported version is .NET 8.
77

8-
> [!NOTE]
9-
> Alternatively, you can use [JetBrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/).
10-
>
11-
> Check out the guide for [Setting up VSCode / Rider here](./1_setting_up_your_development_environment_vscode.md).
8+
## Install .NET 8 SDK
129

13-
## Install Visual Studio 2022
10+
> [!IMPORTANT]
11+
> For the time being, MonoGame requires that you install the x64 version of the .NET SDK even if you are running on an Apple Silicon mac. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled.
1412
15-
Before using MonoGame with Visual Studio you need to ensure you have installed the latest [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) along with the required components.
13+
1. Navigate to [https://dotnet.microsoft.com/en-us/download](https://dotnet.microsoft.com/en-us/download)
1614

17-
When installing Visual Studio, the following workloads are required depending on your desired [target platform(s)](./platforms.md):
15+
![Download .NET For Mac](./images/1_setting_up_your_development_environment/vscode/mac/download-dotnet.png)
1816

19-
* Mandatory for all platforms:
20-
* **.Net desktop development**
21-
* Optional
22-
* **.Net Multi-platform App UI Development** if you wish to target Android, iOS, or iPadOS.
23-
* **Universal Windows Platform development** if you wish to build for Windows store or Xbox.
17+
2. Download the .NET SDK x64-(Intel) Installer
2418

25-
![Visual Studio optional components](images/1_installer_vs_components.png)
19+
> [!NOTE]
20+
> For the time being, MonoGame requires that you install the **.NET SDK x64-(Intel)** version of the .NET SDK even if you are running on an Apple Silicon (M1/M2) Mac. For Apple Silicon Macs, it also requires that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled.
2621
27-
> [!WARNING]
28-
> **Targeting Windows**
29-
>
30-
> If you are targeting the standard Windows DirectX backend, you will also need [the DirectX June 2010 runtime](https://www.microsoft.com/en-us/download/details.aspx?id=8109) for audio and gamepads to work properly.
31-
>
32-
> Work is underway however to update to support DirectX 12 on Windows and Xbox very soon.
22+
3. Once the installation **.pkg** file finishes downloading, run it and follow the prompts to install the .NET SDK
3323

34-
### Install MonoGame extension for Visual Studio 2022
24+
![Install .NET For Mac](./images/1_setting_up_your_development_environment/vscode/mac/install-dotnet.png)
3525

36-
To create new MonoGame projects from within Visual Studio 2022, you will need to install the **MonoGame Framework C# project templates** extension. The following steps demonstrate how to install the extension.
26+
4. Once the installation is complete, open a new terminal window and run the command `dotnet` to verify the installation was successful.
3727

38-
1. Launch Visual Studio 2022
39-
2. Select **Continue without code**. This will launch Visual Studio without any project or solution opened.
28+
![Verify Installation](./images/1_setting_up_your_development_environment/vscode/mac/verify-install.png)
4029

41-
![Visual Studio Launcher Continue Without Code](images/1_continue_without_code.png)
30+
## Setup Wine For Effect Compilation
4231

43-
3. Click "*Extensions -> Manage Extensions* in the Visual Studio 2022 menu bar. This will open the Manage Extensions dialog window.
32+
Effect (shader) compilation requires access to DirectX. This means it will not work natively on macOS and Linux systems, but it can be used through [Wine](https://www.winehq.org/).
4433

45-
![Extensions -> Manage Extensions Menu Selection](images/1_visual_studio_extension_menu.png)
34+
MonoGame provides a setup script that can be executed to setup the Wine environment for Effect (shader) compilation. However, this script has the following prerequisites that must first be setup:
4635

47-
4. Use the search box in the top-right corner of the Manage Extensions dialog window to search for **MonoGame**, then click the **MonoGame Framework C# project templates** extension as shown below and download it to install it.
36+
- **curl** must be installed
37+
- **p7zip** must be installed
38+
- **wine-stable** must be installed.
4839

49-
![Visual Studio Extension Manager](images/1_visual_studio_extension_manager.png)
40+
These can be installed using **brew**.
5041

51-
5. After it is downloaded, an alert will appear at the bottom of the Manage Extensions window that states "Your changes will be scheduled. The modifications will begin when all Microsoft Visual Studio windows are closed." Click the **Close** button, then close Visual Studio 2022.
42+
1. Open a terminal window.
43+
2. Enter the following command:
5244

53-
6. After closing Visual Studio 2022, a VSIX Installer window will open confirming that you want to install the **MonoGame Framework C# project templates** extension. Click the **Modify** button to accept the install.
45+
```sh
46+
brew install p7zip curl
47+
brew install --cask wine-stable
48+
```
5449

55-
![VSIX Installer Window](images/1_vsix_installer_window.png)
50+
> [!CAUTION]
51+
> It is recommended that you use `wine-stable` and not `wine-staging`.
5652

57-
You now have the MonoGame templates installed and are ready to create new projects.
53+
3. Now that the prerequisites are installed, download the [mgfxc_wine_setup.sh](https://monogame.net/downloads/net6_mgfxc_wine_setup.sh) script and execute it by entering the following command in the terminal:
5854

59-
> [!NOTE]
60-
>
61-
> ## [Alternative, use VSCode/Rider on Windows](./1_setting_up_your_development_environment_vscode.md)
62-
>
63-
> If you prefer to use JetBrains Rider or Visual Studio Code, then check out the [Setting up your development environment for VSCode](./1_setting_up_your_development_environment_vscode.md) article instead.
55+
```sh
56+
wget -qO- https://monogame.net/downloads/net6_mgfxc_wine_setup.sh | bash
57+
```
6458

65-
**Next up:** [Creating a new project](2_creating_a_new_project_vs.md)
59+
This will create new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory.
60+
61+
## Apple Silicon Known Issues
62+
63+
There is currently a two known issue when building content on an Apple Silicon (M1/M2) Mac:
64+
65+
1. **Building Textures**: An exception occurs stating that the **freeimage** lib could not be found.
66+
2. **Building SpriteFonts**: An exception occurs stating that the **freetype** lib could not be found.
67+
3. **Building Models**: An exception occurs starting that the **assimp** lib could not be found.
68+
69+
These issue occur due to needing compiled versions of these libs for the M1/M2 architecture. [There is currently work being done to resolve this](https://github.com/MonoGame/MonoGame/issues/8124), however in the meantime, you can use the following workaround that has been provided by community members.
70+
71+
1. Download and install the x64 version of [.NET 6](https://dotnet.microsoft.com/en-us/download/dotnet/6.0). This will place an x64 version of .NET 6 in a `/usr/local/share/dotnet/x64` directory.
72+
NOTE: It MUST be the x64 version in order for this to work. This will allow the x64 native libraries that the MonoGame Content Pipeline uses to function on the Apple Silicon device.
73+
Currently it also needs to be .NET 6 for the 3.8.1 Release of MonoGame.
74+
75+
2. Open your .csproj and add the following lines to the first `<PropertyGroup>` section.
76+
77+
```xml
78+
<DotnetCommand>/usr/local/share/dotnet/x64/dotnet</DotnetCommand>
79+
```
80+
81+
3. (Alternative) The directory above is not in the path. But we do not want the system to be confused on which .NET is should be using. So rather thatn putting the x64 verison in the path we should instead create a symlink named `dotnet64`.
82+
83+
```sh
84+
sudo ln -s /usr/local/share/dotnet/x64/dotnet /usr/local/share/dotnet/dotnet64
85+
```
86+
87+
We can then use this value as the value for `DotnetCommand`
88+
89+
```xml
90+
<DotnetCommand>dotnet64</DotnetCommand>
91+
```
92+
93+
> [!IMPORTANT]
94+
> A fast follow release is planned for Mac/Linux support to improve the content management side of MonoGame.
95+
96+
## Next Steps
97+
98+
Choose from one of the two IDE options on MacOS:
99+
100+
- [Setting up VSCode](./2_choosing_your_ide_vscode.md)
101+
- [Setting up Rider](./2_choosing_your_ide_rider.md)

0 commit comments

Comments
 (0)