-
Notifications
You must be signed in to change notification settings - Fork 2
Getting Started Build System and Directory Overview
This article will provide an overview of how to set everything up to start constructing your game as well as provide a breakdown of the libraries that exist within Firestorm and the directory structure. At the end of the article, I will go over the rationalle behind why everything is set up the way it is. Why at the end? Well, I hate it when I'm slapped with a wall of text when what I really want is the deets on how to get started. So without any further ado...
Firestorm uses Premake5 for generating the projects for your platform. Premake5 was chosen because I absolutely love Lua as a scripting language and since premake runs Lua scripts for its generation system, I jumped all over that.
Before I get into it, a mention should be made of the engine's dependencies. All of the third party source code used by Firestorm lives, apropriately, within the directory ThirdParty. I took as much care as I could to write apropriate generators for Firestorm, so they should all be generated alongside the rest of the Firestorm libraries that make use of them. However, they might not be absolutely perfect due to the individual quirks that exist within the build systems of each of these libraries, so if there is something wrong with these scripts when you run them, please leave a ticket in the Issues page.
To generate the projects for Firestorm, first you need to ensure that the Premake 5 binary is in your system's search path (the premake5 binary for Windows is provided with the repo clone). Then in the command line under the BuildScripts directory, run premake <generator>. All of the projects or build scripts (depending on which generator you used) for the Firestorm libraries, the Third-party libraries, as well as a project for the unit tests, will then be dumped into the folder BuildScripts/Premake.
If there's ever a need to add files to your project, all you need to do is run the generator again and premake will be smart enough to regenerate whatever projects are modified by the file addition. If you are working with Visual Studio or XCode, you will seldom need to do this since you can add new files to those projects through the IDE. However, if you are using make or some other script based build system, you'll probably need to run the generator again. Sometimes premake can be a bit finicky with its project modification detection, so sometimes you may need to nuke the entire BuildScripts/Premake directory and regenerate the projects. However, this shouldn't be necessary under most circumstances.
Once the projects or build scripts are generated, you are ready to get to work. Open the solution file that was dumped into BuildScripts/Premake (Firestorm<.your extension>) and you should be set. Set the UnitTests project as your startup project (XCode and other IDE users, do whatever you gotta do to make sure UnitTests is the project that runs when you hit compile and debug) and smash dat build button. The solution should build and then you should be faced with the UnitTests command line window. Check to ensure that all of the UnitTests complete without any errors and you should be good to go! If any of the UnitTests fail for your platform out of the box or if the build process for UnitTests fails for any reason, please leave a ticket and it will be investigated ASAP. Please include the platform you're compiling for and the version of your system's SDK that you are building against. Please also be sure to include details such as the output of the UnitTests that failed if the UnitTests compiled, or the output of your compiler if they did not compile.
As you no doubt noticed when you cloned the repository, the first party engine code is highly compartmentalized with classes organized into static libraries. One of the primary reasons behind this compartmentalization is for organizational purposes. The other reason, however, is to cut down on compile times. Whether or not this actually does that is debatable (I may have some things to set up to make the compile times better) however it's compartmentalized well enough that they aren't too bad. And the engine is relatively small, so it's not that big of a deal anyway.
Within the source directory are three other directories.
- Applications
- Libraries
- Tests
This is where the main logic of your application should live, as well as any support libraries that you want to write for the application. It is wise to compartmentalize the code in this way so that if you need to make any tools that use classes from your application, you can link against that application's support libraries and the tools and your game will be able to share a codebase.
This is where the first party Firestorm libraries live.
This is where the source code to your unit tests should live. The details on creating a unit test that can be picked up by the build generator scripts is explained in the article Creating a new Unit Test. It is HIGHLY encouraged that you leverage the unit test application when your developing your project, as unit tests can help catch a lot of errors and issues that might not otherwise crop up during your playtesting.