From 87c98bc056025ef339df34a96f96ccf4ea7c6665 Mon Sep 17 00:00:00 2001 From: Dominic Masters Date: Tue, 25 Jul 2023 19:16:47 -0700 Subject: [PATCH] Added building and debugging --- docs/compiling.md | 105 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/docs/compiling.md b/docs/compiling.md index 8741e897..a3aaefb4 100644 --- a/docs/compiling.md +++ b/docs/compiling.md @@ -234,4 +234,107 @@ Afterwards, you will need to run the following command: git clone https://git.wish.moe/YourWishes/Dawn.git ``` This will download the source code of the project to a new subdirectory called -"Dawn" and put all of the projects' source code within there. \ No newline at end of file +"Dawn" and put all of the projects' source code within there. + +### 2. Installing the Dependencies / Libraries. +I try to keep dependencies on third-party libraries to a minimum, however there +are a few libraries that are required to build the Dawn project. These libraries +are not included in the source code, and must be downloaded separately. This is +done using the git tool. + +After you have cloned the above repository, you will need to open a terminal and +navigate to the directory where you downloaded the source code to. Afterwards, +you will need to run the following command: +```bash +git submodule update --init --recursive +``` +This will fetch all of the third-party libraries that are required to build the +Dawn project. This may take a while depending on your internet connection. + +### 3. Loading the Project +This step is semi-optional. We are aiming to build the project using CMake, and +the easiest way to do this is to use the CMake Tools plugin for VSCode that we +installed earlier. This plugin will automatically detect the CMake files in the +project and will allow us to build the project using the VSCode interface. + +If you opted out of using VSCode, you will need to set up your CMake environment +to suit your IDE or needs. This is outside of the scope of this document, and +you will need to refer to your IDE's documentation for more information. + +To load the project, you will need to open VSCode and open the Dawn project +directory. Most operating systems will allow you to do this by dragging the +Dawn project directory onto the VSCode window. If this does not work, you can +open VSCode and click on the "File" menu, and click on "Open Folder". You will +then need to navigate to the Dawn project directory and click "Open". + +Afterwards you will likely be prompted autometically to configure the CMake +Tools plugin. If you are not, you can click on the "CMake" icon on the left-hand +side of the VSCode window, and click on "Configure". This will configure the +CMake Tools plugin to use the CMake files in the Dawn project directory. + +You may also be asked to select a compiler. If you are using Windows, you will +need to select the Visual Studio compiler. If you are using Linux, you will need +to select the GCC or Clang compiler. If you are using macOS, you will need to +select the Clang compiler. If you are using a different compiler, you will need +to select the appropriate compiler. + +If prompted to select a build type, select "Debug". + +## Compiling the Project +Now that we have the project loaded into our IDE, we can compile the project. +This is done using the CMake Tools plugin for VSCode. If you are not using +VSCode you will need to refer to your IDE's documentation for more information. + +Firstly, you will need to create a settings file to configure the project. In +VSCode you can create a new folder called ".vscode" in the Dawn project root +directory. Afterwards, you will need to create a new file called "settings.json" +in the ".vscode" directory. You will then need to paste the following into the +file: +```json +{ + "cmake.configureArgs": [ + "-DDAWN_BUILD_TOOLS=true", + "-DDAWN_BUILD_TARGET=target-liminal-win32-glfw", + "-DDAWN_DEBUG_BUILD=true" + } +} +``` +And save the file. You may want to alter the values to suit your needs. For +example, if you are compiling on Linux, you will need to change +`target-liminal-win32-glfw` to `target-liminal-linux-glfw`. If you are compiling +on macOS, you will need to change it to `target-liminal-osx-glfw`. The specific +configure arguments are outside of the scope of this document, and you will need +to refer to the specific target documentation for more information. + +After you have created the settings file, you will need to configure and build +the project. To perform the build you need to click "Build" button the bottom of +the VSCode window. This will compile the project and will output the resulting +binaries in to a "build" directory within the Dawn project directory. + +Upon clicking the "Build" button, you will see an output panel appear at the +bottom of the VSCode window. This will show the process of the build, and will +show any errors that may occur. This is used to debug and fix any issues that +may occur during the build process. + +If the build was successful, you will see a "Build finished" message in the +output panel, typically read as; +```bash +[build] Build finished with exit code 0 +``` +If you do not see this message, or if the exit code is not 0, you will need to +debug the issue. The output panel will show the error message which is helpful +so we can debug the issue. If you are unable to debug the issue, you can ask for +help in the Discord server. + +## Running the built project +After the build process succeeds you will be able to run the project. This is +done by clicking on the Run icon, which looks like a play button, on the bottom +of the VSCode window. This will run the project in production mode and will not +show any debug information. + +If the program hangs, crashes or does not run, you can click the Debug icon, +which looks like a ladybug, on the bottom of the VSCode window. This will run +the project in debug mode and will show debug information and HALT the program +if there is an error detected. If program HALTS in debug mode you can use this +information to debug the issue. If you are unable to debug the issue, you can +ask for help in the Discord server. \ No newline at end of file