Skip to content

Commit 196364a

Browse files
AristurtleDevAristurtleDev
authored
Add setup information for Arch Linux users (#190)
1 parent fb99ef1 commit 196364a

File tree

3 files changed

+207
-3
lines changed

3 files changed

+207
-3
lines changed

‎articles/getting_started/1_setting_up_your_os_for_development_arch.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Setting up your OS for development on Arch Linux
3+
description: This section provides a step-by-step guide for setting up your development environment on Arch Linux.
4+
---
5+
6+
> [!TIP]
7+
> Arch Linux is a rolling release distribution. This guide was tested in October 2025 with kernel `version 6.15.9-arch1-1`.
8+
9+
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.
10+
11+
## Install .NET 8 SDK
12+
13+
1. Open a new **Terminal** window.
14+
2. Enter the following command in the terminal to install the latest .NET 8 SDK:
15+
16+
```sh
17+
sudo pacman -Syu
18+
sudo pacman -S dotnet-sdk-8.0
19+
```
20+
21+
## Install additional workloads
22+
23+
If you intend to also work with platforms such as `Android` or `iOS`, you will need to install the additional .NET workload templates for those platforms which include additional features and simulators to support those platforms. Just run the following commands from the terminal for the platforms below you wish to install.
24+
25+
> [!IMPORTANT]
26+
> For mobile development with iOS and Android, you must also install the MAUI workload even though MonoGame does not use MAUI. The MAUI workload contains the debugging tools required to run and debug mobile .NET applications. Without it, you will not be able to properly debug your MonoGame mobile projects.
27+
28+
### [Android](#tab/android)
29+
30+
```cli
31+
dotnet workload install android
32+
```
33+
34+
### [iOS](#tab/iOS)
35+
36+
```cli
37+
dotnet workload install ios
38+
```
39+
40+
### [Maui](#tab/maui)
41+
42+
```cli
43+
dotnet workload install maui
44+
```
45+
46+
### [Android, iOS, and Maui](#tab/all)
47+
48+
```cli
49+
dotnet workload install android ios maui
50+
```
51+
52+
---
53+
54+
> [!NOTE]
55+
> You can use `dotnet workload search` to detect any other available workloads you wish to use.
56+
57+
## Setup Wine For Effect Compilation
58+
59+
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/).
60+
61+
MonoGame provides a setup script that can be executed to setup the Wine environment for Effect (shader) compilation.
62+
63+
1. Open a terminal window
64+
2. Install Wine and required dependencies
65+
66+
```sh
67+
sudo pacman -S wget curl 7zip wine
68+
```
69+
70+
> [!IMPORTANT]
71+
> Arch Linux recently transitioned the Wine package to a pure wow64 build to align with upstream Wine development. Because of this, when you install Wine using pacman, you will not get a separate `wine64` executable that the MonoGame tools will expect.
72+
>
73+
> Reference: <https://archlinux.org/news/transition-to-the-new-wow64-wine-and-wine-staging/>
74+
>
75+
> This means you will need to create a symlink for MonoGame to reference with the following command
76+
>
77+
> ```sh
78+
> sudo ln -s /usr/bin/wine /usr/local/bin/wine64
79+
> ```
80+
81+
3. Now that the prerequisites are installed, download the [mgfxc_wine_setup.sh](https://monogame.net/downloads/net8_mgfxc_wine_setup.sh) script and execute it by entering the following command in the terminal:
82+
83+
```sh
84+
wget -qO- https://monogame.net/downloads/net8_mgfxc_wine_setup.sh | bash
85+
```
86+
87+
> [!TIP]
88+
> When running the Wine setup script, you may see a popup asking to install **Wine Mono** for .NET support. You can cancel/close this popup. It's not needed because the MonoGame script installs the actual Windows .NET SDK instead.
89+
90+
> [!NOTE]
91+
> This script will create a new directory called `.winemonogame` in your home directory. If you ever wish to undo the setup this script performed, just simply delete that directory.
92+
93+
4. After the script completes, you must add the `MGFXC_WINE_PATH` environment variable to your **system environment** for it to be accessible to all applications:
94+
95+
```sh
96+
echo 'MGFXC_WINE_PATH="'$HOME'/.winemonogame"' | sudo tee -a /etc/environment
97+
```
98+
99+
> [!IMPORTANT]
100+
> Unlike other Linux distributions, such as Ubuntu, Arch Linux may not automatically load environment variables from your user profile at `~/.profile` for all applications. Adding `MGFXC_WINE_PATH` to `/etc/environment` ensures it is available system-wide, including for GUI applications (such as the MGCB Editor) and IDEs
101+
102+
5. For the environment variable to take effect, you can either log out and back in (recommended) or reboot your system.
103+
104+
6. After logging back in, verify the environment variable is set:
105+
106+
```sh
107+
echo $MGFXC_WINE_PATH
108+
```
109+
110+
> [!NOTE]
111+
> When running the above command you should see an output similar to the following
112+
>
113+
> ```sh
114+
> /home/yourusername/.winemonogame
115+
> ```
116+
117+
## Next Steps
118+
119+
Choose from one of the two IDE options on Arch Linux:
120+
121+
- [Setting up VSCode](./2_choosing_your_ide_vscode.md)
122+
- [Setting up Rider](./2_choosing_your_ide_rider.md)
123+
124+
## Troubleshooting
125+
126+
### Issue: "wine64 not found error"
127+
128+
If the setup script fails with `wine64 not found`, ensure you created the symlink from step 2 above
129+
130+
```sh
131+
sudo ln -s /usr/bin/wine /usr/local/bin/wine64
132+
```
133+
134+
### Issue: Shader compilation fails with "MGFXC effect compiler requires a valid wine installation"
135+
136+
This means the `MGFXC_WINE_PATH` environment variable is not set. Ensure you:
137+
138+
1. Added it to `/etc/environment` as shown above in step 4
139+
2. Logged out and logged back in
140+
3. Can see it with `echo $MGFXC_WINE_PATH`
141+
142+
### Issue: Wine creates a `.wine-mgfxc` directory instead of using `.winemonogame`
143+
144+
This is another symptom of the environment variable not being set. Follow the steps in the previous issue to resolve it.
145+
146+
### Issue: Wine version too old
147+
148+
The MonoGame setup script requires Wine 8.0 or later. Check your version:
149+
150+
```sh
151+
wine --version
152+
```
153+
154+
If it's too old, update your system:
155+
156+
```sh
157+
sudo pacman -Syu
158+
```

‎articles/getting_started/2_choosing_your_ide_vscode.md‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,43 @@ By the end, you will be fully equipped to start creating games with MonoGame usi
3737
2. Click the Download `.deb` button.
3838
3. Double click the `.deb` file and press the `Install` button.
3939

40+
### [Arch Linux](#tab/arch)
41+
42+
On Arch Linux, you have two options for installing Visual Studio Code:
43+
44+
#### Option 1: Code OSS (Open Source Version)
45+
46+
Code OSS is the fully open-source version available under the MIT License. It's available in the official Arch repositories and can be installed with a single command:
47+
48+
```sh
49+
sudo pacman -S code
50+
```
51+
52+
> [!IMPORTANT]
53+
> Code OSS **cannot** use the proprietary Microsoft **C# Dev Kit** extension. However, it can use the base **C#** extension (formerly OmniSharp, now LSP-based), which provides IntelliSense, syntax highlighting, debugging, and code navigation, sufficient for MonoGame development.
54+
55+
#### Option 2: Visual Studio Code (Official Microsoft Version) - Recommended
56+
57+
The official Microsoft version includes proprietary features like settings sync, Microsoft account integration, and **support for the C# Dev Kit extension**. It's available through the AUR (Arch User Repository).
58+
59+
1. First, ensure you have an AUR helper installed. If you don't have one, install `yay`:
60+
61+
```sh
62+
sudo pacman -S git base-devel
63+
git clone https://aur.archlinux.org/yay.git
64+
cd yay
65+
makepkg -si
66+
```
67+
68+
2. Install Visual Studio Code using yay:
69+
70+
```sh
71+
yay -S visual-studio-code-bin
72+
```
73+
74+
> [!TIP]
75+
> For the best MonoGame development experience with full C# Dev Kit support (enhanced project management, integrated testing, better solution support), install the official Visual Studio Code. Code OSS works but has limitations with Microsoft extensions.
76+
4077
---
4178

4279
## Setting up VS Code for development with MonoGame
@@ -68,6 +105,9 @@ To transform Visual Studio Code from a simple text editor into a powerful develo
68105
69106
![Install C# DevKit Extension](./images/1_setting_up_your_development_environment/vscode/install-devkit.png)
70107
108+
> [!NOTE]
109+
> **For Arch Linux Code OSS users:** The C# Dev Kit extension is not compatible with Code OSS. Instead, install only the base **C#** extension (by Microsoft), which provides all the core functionality needed for MonoGame development including IntelliSense, debugging, and code navigation.
110+
71111
## (Optional) Install the "MonoGame for VSCode" extension
72112
73113
A community member has built a VSCode extension for VS code to enable:
@@ -94,8 +134,10 @@ The .NET MAUI extension adds features for building mobile apps, including:
94134
![Install .NET MAUI DevKit Extension](../tutorials/building_2d_games/02_getting_started/images/maui-extension.png)
95135
96136
> [!NOTE]
97-
> This extension is recommended if you wish to do iOS or Android development. It is required for debugging support when working on mobile games.
137+
> This extension is recommended if you wish to do iOS or Android development. It is required for debugging support when working on mobile games.
98138
139+
> [!WARNING]
140+
> **For Arch Linux Code OSS users:** The .NET MAUI extension requires C# Dev Kit and therefore is not compatible with Code OSS. You will need to use the official Visual Studio Code for mobile development support.
99141
100142
## Creating a new MonoGame project
101143

‎articles/toc.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,12 @@ items:
1010
items:
1111
- name: Setting up MacOS
1212
href: /articles/getting_started/1_setting_up_your_os_for_development_macos.html
13-
- name: Setting up Ubuntu
14-
href: /articles/getting_started/1_setting_up_your_os_for_development_ubuntu.html
13+
- name: Setting up Linux
14+
items:
15+
- name: Setting up Arch Linux
16+
href: /articles/getting_started/1_setting_up_your_os_for_development_arch.html
17+
- name: Setting up Ubuntu
18+
href: /articles/getting_started/1_setting_up_your_os_for_development_ubuntu.html
1519
- name: Setting up Windows
1620
href: /articles/getting_started/1_setting_up_your_os_for_development_windows.html
1721
- name: Using Visual Studio

0 commit comments

Comments
 (0)