 |
SAGE Installation Guide
A Simple Academic Game Engine
|
|
SAGE Installation Guide
A Simple Academic Game Engine
|
Before we begin, make sure that you are on a PC running Windows 11 and that your account has the authority to install new programs and to create and edit Windows environment variables. This may not be the case if you are on a work or school computer. If you are unfamiliar with environment variables, you can create and edit them by hitting the Window key on your keyboard and typing "Environment". Click on Edit the system environment variables. The Environment Variables dialog box should appear. Click on the New or Edit button and fill in the name and value fields.
The remainder of this page is divided into six sections. Section 1 explains how to download and install Visual Studio, Section 2 shows how to add MSBuild to your PATH environment variable, Section 3 explains how to download and install the DirectX12 Toolkit, Section 4 shows how to build SAGE, Section 5 explains how to install Visual Leak Detector, and Section 6 contains a summary to help you check your progress.
Download and install Visual Studio Community from https://visualstudio.microsoft.com/downloads/. It's free, as opposed to the other versions of Visual Studio such as Professional and Enterprise. Make sure that you choose the following three workloads (also shown in Fig. 1): Desktop development with C++, Game development with C++, and .NET desktop development. If your computer already has Microsoft Visual Studio installed but you do not have all of these workloads, you can install them from within Visual Studio without having to deinstall and reinstall the whole thing.
In order to use the included batch files Build.bat for fast compilation without running Visual Studio, you must add the location of MSBuild.exe, which was installed when you installed Visual Studio, to your Path environment variable. Its location will depend on which version of Visual Studio you are running. For example, the location for Visual Studio 2022 Community is
C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin
If you are unfamiliar with the process of modifying or creating an environment variable, begin by hitting the Window key on your keyboard and typing "Environment". Click on Edit the system environment variables. The Environment Variables dialog box should appear. Click on the New or Edit button on the User variables field and fill in the name and value in the pop-up dialog box that then appears.
Important Note: Visual Studio only reads the contents of environment variables on startup, so make your you quit all instances of Visual Studio and restart them after creating or changing any environment variable.
Before compiling SAGE you must install and compile the DirectX12 Toolkit. Clone or download the source code for the DirectX12 Toolkit from https://github.com/Microsoft/DirectXTK12/. Open DirectXTK_Desktop_2022_Win10.sln in Visual Studio and compile in both Release and Debug configurations with 64-bit platform (x64) selected. We use x64 because data that is to be uploaded to the GPU needs to be 16-byte aligned, which happens automatically with 64-bit code but not with 32-bit code. Technically it is possible to modify SAGE to work on a 32-bit platform, but that involves overriding the new operator in the renderer and life's just too short to get into that.
Next, create a Windows environment variable DIRECTXTK12_DIR and set it to the name of the folder in which you installed DirectXTK 12. On my computer this is C:\Users\ian\Documents\GitHub\DXTK12\. Then create a Windows environment variable DIRECTXTK12LIB_DIR and set it to the name of the library folder for DirectXTK 12. On my computer this is C:\Users\ian\Documents\GitHub\DXTK12\Bin\Desktop_2022_Win10\. Make sure that both paths ends in a backslash character.
Clone or download the source code for SAGE from https://github.com/Ian-Parberry/sage/. Navigate to the topmost folder in your copy of the sage repository. To check that you have done it right so far, you will find a batch files testenv.bat in the folder with Sage.sln. Double-click on it to run. If all goes well, you will see the message "0 errors found".
Open Sage.sln in Visual Studio and compile in both Release and Debug configurations with 64-bit platform (x64) selected. As part of the build process, this will create a Windows environment variable SAGE_DIR and set it to the current folder. This will be used in all SAGE games to tell Visual Studio where to find SAGE header and library files. Alternately, running Build.bat will compile in both Release and Debug configurations and set the SAGE_DIR environment variable. Note, however, that it simply reports success or failure for each configuration. There are no warning or error messages. If a build fails, run testenv.bat and try building in Visual Studio instead.
We strongly recommend that you install Visual Leak Detector from https://kinddragon.github.io/vld/. Click on Download Installer and run it. Let the installer set the environment variable for you, in addition create and set an environment variable VLD_DIR that SAGE will use to find the header and library folders for Visual Leak Detector. The default is C:\Program Files (x86)\Visual Leak Detector\ (unless you opted to install it in a different location).
Visual Leak Detector detects memory leaks but only works when your game is compiled in Debug mode. Alternately, if you don't want Visual Leak Detector to detect memory leaks, simply comment out the line #include <vld.h> from the file Main.cpp in any SAGE games.
Before moving on, make sure that you have done the following.
MSBuild.exe and add it to your PATH environment variable. This will let you run the batch files Build.bat as a fast alternative to running Visual Studio. See Section 2.DIRECTXTK12_DIR and DIRECTXTK12LIB_DIR. See Section 3.Build.bat in the topmost folder in your copy of the sage repository. If this reports failure, run checkenv.bat to make sure that you set the DIRECTXTK12 environment variables correctly. See Section 4.VLD_DIR. See Section 5. 
1.12.0