Jamie's Blog

Setting up SFML on Windows, OS X and Linux

Tags: Programming

This is a small guide I wrote for Warwick Game Design to get people started with C++ game development with SFML on whatever platform they prefer. Provided that platform is Windows, OS X or Linux. Hopefully it won’t take too much time to get through – if you have any trouble, feel free to email me. If you find any problems or confusing sections please let me know – I wrote it in one sitting, so there are bound to be mistakes.

To start, we’ll install a development environment of your choice – you may have one set up already. We’ll then install the Simple and Fast Media Layer (SFML) library, which is the only external library you’ll need to get started writing some simple games.

I assume that you have some familiarity with the idea of a terminal/command line/console. Wherever I say to enter a command, I mean for you to use a command line. Where I list commands like

$ ls ~/somedir
$ g++ ~/somedir/somefile.cpp

everything following the $ is a command.

Windows

Development environment

There are two main ways to develop C++ applications on Windows. One is to use Microsoft’s own C++ runtime, which is distributed as part of the .NET framework, and will typically use their C++ compiler as shipped with the Visual Studio IDE.

The other method is to shut your eyes and pretend very hard that you’re using a unix-like system, aided by the use of a posix compatibility layer called MSYS2 and the open-source MinGW compiler, which builds executables from your source-code, and provides its own independent C++ runtime which is more similar to that found on other platforms.

In this guide we will look at both options - you may find the Visual Studio route more straightforward, but for cross-compatibility between platforms I would advocate the MSYS2 approach.

Visual Studio 2015

Visual Studio is the official Microsoft Integrated Development Environment (IDE). It bundles its own compiler along with a runtime debugger and an integrated text editor providing code completion and other useful features. However, adding external libraries like SFML can be a bit tedious.

If you’re a Warwick or other university student, there are two versions you may be able to get for free:

Community:

Enterprise:

Available through Warwick’s DreamSpark account for Science, Technology, Engineering and Mathematics (STEM) students:

  • Go to the DreamSpark page

  • Select “sign in”, then Single Sign On (Shibboleth), and log in with your ITS credentials

  • Navigate to the Visual Studio 2015 page, and select Visual Studio Enterprise 2015

(NB: you can also get free copies of every recent version of Windows!)

Installing Visual C++ – Hello World

The first thing you need to do is launch Visual Studio (and possibly register it with your Windows Live account). Then, go to File->New->Project. In the New Project dialogue, select Visual C++, and then double click “Install Visual C++ 2015 Tools for Windows Desktop” and follow the on-screen instructions.

Once this is finished, restart Visual Studio, go back to the Visual C++ tab of the New Project dialogue, and select Empty Project. You will also need to name the project: call this one “Hello World”.

Now, we need to create our project’s main file, where our main() function lives, which is where our program starts executing. On the right, you’ll see the Solution Explorer window, showing the layout of our project. Right click on the Source Files folder, select add (Ctrl+Shift+A), and double click C++ File (.cpp).

Now, copy out the following program:

#include <iostream>

int main() {
    std::cout << "Hello World!" << std::endl;

    return 0;
}

Save this, and optionally rename it to main.cpp. To run the code, click the green “play” arrow with the label Local Windows Debugger (F5). It will inform you that the project is out of date and ask if you want to build it. Before you click “yes,” I suggest you tick the “do not show this dialog again,” check-box to make it build every time.

You should have seen a command prompt open, and promptly vanish. This is because Visual Studio opens it to run your program, and closes it when your program exits. While you can use the Windows OutputDebugString() function to output text to the debug window, this ties your program to Windows – bad! For now, just stick the line

while (true);

before the line

return 0;

This will stop the program from exiting next time, until you click the command prompt’s close button or Visual Studio’s red “stop debugging” button (Shift+F5).

Installing SFML – Hello Triangle

Next, we want to set up SFML. Replace the code from the previous section with this:

#include <iostream>
#include <SFML/Window.hpp>

int main()
{
    sf::Window window(sf::VideoMode(512, 512), "Hello Triangle!");
}

If you try to run this, it will fail to compile. This is because not only have we not set up SFML, we haven’t even got it on our system yet.

You’ll want to download the latest version of the SFML library from the SFML downloads page. You want to get the 32 bit Visual C++ 14 (2015) version. Extract the files from the zip wherever you like.

Now you have to choose where to put the core library files. There are three folders you need:

  • include/ - the C++ header files (.hpp files) that declare the SFML functions you call in your code (open one of these in a text editor to look around!)

  • bin/ - the dynamic link libraries (.dll files) which contain the compiled SFML functions that your code calls at runtime.

  • lib/ - the static libraries (.lib files) which get built into your program at compile-time, often complemented by .dlls in the bin/ folder.

Managing libraries on Windows is a pain. While hardened Windows developers may have preferred methods for installation, I do what I find simplest: stick the bin/, include/ and lib/ folders in the root folder of my C:\ drive. This is pretty horrid, but whether or not it makes your skin crawl, follow my lead for now, and you can move them somewhere nicer once you understand how to get everything working.

