diff --git a/documentation/articles/conditional_compilation.md b/documentation/articles/conditional_compilation.md new file mode 100644 index 00000000..8a394b5e --- /dev/null +++ b/documentation/articles/conditional_compilation.md @@ -0,0 +1,130 @@ +--- +title: Conditional Compilation +description: Compilation directives for platform specific compilation of code. +--- + +# Conditional compilation + +MonoGame supports running C# projects on multiple platforms and supports several [directives](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives) to allow developers to selectively include or exclude code from compilation, based on whether certain [scripting symbols](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/symbols) or definitions are defined or not defined. + +You can read more broadly about how these directives work in C# in Microsoft’s user documentation on [C# preprocessor directives](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives) + +The hash `#` character in front of the **if** and **endif** indicates that these statements are “directives”, and they are handled during the build/compilation process, rather than at runtime. + +As an example, you can see in the code excerpt below, one set of code will be compiled on a DesktopGL platform, else the other code will be used. + +```csharp +#if DESKTOPGL + // The Client is running on the DesktopGL runtime +#else + // The Client is NOT running on DesktopGL +#endif +``` + +The critical factor is that the above pattern reduces what code is compiled and is included in the final build / release. + +> [!NOTE] +> The above technique is an alternative to using the `MonoGamePlatform` method, where all code included is compiled and included in your build, for example: +> +> ```csharp +> if(PlatformInfo.MonoGamePlatform == MonoGamePlatform.DesktopGL) +> { +> // The Client is running on the DesktopGL runtime +> } +> else +> { +> // The Client is NOT running on DesktopGL +> } +> ``` + +## Platform scripting symbols + +MonoGame provides the following scripting symbols through the [PlatformInfo](https://github.com/MonoGame/MonoGame/blob/develop/MonoGame.Framework/Utilities/PlatformInfo.cs) class, these are as follows: + +|Scripting #define|Description|Notes| +|-|-|-| +|ANDROID|Defines an application running on an Android system, this includes all Android based systems and varients.|| +|DESKTOPGL|A collective defintion covering OpenGL graphics on Windows, Mac and Linux.|| +|IOS|Covers all iOS based devices, including iPhone, iPad and future systems based on iOS.|| +|TVOS|Specific target for TVOS only.|| +|WINDOWS && DIRECTX|Combined definition for using DirectX on a Windows runtime|If you are using OpenGL, then use the DESKTOPGL define.| +|WINDOWS_UAP|Targetting Windows 10 & 11 UWP based applications|| +|SWITCH|Nintendo Switch based platform only.|| +|XB1|Xbox One, all editions. Including Xbox One, Xbox One X & S, Xbox Series X&S|| +|PLAYSTATION4|Playstation 4 custom silicon platform, for all editions of Playstation 4 including Pro|| +|PLAYSTATION5|Playstation 5 AMD based platform, for all editions|| +|STADIA|Google Statia runtime|Being deprecated with the fall of Stadia| + +## Other scripting symbols + +Microsoft Build which is used under the hood to build MonoGame projects also provides the following default symbols (as well as those included in your projects definition): + +|Scripting #define|Description|Notes| +|-|-|-| +|TRACE||| +|DEBUG|Is the application running in a DEBUG mode.|| +|RELEASE|Is the application running in a RELEASE mode.|| +|NET|Defines an application running on .NET.|| +|NETX|A define for the specific version of .NET being used, usually NET6 (.net 6) or NET8 (.net 8).|| +|NETCOREAPP|Defines an appication running as a .NET Core Application.|| + +To see the default symbols defined for your project: + +# [VSCode](#tab/vscode) + +In your `project.csproj` file, you can add custom symbols to your project as shown below. TRACE, DEBUG, RELEASE and framework options are included by default. + +The below example adds a `MYDEBUG` symbol in `Debug` build profile. + +```xml + + $(DefineConstants);MYDEBUG + +``` + +# [Visual Studio](#tab/vs) + +In Visual Studio, you can right-click your project and select properties to view your project definition, navigating down to the `Build` tab shows the symbol options for your project. + +![Visual Studio Build properties](images/vsprojectbuildproperties.png) + +--- + +## Testing precompiled code + +The example below shows logging the specific platform that was detected on startup. + +```csharp +using Microsoft.Xna.Framework; +using Microsoft.Xna.Framework.Graphics; +using Microsoft.Xna.Framework.Input; +using MonoGame.Framework.Utilities; +using System; + +namespace MonoGameDefinitionsTest; + +public class Game1 : Game +{ + private SpriteBatch _spriteBatch; + + public Game1() + { + _graphics = new GraphicsDeviceManager(this); + Content.RootDirectory = "Content"; +#if DESKTOPGL + Console.WriteLine("Hello from DesktopGL"); +#elif ANDROID + Console.WriteLine("Hello from ANDROID"); +#elif IOS + Console.WriteLine("Hello from iOS"); +#elif WINDOWS && DIRECTX + Console.WriteLine("Hello from WindowsDX"); +#else + // Fallback for any platform that was not selected above. + Console.WriteLine($"Hello from {PlatformInfo.MonoGamePlatform}"); +#endif + } +} +``` + +Depending on whichever platform you `Compile` for (build), only the specific lines detected above will be included in the build. \ No newline at end of file diff --git a/documentation/articles/images/vsprojectbuildproperties.png b/documentation/articles/images/vsprojectbuildproperties.png new file mode 100644 index 00000000..d6904db1 Binary files /dev/null and b/documentation/articles/images/vsprojectbuildproperties.png differ diff --git a/documentation/articles/toc.yml b/documentation/articles/toc.yml index 9fd04b94..fc93e7ae 100644 --- a/documentation/articles/toc.yml +++ b/documentation/articles/toc.yml @@ -2,6 +2,8 @@ href: index.md - name: What's New href: whats_new.md +- name: Supported platforms + href: platforms.md - name: Getting Started items: - name: Introduction @@ -24,16 +26,6 @@ href: getting_started/4_adding_content.md - name: 5. Adding Basic Code href: getting_started/5_adding_basic_code.md -- name: Tools - items: - - name: Introduction - href: tools/index.md - - name: MGCB - href: tools/mgcb.md - - name: MGCB Editor - href: tools/mgcb_editor.md - - name: MGFXC - href: tools/mgfxc.md - name: Content Pipeline items: - name: Introduction @@ -48,14 +40,26 @@ href: content_pipeline/adding_ttf_fonts.md - name: Localization href: content_pipeline/localization.md -- name: Supported platforms - href: platforms.md -- name: Migrating from 3.7 - href: migrate_37.md -- name: Migrating from 3.8.0 - href: migrate_38.md -- name: Migrating from XNA - href: migrate_xna.md +- name: Tools + items: + - name: Introduction + href: tools/index.md + - name: MGCB + href: tools/mgcb.md + - name: MGCB Editor + href: tools/mgcb_editor.md + - name: MGFXC + href: tools/mgfxc.md +- name: Migrating + items: + - name: Migrating from 3.7 + href: migrate_37.md + - name: Migrating from 3.8.0 + href: migrate_38.md + - name: Migrating from XNA + href: migrate_xna.md +- name: Conditional Compilation + href: conditional_compilation.md - name: Packaging href: packaging_games.md - name: Samples and Demos