Chapter 2 – Installation and Configuration

Last updated on July 22nd, 2020

What is covered, what not?

  • installation guide for SDL 2.0 under Microsoft Windows
  • installation of Free Pascal Compiler (FPC)
  • installation of Free Pascal IDE and Lazarus IDE
  • installation of SDL 2.0
  • configuration of FP IDE and Lazarus IDE to work with SDL 2.0
  • after this you are ready to code awesome SDL 2.0 stuff 🙂

Free Pascal IDE or Lazarus IDE

IDE stands for integrated development environment. Although you could write your programs in a simple text editor, an IDE makes your life much easier. For example, it highlights keywords, makes it easier for you to set up the compiler, and much more. Now let’s have a look at these two IDEs:

You may notice that the native Free Pascal IDE (left) looks old, but it is shipped right along with the Free Pascal Compiler. In contrast to that the Lazarus IDE (right) looks up-to-date, but requires it to be installed additionally. My advise is nonetheless, use the Lazarus IDE.

The Free Pascal Compiler (FPC)

We need three different software packages. First of all we need the stand-alone Free Pascal Compiler or Lazaruse IDE (which already has a copy of the Free Pascal Compiler included). If you are not sure, I recommend to go with the Lazarus IDE package.

SDL Library and SDL 2.0 units

Additionaly we need the original SDL library files (.dll files). And finally we need units that connect our SDL 2.0 code written in Free Pascal to the SDL library files. The latter will be done by SDL 2.0 units.

This table provides all information and sources you need with respect to installation steps 1) – 3). Keep in mind, you have to download either the Lazarus IDE or the stand-alone Free Pascal Compiler, not both.

approx. Size [MB]
Source link
Details and remarks
Lazarus IDE (has FPC included)
1.4.4 or later
Linux and Mac OS X versions are here: (see Downloads).
Free Pascal Compiler (stand-alone)
3.0.0 or later
Windows 32 bit version
Windows 64 bit version (needs 32 bit version)
If you need the Linux, Mac OS X or other versions, check them out here: (see Download).
SDL 2.0 units
1.72* (see remark)
On the right upper side is a button saying Download ZIP. Click on this button for the download of the latest release. *Better go with the latest availabe version (not version 1.72!) since some important bugfixes have been made lately.
SDL 2.0 dynamic link library
SDL 2.0 > Download > Choose the download suitable for your system.

Download Lazarus or the stand-alone Free Pascal Compiler (FPC)

If you have Free Pascal or the Lazarus IDE installed already, you can skip the steps 1a) and 1b).

1a) For Lazarus IDE: Download the latest version of the Lazarus IDE. It has the Free Pascal Compiler accompanied. Remark: As of today (12/02/2016) the bundle doesn’t provide the most recent Free Pascal Compiler (3.0.0) but the version before (2.6.4). The tutorial examples will work with both versions though.

1b) For Free Pascal IDE: 32 bit Windows: Download the latest stable Free Pascal compiler, version 3.0.0 or higher. 64 bit Windows: You have two choices, 1) Simple way: Go with the 32 bit version of Free Pascal. (Recommended), 2) Install the 64 bit version of Free Pascal on top of the 32 bit version of Free Pascal. In this case you need both files. Hence, you need to download both Free Pascal installers shown above.

Download SDL 2.0 and Header translation

2) Download the latest version of Tim Blume’s SDL 2.0 units, better go with the latest branch (master branch), and do not use version 1.72 since it contains some bugs. Click on “Clone or download” and then on “Download ZIP” (see arrows in image below) of the page and make sure that Branch: master (not v1.72!) is chosen at the left side (see arrow in image below). This is important for any operating system: Windows, Linux, Mac OS X.

Download SDL2 units on GitHub
Choose the master branch (1), click on “Clone or download” (2) and click on Download ZIP (3).

3) Download the latest version of SDL 2.0 runtime library, version 2.0.4 or higher.