Now, in your Hello World project, right click on the project root (Hello World, below Solution 'Hello World' (1 project)), and select Properties. In the Properties pages, select VC++ Directories.

For each of Include Directories and Library Directories in the list, click on the field on the right, and a drop-down arrow will appear. Click the arrow, and then the pop-up saying <Edit...>.

In the pop-up window, click the yellow New Folder button to the top-right, and type the appropriate path:

  • Include Directories: C:\include
  • Library Directories: C:\lib

This tells the compiler that it should search C:\include when looking for header files you #include in your code, and C:\lib when looking for libraries to link into your executable.

Now you need to tell the linker which libraries to link. In the same window, go to “Linker”->“Input”, and modify the “Additional Dependencies” field with the drop-down box as before. Add the following text to the box:

sfml-system.lib
sfml-graphics.lib
sfml-window.lib
sfml-main.lib

These are all of the .lib files SFML needs to create a window and draw graphics to the screen.

This should be everything we need to build the solution. If you close the property pages, and go to Build->Build Solution in the menu bar (Ctrl+Shift+B), there shouldn’t be any problems. However, if you try to run your program (F5), it will crash with an error:

The program can’t start because sfml-system-2.dll is missing from your computer.

This is because the debugger which runs the program doesn’t know where SFML’s .dll files are. This information needs to be given to it at runtime.

Go back to the project property pages (right click on “Hello World” in the Solution Explorer and select “Properties”). Go to “Debugger”, and select the “Environment” field. Edit it as before, and add the line

PATH=%PATH%;C:\bin

Now the debugger will tell our program where to find the .dlls. Close the property pages again, and hit F5 to run the program. A square window should flash open on the screen and then close again, along with the console window from before. If this works, then we’re all set to move on!

MSYS2

MSYS2 is a posix compatibility layer based on CYGWIN which provides a unix/linux-like environment on Windows. That means that it gives you a command-line interface from which you can run specially-converted Linux programs, the most important of which is the MinGW C/C++ compiler.

This option doesn’t permit the use of an IDE to compile your code (without some additional setup) but it does make installing SFML much simpler.

MSYS2 uses Arch Linux’s package manager, pacman. The most useful commands are -S, which installs listed packages, and -Ss, which searches for a package:

$ pacman -S git cmake # install the git and cmake packages
$ pacman -Ss sfml # search for packages containing the string "sfml"

If a package can’t be found when installing it, use -Ss to find what it’s actually called.

Once you’ve installed MSYS2, you should be able to follow the instructions from the OS X/Linux section.

OS X/Linux

OS X and the different Linux distributions are all unix-like operating systems. In this guide we will hope for the best that the steps are similar regardless of your distribution.

Development environment

For development environment, there is a lot to choose from. IDEs are available, but to keep things simple I recommend sticking to a text editor for writing code:

  • Sublime Text
  • KWrite/Kate
  • gedit
  • vim or emacs (not to be undertaken lightly)

You’ll also want a compiler and a few other tools. There are two major C++ compilers, GCC and Clang - whichever you choose, the following steps will be the same, except the compiler will be called either g++ or clang++. These will be available via your package manager; many distros bundle GCC with other useful tools in a general development package, for example:

  • build-essential (Ubuntu, Debian, Linux Mint)
  • base-devel (Arch Linux)

Otherwise, you should be able to install them by name (gcc or clang). In this case, you should also install make for build automation.

On OS X, install the Homebrew package manager, and then do

$ brew install gcc
$ brew install make

Installing SFML

Using libraries in unix-like systems is usually as simple as installing them through your distro’s package manager:

  • Ubuntu, Debian and Linux Mint:

    $ sudo apt-get install libsfml-dev
  • Arch Linux:

    $ sudo pacman -S sfml
  • MSYS2:

    $ sudo pacman -S mingw-w64-sfml-git
  • OS X:

    $ brew install sfml

Otherwise, you should follow the SFML install guide.

Writing a “Hello World” program

Once you’re happy with your development environment, the next thing you should do is write a simple C++ program to make sure everything is set up properly.The typical first program in any language is one which outputs “Hello World!” to the screen and then exits. Let’s try that.

#include <iostream>

int main() {
    std::cout << "Hello World!" << std::endl;

    return 0;
}

Write this out and save it to hello_world.cpp.

There’s a surprising amount going on here. First we include “iostream” from the C++ standard library, which provides input and output in the form of streams. We define a function main with type int (integer number). main is always the function where our program starts, and it must always return an int (in this case 0); however, in C++ we can leave out return 0 for main as this is the default (NB: no other function allows this!).

We output the string “Hello world!” as a stream, using the << “output stream” operator, which sends the string to cout (standard output) and ends it with endl (end line). cout and endl are defined in the standard library, and live in the std namespace, which prevents collisions between different libraries. This means we need to prepend them with std:: to ensure we get the cout we expected.

Now we want to compile our code,

$ g++ -o my_program hello_world.cpp

and then run it:

$ ./my_program

This should print “Hello World!” in the terminal (or debug output in VS).

Hello Rectangle

Ok, great. We can write text to a terminal. Next, we want to display something graphical. I ran out of time writing this here, but you can continue on your own with the SFML tutorials.