| 1 |
--- |
| 2 |
short-description: A simple GUI tutorial |
| 3 |
... |
| 4 |
|
| 5 |
# Building a simple SDL2 app from scratch |
| 6 |
|
| 7 |
This page shows from the ground up how to define and build an SDL2 gui |
| 8 |
application using nothing but Meson. The document is written for |
| 9 |
Windows, as it is the most complex platform, but the same basic ideas |
| 10 |
should work on Linux and macOS as well. |
| 11 |
|
| 12 |
The sample application is written in plain C as SDL 2 is also written |
| 13 |
in C. If you prefer C++ instead, the conversion is fairly simple and |
| 14 |
is left as an exercise to the reader. |
| 15 |
|
| 16 |
This document assumes that you have already installed both Visual |
| 17 |
Studio and Meson. |
| 18 |
|
| 19 |
# Set up the build directory |
| 20 |
|
| 21 |
First you need to create an empty directory for all your stuff. The |
| 22 |
Visual Studio toolchain is a bit unusual in that it requires you to |
| 23 |
run your builds from a specific shell. This can be found by opening |
| 24 |
the application menu and then choosing `Visual Studio <year> -> x86_64 |
| 25 |
native tools command prompt`. |
| 26 |
|
| 27 |
It will put you in a weird directory, so you need to go to your home |
| 28 |
directory: |
| 29 |
|
| 30 |
cd \users\yourusername |
| 31 |
|
| 32 |
Typically you'd type `cd \users\` and then press the tabulator key to |
| 33 |
make the shell autocomplete the username. Once that is done you can |
| 34 |
create the directory. |
| 35 |
|
| 36 |
mkdir sdldemo |
| 37 |
cd sdldemo |
| 38 |
|
| 39 |
# Creating the sample program |
| 40 |
|
| 41 |
Now we need to create a source file and a Meson build definition file. |
| 42 |
We're not going to use SDL at all, but instead start with a simple |
| 43 |
program that only prints some text. Once we have it working we can |
| 44 |
extend it to do graphics. The source goes into a file `sdlprog.c` and |
| 45 |
has the following contents: |
| 46 |
|
| 47 |
```c |
| 48 |
#include <stdio.h> |
| 49 |
|
| 50 |
int main(int argc, char **argv) { |
| 51 |
printf("App is running.\n"); |
| 52 |
return 0; |
| 53 |
} |
| 54 |
``` |
| 55 |
|
| 56 |
The build definition goes to a file called `meson.build` and looks |
| 57 |
like this: |
| 58 |
|
| 59 |
```meson |
| 60 |
project('sdldemo', 'c') |
| 61 |
|
| 62 |
executable('sdlprog', 'sdlprog.c') |
| 63 |
``` |
| 64 |
|
| 65 |
With this done we can start the build with the following command: |
| 66 |
|
| 67 |
meson setup builddir |
| 68 |
|
| 69 |
Here `builddir` is the _build directory_, everything that is generated |
| 70 |
during the build is put in that directory. When run, it should look |
| 71 |
like this. |
| 72 |
|
| 73 |
 |
| 74 |
|
| 75 |
The program is compiled with this: |
| 76 |
|
| 77 |
meson compile -C builddir |
| 78 |
|
| 79 |
The `-C` argument tells Meson where the configured build directory is. |
| 80 |
|
| 81 |
The program will be in the build directory and can be run like this: |
| 82 |
|
| 83 |
builddir\sdlprog |
| 84 |
|
| 85 |
The output should look like this. |
| 86 |
|
| 87 |
 |