Install Lazarus or the Free Pascal Compiler

4a) For Lazarus: 32 and 64 bit Windows: Execute lazarus-1.4.4-fpc-2.6.4-win32.exe  to install Lazarus for a 32 bit or 64 bit Windows system and follow the self-installer. Let the self-installer create a shortcut on your desktop.

4b) For Free Pascal IDE: 32 and 64 bit Windows: Execute fpc-2.6.4.i386-win32.exe  to install Free Pascal for a 32 bit or 64 bit Windows system. Let the self-installer create a shortcut on your desktop. Don’t modify any checked options during installation process. The default path is: C:\FPC\[Compiler version]\. [Compiler version] should be 3.0.0 or higher numbers. 64 bit Windows only: After you installed the 32 bit Free Pascal, you may execute fpc-3.0.0.i386-win32.cross.x86_64-win64.exe optionally to add the 64 bit version on top.

Install SDL 2.0 and Header translation

5) Extract or to get the SDL runtime library. This leads to two extracted files. There is a text file and the very important SDL2.dll.

6) 32bit Windows: Copy those files (especially the SDL2.dll!) to your system32-folder, C:\WINDOWS\system32\. 64bit Windows:  Copy those 64bit files to your system32-folder (!), C:\WINDOWS\system32\, Windows is expecting you to do this. Do not use the SysWoW64-folder (Hint: 32 bit files on 64 bit Windows go here).

If it is not possible to copy the files into this folder (or you are unsure about its location) alternativly you can copy the SDL2.dll right into the same folder where the SDL 2.0 application (.exe) is located. That is because SDL 2.0 first  looks for the SDL2.dll in the folder from which it is executed and if it isn’t found there, in the corresponding system folder! Anyway, if it isn’t found anywhere, the program will raise an error.

Now you have installed Free Pascal and the SDL runtime library on your system. Finally SDL 2.0 units have to be installed.

7a) For Lazarus IDE: Extract the The Free Pascal Compiler is located in a subfolder called “fpc”. I suggest to copy all the files to a folder with full path C:\Lazarus\fpc\[Compiler Version]\units\SDL2\. [Compiler version] should be 2.6.4 or higher numbers. Skip step 7b).

7b) For Free Pascal IDE: Extract the I suggest to copy all the files to a folder with full path C:\FPC\[Compiler Version]\units\SDL2\. [Compiler version] should be 3.0.0 or higher numbers. All later chapters will assume you installed to this path.

Configuring the Lazarus IDE

Now the compiler has to be told where to find the new units.

8) Open the Free Pascal IDE (for example by clicking the shortcut on desktop).

Lazarus IDE Desktop Icon

9) In Lazarus the path to external units has to be set for each project. Create a project if no project is set up (Project > New Project …). In the menue choose the following item Project > Project Options …. Now a window should pop up.

10) Under “Compiler Options” choose “Paths” (see red mark). Choose the three dots button (see red mark on the right side) for the “Other units files (-Fu)” field (red mark). This makes the “Path Editor” pop up. In the area “Search paths:”, click on the yellow folder symbol in the right bottom corner. Choose the path to your SDL-units (e.g. C:\Lazarus\2.6.4\units\SDL2). Make sure the path leads to the folder, where the sdl2.pas file is located! This file contains all the basic features of SDL 2.0.

Lazarus IDE Include Paths

Confirm by clicking “OK” until all windows are closed. Your Lazarus IDE is now set up for SDL 2.0 application development :-)!

Configuring the Free Pascal IDE (skip if you use Lazarus)

Now the compiler has to be told where to find the new units.

8) Open the Free Pascal IDE (for example by clicking the shortcut on desktop).

Free Pascal IDE Desktop Icon

9) In the menue choose the following item Options > Directories…. Now a window should pop up.

