An opinionated EmptyEpsilon development setup for windows

readme.md

An opinionated EmptyEpsilon setup for windows

This guide will take you through setting up a development environment for EmptyEpsilon on a windows machine.
It is published as part of a gist containing configuration files that are specific to this set-up. you will be asked to copy them to the project's folder.

This guide assumes you want to create a 32 bit application. Note that I'm experiencing issues producing a good 32 bit release. There seems to be a problem with linker optimizations as well as ERROR_ACCESS_VIOLATION of SFML using libstdc++-6.dll. However, building and running a debug binary works fine. To produce windows production releases, I'm using an automated script that can be found here

Required applications

In order to set up a windows development environment for EmptyEpsilon, you need to install the following applications.
These applications (as do most free windows tools) can be installed using Chocolatey to save the trouble.

• Git.
  This tutorial seems reasonable, except that I chose openSSL instead of Windows Secure Channel, assuming openSSL will be better documented and addressed in mainstream git-related tutorials.
  Speaking of, you should also create an SSH key and connect it to your github account.
  Also, configure your git
  Verify installation of git by using it in a new command prompt: git --version should print something like git version {...}
  Also, verify ssh connection to github

• CMake version 3.12.2 at least.
  Verify installation of cmake by using it in a new command prompt: cmake --version should print something like cmake version 3.12.2
  Cmake is basically 'yo-dog I hear you like build configurations so here's a build configuration system to configure your build configuration system'. It compiles 3rd party build configurations from its own build configurations.

• ninja.
  Verify installation of ninja by using it in a new command prompt: ninja --version should print something like 1.7.2
  Ninja is a build tool. If you want to use more standard build tools, you can choose to use visual studio (not vscode) build tool, or makefiles. Just download, install and configure accordingly.

• vscode with these extensions:

  • C/C++
  • CMake Tools
  • vscode-lua

Set up workspace files

• make a folder, we'll call it workspace
• clone EmptyEpsilon and SeriousProton into workspace

workspace> git clone git@github.com:daid/EmptyEpsilon.git
Cloning into 'EmptyEpsilon'...
{...}
workspace> git clone git@github.com:daid/SeriousProton.git
Cloning into 'SeriousProton'...
{...}

• workspace should now have two subdirs : EmptyEpsilon, SeriousProton. Verify this using dir command:

workspace>dir /w
{...}
[.]                      [..]  
[EmptyEpsilon]           [SeriousProton] 
{...}

• create folder workspace/EmptyEpsilon/.vscode and put the content of this gist inside
• download SFML 2.5.1 for windows 32 bit and extract it to workspace
• workspace should now have three subdirs : EmptyEpsilon, SeriousProton, SFML-2.5.1
• download MinGW GCC-7.3.0 windows 32 bit (dwarf) and extract it to workspace.
  notice that this version has to exactly match the version used to build SFML, so if at some point you update one you'd need to update the other (for example, if you want to compile for 64 bit). SFML usually provide good reference for that in their downloads page.
• workspace should now have four subdirs : EmptyEpsilon, SeriousProton, SFML-2.5.1, mingw32
• download drmingw for windows 32 bit and extract it to workspace
• workspace should now have five subdirs : EmptyEpsilon, SeriousProton, SFML-2.5.1, mingw32, drmingw-0.8.2-win32
• edit the file EmptyEpsilon/CmakeLists.txt: replace the line:

find_package(SFML 2.3 REQUIRED system window graphics network audio)

with the lines:

cmake_policy(SET CMP0074 NEW)
find_package(SFML 2.5 COMPONENTS system window graphics network audio REQUIRED)

Set up workspace configurations

• open a new vscode window, you should see a welcome message.
• in vscode, choose file > Add Folder to Workspace and choose the workspace\EmptyEpsilon folder.
• at the top of the window, a selection list will appear, prompting you to select a kit choose local mingw32. you will only have to do this once. Then it will bootstrap the the build environment for 1-2 seconds.

The big moment

Press F5 to start the build and debug job. The code will then compile. you will see a lot of action in the console tab. After that, EmptyEpsilon will run in debug mode. how awesome is that? 😎

Troubleshooting

some of the instructions here don't work for everyone. If you have an issue, read the conversation in the original gist, and see if someone have already faced a similar issue and has come up with a workaround. I will try to keep this file updated with the common issues.

• @schoolmeister 's fix for not finding SFML
• my own temporary hack for dealing with Syntax error in cmake code when parsing string errors

quirks while debugging EmptyEpsilon in vscode

• Read the Known Limitations of debugging C++ in vscode, and remember you're using MinGW. a particularly non intuitive detail to remember :

  To set a breakpoint when the application is running {...} press Ctrl-C in the application's terminal.

• Each debug configuration can only run a single instance. I've included two identical run configurations (gdb) Launch and (gdb) Launch2 to aid debugging multiplayer flows quickly.
• In this environment, the Escape key breaks the debugging. that's either a vs-code default hotkey, or something of the sort. Luckily, in EmptyEpsilon the Home Key serves the same purpose.

c_cpp_properties.json