| 88 |
|
| 89 |
# Upgrading the program to use SDL |
| 90 |
|
| 91 |
The code needed to start SDL is a bit more complicated and we're not |
| 92 |
going to go into how it works. Merely replace the contents of |
| 93 |
`sdlprog.c` with the following: |
| 94 |
|
| 95 |
```c |
| 96 |
#include "SDL.h" |
| 97 |
|
| 98 |
int main(int argc, char *argv[]) |
| 99 |
{ |
| 100 |
SDL_Window *window; |
| 101 |
SDL_Renderer *renderer; |
| 102 |
SDL_Surface *surface; |
| 103 |
SDL_Event event; |
| 104 |
|
| 105 |
if (SDL_Init(SDL_INIT_VIDEO) < 0) { |
| 106 |
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't initialize SDL: %s", SDL_GetError()); |
| 107 |
return 3; |
| 108 |
} |
| 109 |
|
| 110 |
if (SDL_CreateWindowAndRenderer(320, 240, SDL_WINDOW_RESIZABLE, &window, &renderer)) { |
| 111 |
SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Couldn't create window and renderer: %s", SDL_GetError()); |
| 112 |
return 3; |
| 113 |
} |
| 114 |
|
| 115 |
while (1) { |
| 116 |
SDL_PollEvent(&event); |
| 117 |
if (event.type == SDL_QUIT) { |
| 118 |
break; |
| 119 |
} |
| 120 |
SDL_SetRenderDrawColor(renderer, 0x00, 0x00, 0x00, 0x00); |
| 121 |
SDL_RenderClear(renderer); |
| 122 |
SDL_RenderPresent(renderer); |
| 123 |
} |
| 124 |
|
| 125 |
SDL_DestroyRenderer(renderer); |
| 126 |
SDL_DestroyWindow(window); |
| 127 |
|
| 128 |
SDL_Quit(); |
| 129 |
|
| 130 |
return 0; |
| 131 |
} |
| 132 |
``` |
| 133 |
|
| 134 |
Let's try to compile this by running `meson compile -C builddir` again. |
| 135 |
|
| 136 |
 |
| 137 |
|
| 138 |
That fails. The reason for this is that we don't actually have SDL |
| 139 |
currently available. We need to obtain it somehow. In more technical |
| 140 |
terms SDL2 is an _external dependency_ and obtaining it is called |
| 141 |
_dependency resolution_. |
| 142 |
|
| 143 |
Meson has a web service for downloading and building (if needed) |
| 144 |
dependencies called a WrapDB. It provides SDL2 so we can use it |
| 145 |
directly. First we need to create a `subprojects` directory because in |
| 146 |
Meson all subprojects like these must be stored in that directory for |
| 147 |
consistency. |
| 148 |
|
| 149 |
mkdir subprojects |
| 150 |
|
| 151 |
Then we can install the dependency: |
| 152 |
|
| 153 |
meson wrap install sdl2 |
| 154 |
|
| 155 |
It looks like this: |
| 156 |
|
| 157 |
 |
| 158 |
|
| 159 |
As a final step we need to update our build definition file to use the |
| 160 |
newly obtained dependency. |
| 161 |
|
| 162 |
```meson |
| 163 |
project('sdldemo', 'c', |
| 164 |
default_options: 'default_library=static') |
| 165 |
|
| 166 |
sdl2_dep = dependency('sdl2') |
| 167 |
|
| 168 |
executable('sdlprog', 'sdlprog.c', |
| 169 |
win_subsystem: 'windows', |
| 170 |
dependencies: sdl2_dep) |
| 171 |
``` |
| 172 |
|
| 173 |
**NOTE:** If you're on Windows you need to include the sdl2main dependency as well; To do so you can modify the above build script like so: |
| 174 |
|
| 175 |
```meson |
| 176 |
project('sdldemo', 'c', |
| 177 |
default_options: 'default_library=static') |
| 178 |
|
| 179 |
sdl2_dep = dependency('sdl2') |
| 180 |
sdl2_main_dep = dependency('sdl2main') |
| 181 |
|
| 182 |
executable('sdlprog', 'sdlprog.c', |
| 183 |
win_subsystem: 'windows', |
| 184 |
dependencies: [sdl2_dep, sdl2_main_dep]) |
| 185 |
``` |
| 186 |
|
| 187 |
In addition to the dependency this has a few other changes. First we |
| 188 |
specify that we want to build helper libraries statically. For simple |
| 189 |
projects like these it makes things simpler. We also need to tell |
| 190 |
Meson that the program we are building is a Windows GUI |
| 191 |
application rather than a console application. |
| 192 |
|
| 193 |
This is all we need to do and can now run `meson compile` again. First |
| 194 |
the system downloads and configures SDL2: |
| 195 |
|
| 196 |
 |
| 197 |
|
| 198 |
A bit later the compilation exits successfully. |
| 199 |
|
| 200 |
 |
| 201 |
|
| 202 |
# Program is done |
| 203 |
|
| 204 |
Now we can run the application with |
| 205 |
|
| 206 |
builddir\sdlprog |
| 207 |
|
| 208 |
The end result is a black SDL window. |
| 209 |
|
| 210 |
 |