Debian Codegraph @

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

raw
1 ---
2 short-description: Simplest tutorial
3 ...
4
5 # Tutorial
6
7 This page shows from the ground up how to create a Meson build
8 definition for a simple project. Then we expand it to use external
9 dependencies to show how easily they can be integrated into your
10 project.
11
12 This tutorial has been written mostly for Linux usage. It assumes that
13 you have GTK development libraries available on the system. On
14 Debian-derived systems such as Ubuntu they can be installed with the
15 following command:
16
17 ```
18 sudo apt install libgtk-3-dev
19 ```
20
21 In addition, it is recommended to have the glib library with version 2.74 or higher.
22
23 It is possible to build the GUI application on other platforms, such
24 as Windows and macOS, but you need to install the needed dependencies.
25
26 The humble beginning
27 -----
28
29 Let's start with the most basic of programs, the classic hello
30 example. First we create a file `main.c` which holds the source. It
31 looks like this.
32
33 ```c
34 #include <stdio.h>
35
36 //
37 // main is where all program execution starts
38 //
39 int main(int argc, char **argv) {
40 printf("Hello there.\n");
41 return 0;
42 }
43 ```
44
45 Then we create a Meson build description and put it in a file called
46 `meson.build` in the same directory. Its contents are the following.
47
48 ```meson
49 project('tutorial', 'c')
50 executable('demo', 'main.c')
51 ```
52
53 That is all. Note that unlike Autotools you [do not need to add any
54 source headers to the list of
55 sources](FAQ.md#do-i-need-to-add-my-headers-to-the-sources-list-like-in-autotools).
56
57 We are now ready to build our application. First we need
58 to initialize the build by going into the source directory and issuing
59 the following commands.
60
61 ```console
62 $ meson setup builddir
63 ```
64
65 We create a separate build directory to hold all of the compiler
66 output. Meson is different from some other build systems in that it
67 does not permit in-source builds. You must always create a separate
68 build directory. Common convention is to put the default build
69 directory in a subdirectory of your top level source directory.
70
71 When Meson is run it prints the following output.
72
73 The Meson build system
74 version: 0.13.0-research
75 Source dir: /home/jpakkane/mesontutorial
76 Build dir: /home/jpakkane/mesontutorial/builddir
77 Build type: native build
78 Project name is "tutorial".
79 Using native c compiler "ccache cc". (gcc 4.8.2)
80 Creating build target "demo" with 1 files.
81
82 Now we are ready to build our code.
83
84
85 ```console
86 $ cd builddir
87 $ ninja
88 ```
89
90 If your Meson version is newer than 0.55.0, you can use the new
91 backend-agnostic build command:
92
93 ```console
94 $ cd builddir
95 $ meson compile
96 ```
97
98 For the rest of this document we are going to use the latter form.
99
100 Once the executable is built we can run it.
101
102 ```console
103 $ ./demo
104 ```
105
106 This produces the expected output.
107
108 Hello there.
109
110 Adding dependencies
111 -----
112
113 Just printing text is a bit old fashioned. Let's update our program to
114 create a graphical window instead. We'll use the
115 [GTK+](https://gtk.org) widget toolkit. First we edit the main file to
116 use GTK+. The new version looks like this.
117
118 ```c
119
120 #include <gtk/gtk.h>
121
122 //
123 // Should provided the active view for a GTK application
124 //
125 static void activate(GtkApplication* app, gpointer user_data)
126 {
127 GtkWidget *window;
128 GtkWidget *label;
129
130 window = gtk_application_window_new (app);
131 label = gtk_label_new("Hello GNOME!");
132 gtk_container_add (GTK_CONTAINER (window), label);
133 gtk_window_set_title(GTK_WINDOW (window), "Welcome to GNOME");
134 gtk_window_set_default_size(GTK_WINDOW (window), 400, 200);
135 gtk_widget_show_all(window);
136 } // end of function activate
137
138 //
139 // main is where all program execution starts
140 //
141 int main(int argc, char **argv)
142 {
143 GtkApplication *app;
144 int status;
145
146 #if GLIB_CHECK_VERSION(2, 74, 0)
147 app = gtk_application_new(NULL, G_APPLICATION_DEFAULT_FLAGS);
148 #else
149 app = gtk_application_new(NULL, G_APPLICATION_FLAGS_NONE);
150 #endif
151 g_signal_connect(app, "activate", G_CALLBACK(activate), NULL);
152 status = g_application_run(G_APPLICATION(app), argc, argv);
153 g_object_unref(app);
154
155 return status;
156 } // end of function main
157 ```
158
159 Then we edit the Meson file, instructing it to find and use the GTK+
160 libraries.
161
162 ```meson
163 project('tutorial', 'c')
164 gtkdep = dependency('gtk+-3.0')
165 executable('demo', 'main.c', dependencies : gtkdep)
166 ```
167
168 If your app needs to use multiple libraries, you need to use separate
169 [[dependency]] calls for each, like so:
170
171 ```meson
172 gtkdeps = [dependency('gtk+-3.0'), dependency('gtksourceview-3.0')]
173 ```
174
175 We don't need it for the current example.
176
177 Now we are ready to build. The thing to notice is that we do *not*
178 need to recreate our build directory, run any sort of magical commands
179 or the like. Instead we just type the exact same command as if we were
180 rebuilding our code without any build system changes.
181
182 ```console
183 $ meson compile
184 ```
185
186 Once you have set up your build directory the first time, you don't
187 ever need to run the `meson` command again. You always just run `meson
188 compile`. Meson will automatically detect when you have done changes
189 to build definitions and will take care of everything so users don't
190 have to care. In this case the following output is produced.
191
192 [1/1] Regenerating build files
193 The Meson build system
194 version: 0.13.0-research
195 Source dir: /home/jpakkane/mesontutorial
196 Build dir: /home/jpakkane/mesontutorial/builddir
197 Build type: native build
198 Project name is "tutorial".
199 Using native c compiler "ccache cc". (gcc 4.8.2)
200 Found pkg-config version 0.26.
201 Dependency gtk+-3.0 found: YES
202 Creating build target "demo" with 1 files.
203 [1/2] Compiling c object demo.dir/main.c.o
204 [2/2] Linking target demo
205
206 Note how Meson noticed that the build definition has changed and reran
207 itself automatically. The program is now ready to be run:
208
209 ```
210 $ ./demo
211 ```
212
213 This creates the following GUI application.
214
215 ![GTK+ sample application screenshot](images/gtksample.png)