10) The first tab whitin this new window is called “Units”. Here you add the full path to your SDL-units (e.g. C:\FPC\3.0.0\units\SDL2) right below the other paths. Leave the last backslash out. Make sure the path leads to the folder, where the sdl2.pas file is located! This file contains all the basic features of SDL 2.0.

SDL2 directories
Since the screenshot is old, the compiler version has been 2.6.2, which is reflected in the shown pathes. It should be 3.0.0 or higher numbers for you.

Confirm by clicking “OK”.


Congratulations! You have configured your system for developing SDL 2.0 applications with the Lazarus IDE or the Free Pascal IDE! Simple, isn’t it? 🙂

For those of you who try running a program and get an abortion together
with a messege saying “exitcode = 309”: You skipped step 6! Did you copy
the SDL2.dll to your system32- or system-folder respectively? If so and the
error still occurs you should copy the SDL2.dll into the folder
where the programs are placed. Now it should work.

← Chapter 1 | Chapter 3 →

12 thoughts on “Chapter 2 – Installation and Configuration

  1. Hi ….pleasant day

    Not very comfortable with all these manual required component installations.
    Is there not an “one click ” download and install all components and ready to use.
    Appreciate any advice.


  2. Hi. Can you help me? I can’t run first simple program with SDL. It compiles succesfully, but gives an error 0xc000007b while running. I’m using Free Pascal compiler. I have WIndows 10 (64-bit) and downloaded FPC 64-bit (AMD64/Intel 64/x86_64). I also downloaded SDL2 (64-bit) and copied .dll to SysWOW64 (it hasn’t been comiled when I copied it to System32). What should I do now?

    1. Hi MDtox,
      did you install the native FPC 32-bit compiler before installing the 64-bit cross compiler on top? – If not, make sure to do so, because otherwise FPC won’t work properly.

      You should also copy the SDL2 64-bit files to the system32-folder. SysWOW64 is really the wrong location. What error message you get, if you try to compile the program now?

  3. Hi !
    I wanted to know how can I Install SDL 2.0 and Header translation in geany or notepad++
    because I cant find any option for the units


    1. Hi Leonel,
      unfortunately I’m not familiar with neither Geany nor Notepad++. You may look into the documentations of either editor where to find the option to set up unit/header files.

  4. Had some weird results on Linux with the SDL2 units, had to rename them to use lowercase prefixes (i.e sdl2_image instead of SDL2_image). The project using the units would build fine in Lazarus, but code completion (ctrl+space) triggered errors (unit not found), and compiling from command line also reported errors about missing units. Might be the same case on OSX, haven’t tried it yet.

      1. Hi there Mr. Matthius,

        I have followed your installation guide for SDL2 for FPC under Linux and I even followed the other fella’s advice on renaming the captital SDL2_gfx.pas Ect.

        And as far as I know FPC finds it and everything but for some reason when i try to compile the example in your getting started tutorial it keeps giving me an Error 5 message saying that it cannot create SDL2.o or somthing like that. do you know what is happening ?. below is my system config.

        Ubuntu 16.10 Xenial edition
        FPC 3.0.0
        SDL2 bindings latest version from gihub
        SDL2 Linux Dev files, headers, Runtime files
        All dependencies that SDL2 Requires for building the lib(s)

        I have never had this many problems on linux before or with FPC for that matter.

        Thanks in advance for any and all help or suggestions on how to fix this problem.

        Russell Morton.

        1. Hello Russell Morton,

          Well, I wonder why would you use the SDL2 Linux Dev files and try to compile the library yourself, I’m sure Ubuntu has the library pre-compiled in their package manager for you :-). Or do you really need the very last release version of SDL2?

          I just released a short Linux installation instruction. Maybe it can help.

          Please let me know if you succeeded in getting it run.

    1. @Rickmeister: I tried it now. I unfortunately (or fortunately?) can’t confirm these troubles. I could compile chapter 3-9 without any trouble and the code completion doesn’t trigger errors for me.

Leave a Reply

Your email address will not be published. Required fields are marked *