Build Setup

MicroEngine source is configured to support a handful of environments, allowing users freedom in their development tools of choice. (If you are an advanced C++/CMake programmer, you can set it up for any custom environment too.) Only x64 (64-bit) builds are supported; a 32-bit build may work but may exhibit undefined behaviour. For more information on CMake and C++, visit this page.

Global Requirements:

1. x64 (64-bit) CPU and OS
2. C++17 compiler & tools (linker and runtime)
3. CMake 3.13+
4. Collaborators/Contributors:
   1. Editor Config support in your editor / IDE
      • VS Code (Also available through "Extensions" within the editor)
      • Notepad++
      • Code::Blocks
   2. clang-format (standalone executable linked at the bottom of the page; rename as clang-format.exe and place in Tools)
      • Visual Studio 2019: Formatting > General > Enable ClangFormat
      • VS Code

Common

1. Download and install CMake 3.13+ for your OS (cmake-gui is the GUI wrapper on Linux)
2. Clone the repository: git clone https://github.com/<repo-url> to a location on your local storage
   1. Collaborators: git checkout dev (dev is your effective master)
3. (Optional) Manually initialise git submodules: git submodule update --init --recursive (CMake scripts will do this even if you don't)

Note: Downloading an archive of the repo - instead of cloning - will not work without manual submodule updation!

Quick Links:

1. Visual Studio Solution
2. Visual Studio CMake
3. Visual Studio Code / Code::Blocks (or any text editor) with MinGW
4. Linux
5. Adding Sources

Windows (x64)

There are several options, listed in order of increasing complexity (of pre-build configuration).

Visual Studio Solution

Requirements

1. Visual Studio 2017+
2. Windows SDK
3. (Optional) LLVM compiler toolchain and LLVM Visual Studio plugin

Instructions

1. Open CMake and configure it:
   1. Click "Browse Source" and select {repo_path}
   2. Put {repo_path}/out (or a subdirectory) as "Where to build the binaries:"
   3. Click Configure and select your generator:
      • If using VS 2019: "Visual Studio 16 2019"
      • If using VS 2017: "Visual Studio 15 2017"
      1. If using VS 2017, enter "x64" as the "platform" (Win32 is not supported!)
      2. (Optional): If using Clang/LLVM, set "LLVM" as the "platform toolset"
      3. Click Finish (first-time configuration will take some time, successive ones will be much faster)
   4. After configuring is complete, ensure UPDATE_SUBMODULES is checked and click "Generate"
   5. Click Open Project
2. In the IDE:
   1. (Optional) Choose your build configuration: Debug / RelWithDebInfo are relevant on Windows (the latter will build optimised - and hard-to-debug - binaries)
   2. Build ALL_BUILD: this will also auto-rerun CMake when it is out-of-date
   3. Select MicroEngine as the "Startup Project" in solution explorer
   4. Debug/Run the built executable (located in {repo_path}/Build)

Note: The generated solution file can be found in the path you chose as "Where to build the binaries" in CMake: it should be called {project_name}.sln. Do not manually edit/delete any files in there.

Visual Studio CMake

Requirements

1. Visual Studio 2019+
2. C++ CMake tools for Windows
3. Windows SDK
4. (Optional) LLVM compiler toolchain and Clang Compiler for Windows

Instructions

1. Open Visual Studio, select "Open Folder", and pick {repo_dir}
2. (Optional) Right-click CMakeLists.txt and select "CMake Settings for {project_name}":
   1. Set the toolset to clang_cl_x64 (if using LLVM/CLang)
   2. Add another build configuration for RelWithDebInfo
3. Click Project -> Generate Cache
4. Click Build -> Build All
5. To Debug: Click the arrow next to "Select Startup Item" (the green play button) and pick the name of the executable; click the button / press F5

Visual Studio Code / Code::Blocks / Notepad++ / vim / emacs / etc

Requirements

1. MinGW x64 (with mingw32-make 4+ and g++ 7+)
   1. Note: make sure to select x86_64 as the "Architecture", and to add /path/to/mingw/bin to your environment's PATH (for CMake to find the compiler)!
2. (VSCode):
   1. (Optional) Microsoft C/C++ extension

Note: mingw (32-bit, installs via mingw-get / MinGW Installation Manager etc) is not supported! You must use mingw64 to successfully compile and link MicroEngine.

Instructions

1. Open CMake and configure it:
   1. Click "Browse Source" and select {repo_path}
   2. Put {repo_path}/out/Debug (or a subdirectory) as "Where to build the binaries:"
   3. Click Configure and select the "MinGW MakeFiles" generator (or "CodeBlocks MinGW MakeFiles" if using CB)
   4. Click Finish (first-time configuration will take some time, successive ones will be much faster)
   5. After configuring is complete, ensure UPDATE_SUBMODULES is checked and click "Generate"
   6. (Optional) Create another CMake build directory {repo_path}/out/RelWithDebInfo and repeat, but with CMAKE_BUILD_TYPE set to RelWithDebInfo
2. Build and debug/run MicroEngine:
   • Via the terminal: navigate to the CMake build directory, then:
     1. Type mingw32-make and press enter (pass -jN to use N threads)
     2. Navigate to MircoEngine's build directory ({repo_path}/Build)
     3. To Run: type ./{exe-filename} and press Enter
     4. To Debug: type gdb ./{exe-filename} and press Enter, at the gdb console type run and press Enter
   • If using Code::Blocks:
     1. Open the generated project
     2. Build ALL_BUILD
     3. Select MicroEngine as the debugging target
     4. Set path/to/gdb.exe as the debugger
     5. Debug/Run the target
   • If using VSCode with the C/C++ plugin:
     1. Click Terminal and "Configure Default Build Task" and "Configure Task" to automate building and debugging without having to enter the terminal

Linux (x64)

Requirements

1. All SFML dependencies/libraries installed to standard paths
2. g++ 7+, make
3. (Optional) clang, llvm, ninja, codeblocks

Instructions

1. Open CMake and configure it:
   1. Click "Browse Source" and select {repo_path}
   2. Put {repo_path}/out (or a subdirectory) as "Where to build the binaries:"
   3. Click Configure and select the generator:
      1. make: Select "Unix Makefiles"
      2. ninja: Select "Ninja"
      3. codeblocks: Select "CodeBlocks Unix Makefiles" / "CodeBlocks Ninja"
      4. (Optional): Select "Specify Native Compilers" and provide paths to clang if using it
      5. Click Finish (first-time configuration will take some time, successive ones will be much faster)
      6. After configuring is complete, ensure UPDATE_SUBMODULES is checked and click "Generate"
      7. (Optional) Create another CMake build directory {repo_path}/out/RelWithDebInfo and repeat, but with CMAKE_BUILD_TYPE set to RelWithDebInfo
2. Build and debug/run the executable:
   • Via the terminal: navigate to the CMake build directory, then:
     1. Type ninja / make -j{threads} and press enter
     2. Navigate to MircoEngine's build directory ({repo_path}/Build)
     3. To Run: type ./{exe-filename} and press Enter
     4. To Debug: type gdb ./{exe-filename} and press Enter, at the gdb console type run and press Enter
   • If using Code::Blocks:
     1. Open the generated project
     2. Build ALL_BUILD
     3. Select MicroEngine as the debugging target
     4. Debug/Run the target

Note: Ensure to delete everything in Build except Resources, if and when changing build environments on the same {repo_path}.

Development

Adding Sources

• Do not add files to a project/solution, they will be removed when the next CMake generation gets triggered!
• Do add the file paths to Source/Source.cmake and build ZERO_CHECK from the IDE to regenerate CMake
• To manually regenerate CMake:
  1. Open CMake
  2. Click "Browse Build" and select the output directory previously chosen; CMake will detect and auto-load everything else
  3. Click Generate
• Run clang-format on all changes/new files

Troubleshooting

• To start from scratch, delete {repo_path}/{out} and everything in {repo_path}/Build except Resources
• Restore mistakenly deleted Resources via (running from {repo_path}):
  1. git reset -- Build/Resources
  2. git checkout Build/Resources
• To reset your changes to a remote branch: git reset --hard origin/{branch}
• To amend the HEAD commit: git commit --amend

Building (Compiling)

Visual Studio Code with MinGW 64

Instructions

1. In VS Code open a terminal and navigate to the directory where CMake built the project: cd {build path}
2. Build the project using: mingw32-make -j{threads}
3. Or, use Tools/build.sh (instructions in the script)

• This creates {executable}.exe in the Build directory
• Navigate to the Build directory with cd; cd {repo path}/Build;
• Execute: ./{executable}.exeto run the game