Debian Codegraph @

subprojects/meson-docs/docs/markdown/GuiTutorial.md

raw
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 ![Configuring the sample application](images/sdltutorial_01.png)
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 ![Running the sample application](images/sdltutorial_02.png)
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 ![Building SDL app fails](images/sdltutorial_03.png)
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 ![Obtaining SDL2 from WrapDB](images/sdltutorial_04.png)
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 ![Running the sample application](images/sdltutorial_05.png)
197
198 A bit later the compilation exits successfully.
199
200 ![Running the sample application](images/sdltutorial_06.png)
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 ![Running the sample application](images/sdltutorial_07.png)