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"
}

@amir-arad, wow pretty nice write up, need to dig into windows compilation for our next session. Thank you very much.

@LHolst my small contribution to this community and this great game

@LHolst check out daid/EmptyEpsilon#578

Installed all the software, but VSCode can't find cmake. cmake tools can't find the kit either. How do I tell VSCode where cmake is installed? How do I tell VSCode where to find the kit (in the /.vscode directory)?

I found where to specify the path to cmake within VSCode. Now I get "Set up and build your cmake project before debugging" and "Unable to determine what CMake generator to use. Please install or configure a preferred generator, or update settings.json or your kit configuration." This goes back to telling VSCode where to find the kit. Ideas?

Resolved the generator problem: you cannot specify the path in VSCode, Ninja must be in the path. Now I'm getting the error:

[cmake] CMake Error at cmake/FindSFML.cmake:356 (message):
[cmake] Could NOT find SFML (missing: SFML_SYSTEM_LIBRARY SFML_WINDOW_LIBRARY
[cmake] SFML_GRAPHICS_LIBRARY SFML_NETWORK_LIBRARY SFML_AUDIO_LIBRARY)
[cmake] Call Stack (most recent call first):
[cmake] CMakeLists.txt:383 (find_package)

...and yes, SFML is installed in the location specified

Got past the could not find SFML error by inserting this line in front of the find_package line in the Setup SFML part of CMakeLists.txt:
set(SFML_ROOT "C:\Personal\Games\EmptyEpsilon\gitViaVsCode\workspace\SFML-2.5.1")

Now I'm getting this error:
[build] FAILED: CMakeFiles/EmptyEpsilon.dir/src/pathPlanner.cpp.obj
[build] c:\Personal\Games\EmptyEpsilon\gitViaVsCode\workspace\EmptyEpsilon..\mingw32\bin\g++.exe -DDEBUG -DVERSION_NUMBER=20190212 -DWINDOW_TITLE="EmptyEpsilon" -I../../src -I../../../SeriousProton/src -Wall -g -std=gnu++11 -MD -MT CMakeFiles/EmptyEpsilon.dir/src/pathPlanner.cpp.obj -MF CMakeFiles\EmptyEpsilon.dir\src\pathPlanner.cpp.obj.d -o CMakeFiles/EmptyEpsilon.dir/src/pathPlanner.cpp.obj -c ../../src/pathPlanner.cpp
[build] In file included from ../../../SeriousProton/src/engine.h:6:0,
[build] from ../../src/spaceObjects/spaceObject.h:4,
[build] from ../../src/pathPlanner.h:4,
[build] from ../../src/pathPlanner.cpp:1:
[build] ../../../SeriousProton/src/P.h:4:10: fatal error: SFML/System.hpp: No such file or directory
[build] #include <SFML/System.hpp>
[build] ^~~~~~~~~~~~~~~~~
[build] compilation terminated.
[build] ninja: build stopped: subcommand failed.
[build] Build finished with exit code 1
[main] Failed to prepare executable target with name 'undefined'

Most importantly, THANK YOU Amir! Your efforts and skills are greatly appreciated!
Your process above was followed extremely carefully ( on Windows PC ).
Similar to @Xansta, I also had the " Can't Find SFML" Problem so I added a set(SFML_ROOT) link and then something compiled.
The resulting EXE binary is comparatively huge. 121 MB vs daid's normal 22 MB release, vs 4MB size I used to get from CodeBlocks.
Running the EXE has multiple "File Not Found " errors despite being in the root of the executable directory.
sfml-audio-d-2.dll
sfml-graphics-d-2.dll
sfml-network-d-2.dll
sfml-system-d-2.dll

This missing file was NOT in the root
libgcc_s_dw2-1.dll
but..
libgcc_s_sjlj-1.dll IS in in the root from the project default files.
I moved the requested file from the mingw32 library to the new EXE root and this single error is gone.

I really think this guide is a couple of short steps from glory and triumph.
Do you think you can take another look at your guide as compared to your local success and give some pointers please?
I promise to meticulously test your updated guide as a second set of eyes to validate things and take notes to add to help others,

• This Cmake build process makes a, basically, "naked" exe binary in the .bin/win folder.
  What collateral files are needed in the final EXE directory root for this particular build?
  I've been using step #14 of this but based on the libgcc file error above, there must be some differences.
• A linking/find issue with SFML that adding a local SFML_ROOT doesn't fix because it appears to break the relative file locations during run time.

Also note: Thinking this was related to the recent SFML upgrade, (see other issue).
I tested this guide using BOTH the newest source of Empty Epsilon and required libraries as well as the pre-SFML upgrade from November, 2018 (with libraries of the same age).
Results were the same.

@PlanetariumWSD Maybe worth emphasizing that this is a guide to set up a development environment, not something that produces releases. There's a difference. (mentioned at the beginning of the guide: "Note that currently I'm experiencing linker issues producing a 32 bit release binary [...] However, building and running a debug binary works fine.")

I only ever succeeded in running the game for debugging using this environment. I bet the EXE file size is as you describe, with no optimizations and all the symbol mapping and other debug data. I did conduct several (!) tests of this tutorial. Admittedly it was a while back and I'm scratching my head, comparing my working environment to the tutorial trying to find a clue.

I assume you've followed the instructions carefully?

as for releases:
I use this setup for releases (runs on linux, builds for windows)

the thing that helps the game find the missing dll files is the PATH environment variable in the debug configuration (under cmake.debugConfig in settings.json). If you plan on running the executable in any other way than the cmake launcher, you should apply similar environment variables.

same goes to running CMake outside of the vscode cmake plugin: cmake.configureSettings needs to be applied so that DRMINGW_ROOT, SFML_DIR, and SERIOUS_PROTON_DIR will be available to CMake. then you won't need to add SFML_ROOT.

@Xansta sorry I missed your comments :(
anything I can still help with?

I've switched to trying on a Mac which is closer to a Linux environment. If I go back to a Windows environment, I'll reexamine this set of instructions. I appreciate the work done to make this code base more accessible

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.