{
    "configurations": [
        {
            "name": "win32",
            "includePath": [
                "${workspaceFolder}/src",
                "${workspaceFolder}/../SeriousProton/src",
                "${workspaceFolder}/../SFML-2.5.1/include"
            ],
            "browse" : {
                "path": [
                    "${workspaceFolder}/.."
                ],
                "limitSymbolsToIncludedHeaders" : true,
                "databaseFilename" : ""
            },
            "intelliSenseMode": "clang-x64",
            "configurationProvider": "vector-of-bool.cmake-tools",
            "compilerPath": "${workspaceFolder}/../mingw32/bin/gcc.exe",
            "cStandard": "c11",
            "cppStandard": "c++17"
        }
    ],
    "version": 4
}

cmake-kits.json

[
  {
    "name": "local mingw32",
    "compilers": {
      "CXX": "${workspaceFolder}/../mingw32/bin/g++.exe",
      "C": "${workspaceFolder}/../mingw32/bin/gcc.exe",
      "RC": "${workspaceFolder}/../mingw32/bin/windres.exe"
    }
  }
]

cmake-variants.yaml

buildType:
    default: debug
    choices:
        debug:
            short: Debug
            long: Build with debugging information
            buildType: Debug
        release:
            short: Release
            long: Build with optimizations
            buildType: Release
crashLogger:
    default: off
    choices:
        on:
            short: Log
            long: Enable the drmingw crash logging facilities
            settings:
                ENABLE_CRASH_LOGGER: ON
        off:
            short: Don't Log
            long: no crash logging 
            settings:
                ENABLE_CRASH_LOGGER: OFF

extensions.json

{
    "recommendations": [
        "ms-vscode.cpptools",
        "ms-vscode.cmake-tools",
        "trixnz.vscode-lua"
    ]
}

launch.json

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Launch",
            "type": "cppdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "args": ["httpserver=8081"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            // "externalConsole": true,
            "logging" : {
                // "engineLogging" : true,
                // "trace" : true,
                // "traceResponse" : true
            },
            "MIMode": "gdb",
            "miDebuggerPath": "${workspaceFolder}/../mingw32/bin/gdb.exe",
            "environment": [{ 
                "name" : "PATH",
                "value" : "${env:PATH};${workspaceFolder}\\..\\SFML-2.5.1\\bin;${workspaceFolder}\\..\\drmingw-0.8.2-win32\\bin;${workspaceFolder}\\..\\mingw32\\bin;"
            }],
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
            ]
        },
        {
            "name": "(gdb) Launch2",
            "type": "cppdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "args": ["httpserver=8081"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            // "externalConsole": true,
            "logging" : {
                // "engineLogging" : true,
                // "trace" : true,
                // "traceResponse" : true
            },
            "MIMode": "gdb",
            "miDebuggerPath": "${workspaceFolder}/../mingw32/bin/gdb.exe",
            "environment": [{ 
                "name" : "PATH",
                "value" : "${env:PATH};${workspaceFolder}\\..\\SFML-2.5.1\\bin;${workspaceFolder}\\..\\drmingw-0.8.2-win32\\bin;${workspaceFolder}\\..\\mingw32\\bin;"
            }],
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                },
            ]
        }
    ]
}

settings.json

{
    "cmake.configureOnOpen": true,
    "cmake.configureSettings": {
        "DRMINGW_ROOT" : "${workspaceFolder}/../drmingw-0.8.2-win32",
        "SFML_DIR" : "${workspaceFolder}/../SFML-2.5.1/lib/cmake/SFML/",
        "SFML_ROOT" : "${workspaceFolder}/../SFML-2.5.1/",
        "SERIOUS_PROTON_DIR" : "${workspaceFolder}/../SeriousProton"
    },
    "cmake.buildDirectory": "${workspaceFolder}/.bin/win",
    "C_Cpp.default.configurationProvider": "vector-of-bool.cmake-tools",
    "cmake.debugConfig": {
       "externalConsole" : true,
       "logging" : {
           "engineLogging" : true,
           "trace" : true,
           "traceResponse" : true
       },
       "MIMode": "gdb",
       "miDebuggerPath": "${workspaceFolder}/../mingw32/bin/gdb.exe",
       "environment": [{ 
            "name" : "PATH",
            "value" : "${env:PATH};${workspaceFolder}/../SFML-2.5.1/bin;${workspaceFolder}/../drmingw-0.8.2-win32/bin;${workspaceFolder}/../mingw32/bin;"
        }],
        "setupCommands": [
            {
                "description": "Enable pretty-printing for gdb",
                "text": "-enable-pretty-printing",
                "ignoreFailures": true
            }
        ]
    },
    "C_Cpp.configurationWarnings": "Disabled"
}

Hey amir-arad,

Thanks for your answers.

I use CMake 3.16.5.

Your workaround worked perfectly.
I subscribed to your issue, thanks for creating it.

@k9lego yeah the Escape key breaks the debugging. that's either a vs-code default hotkey, or something of the sort. usually in EmptyEpsilon the Home Key serves the same purpose, so I just switched to it and after a while it stopped bothering me :)

I've just used this tutorial on a new computer. The CMake plugin changed a bit, so I've updated the instructions accordingly.