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 [email protected]:daid/EmptyEpsilon.git
Cloning into 'EmptyEpsilon'...
{...}
workspace> git clone [email protected]: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, I've managed to make this work. The settings I used can be found here.

In settings.json, I changed "SFML_DIR" : "${workspaceFolder}/../SFML-2.5.1/lib/cmake/SFML/"
to "SFML_ROOT" : "${workspaceFolder}/../SFML-2.5.1/" since SFML_DIR wasn't being used in (the current version of) CMakeLists.txt and also because the folder /lib/cmake has been removed since SFML 2.5. This sets the root of SFML without breaking CMakeLists.txt on non-windows platforms.

Then I added the following line in CMakeLists.txt above find_package:

cmake_policy(SET CMP0074 NEW)

Basically, without setting the root CMake simply couldn't find the SFML directory. However, setting the root resulted in policy warnings stating the variable (SFML_ROOT) had been ignored (even though that was obviously not the case) so this suppresses that warning and signals we're using the NEW policy.

Then, as in step #13 and #14 of the Code::Blocks setup, I copied the necessary folders from EmptyEpsilon and necessary DLLs from MinGW, DrMinGW and SFML (I had to copy the DLLs ending with "-d-2" for some reason though) to the build target folder.

After this I was able to debug using Visual Code, and also able to simply run the .exe in the build directory itself.
I know the environment configured in cmake.debugConfig is supposed to make the copying of the DLLs and folders obsolete but the files aren't being found for some reason.

good work @schoolmeister !

I've just installed a dev environment in a new PC. the build worked, the debug had an error in the path in settings.json.
I've submitted a fix in this gist.

Hi Amir,

I've been following this along (I think) correctly until I got to the "in the bottom blue bar you'll see a bug icon. click it." - there is no bug icon on the blue bar.

There is a bug on the grey bar on the left, but clicking on that doesn't expose anything where I can select "local mingw32".

Any clues what I've done wrong?

@nigelkennington This guide was written before version 1.2.1 of the CMake Tools plugin (which is responsible for that bug icon at the bottom). in 1.2.1 they changed a bunch of things, and now the bug icon sometimes not appear.
I suggest clicking the "build" label at the bottom bar. that will compile the project, but not run it. perhaps the bug icon will appear after that. I will try to come up with better run configurations and upload them here (I have it set up in my old workstation)

Thanks for getting back to me Amir.

I'm sorry about being thick here, but there is no "build" label on the bottom bar, the blue one yes? All I've got is:

"Master", circular arrows that claim to be "Synchronise Changes" if you hover over them, an x in a circle and a warning sign with zeros next to them that say "No problems" if you hover over them and then "Launch Program (EmptyEpsilon).

If I click "Launch Program" It says "debug" at the top and then if I select that it pops up a dialog saying "${file} can not be resolved. Please open an editor." which links to the launch.json file in the .vscode folder.

Progress! I uninstalled everything and reinstalled using chocolatey and it's working now. Hooray!

Thanks for your help! Now to see if I can work out how to get that sweet sounding docks and drones thing going!

Out of curiosity, how might this tutorial vary for Ubuntu 18.04 LTS. I'm trying to have my development and production compiling on the same Linux machine. This is amazing by the way, thanks for going out of your way to share it!

@k9lego My previous dev environment was ubuntu and it went very smooth. better than windows by far (debugging for one thing, and releases should be a breeze).
basically:

1. you don't need ninja and openSSL
2. find the best way to install / download the dependencies built for linux
3. rename executables accordingly (.exe files etc.)

Hey amir-arad,

Thanks for this document, it is very usefull.

However, when I try to build (little bug button down in the blue bar), I have tones of the same error :

[cmake] CMake Error at CMakeLists.txt:386 (add_executable):
[cmake] Syntax error in cmake code when parsing string
[cmake]
[cmake] c:\Users\myuser\source\repos\EEWorkspace\EmptyEpsilon/../SeriousProton/src/soundManager.cpp

it seems weird that they are both \ and / in the path, but I have no idea how to fix it.

Any thoughts ?

See you

Hi @lacombet
very strange. I've been using both kinds of slashes like that successfully for years. Suddenly, now I get these errors as well...

What version of CMake are you running? (run cmake --version to find out)

opened this ticket, hope it helps:
microsoft/vscode#92218

my workaround is to replace ${workspaceFolder} in settings.json with the folder's path containing forward slashes.
In @lacombet case that should be:
c:/Users/myuser/source/repos/EEWorkspace/EmptyEpsilon

I followed these instructions and it worked. Thanks a ton! Running into one minor issue though, the escape key used to exit a console also seems to end the debugging session. Any ideas what might be going on there?

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.