Debian Codegraph @

subprojects/meson-docs/docs/markdown/Style-guide.md

raw
1 ---
2 short-description: Style recommendations for Meson files
3 ...
4
5 # Style recommendations
6
7 This page lists some recommendations on organizing and formatting your
8 Meson build files.
9
10 ## Tabs or spaces?
11
12 Always spaces. Two spaces is the most common.
13
14 ## Trailing commas?
15
16 Yes, where possible. They help make nicer diffs in version control systems.
17
18 ## Naming Variable
19
20 Snake case (stylized as `snake_case`) refers to the style of writing in which
21 each space is replaced by an underscore (`_`) character, and the first letter of
22 each word written in lowercase. It is the most common naming convention used
23 in Meson build scripts as identifiers for variable.
24
25 Let say you would like to refer to your executable so something like `my_exe`.
26
27 ## Dependency usage
28
29 The `dependency` function is the recommended way to handle
30 dependencies. If your wrap files have the necessary `[provide]`
31 entries, everything will work automatically both when compiling your
32 own and when using system dependencies.
33
34 You should only need `subproject` when you need to extract non dependencies/programs.
35
36 ## Naming options
37
38 There are two ways of naming project options. As an example for
39 booleans the first one is `foo` and the second one is `enable-foo`.
40 The former style is recommended, because in Meson options have strong
41 type, rather than being just strings.
42
43 You should try to name options the same as is common in other
44 projects. This is especially important for yielding options, because
45 they require that both the parent and subproject options have the same
46 name.
47
48 # Global arguments
49
50 Prefer `add_project_arguments` to `add_global_arguments` because using
51 the latter prevents using the project as a subproject.
52
53 # Cross compilation arguments
54
55 Try to keep cross compilation arguments away from your build files as
56 much as possible. Keep them in the cross file instead. This adds
57 portability, since all changes needed to compile to a different
58 platform are isolated in one place.
59
60 # Sorting source paths
61
62 The source file arrays should all be sorted. This makes it easier to
63 spot errors and often reduces merge conflicts. Furthermore, the paths
64 should be sorted with a natural sorting algorithm, so that numbers are
65 sorted in an intuitive way (`1, 2, 3, 10, 20` instead of `1, 10, 2,
66 20, 3`).
67
68 Numbers should also be sorted before characters (`a111` before `ab0`).
69 Furthermore, strings should be sorted case insensitive.
70
71 Additionally, if a path contains a directory it should be sorted before
72 normal files. This rule also applies recursively for subdirectories.
73
74 The following example shows correct source list definition:
75
76 ```meson
77 sources = files(
78 'aaa/a1.c',
79 'aaa/a2.c',
80 'bbb/subdir1/b1.c',
81 'bbb/subdir2/b2.c',
82 'bbb/subdir10/b3.c',
83 'bbb/subdir20/b4.c',
84 'bbb/b5.c',
85 'bbb/b6.c',
86 'f1.c',
87 'f2.c',
88 'f10.c',
89 'f20.c',
90 )
91 ```