Debian Codegraph @

subprojects/meson-docs/docs/markdown/Generating-sources.md

raw
1 ---
2 short-description: Generation of source files before compilation
3 ...
4
5 # Generating sources
6
7 Sometimes source files need to be preprocessed before they are passed
8 to the actual compiler. As an example you might want build an IDL
9 compiler and then run some files through that to generate actual
10 source files. In Meson this is done with
11 [[generator]] or
12 [[custom_target]].
13
14 ## Using custom_target()
15
16 Let's say you have a build target that must be built using sources
17 generated by a compiler. The compiler can either be a built target:
18
19 ```meson
20 mycomp = executable('mycompiler', 'compiler.c')
21 ```
22
23 Or an external program provided by the system, or script inside the
24 source tree:
25
26 ```meson
27 mycomp = find_program('mycompiler')
28 ```
29
30 Custom targets can take zero or more input files and use them to
31 generate one or more output files. Using a custom target, you can run
32 this compiler at build time to generate the sources:
33
34 ```meson
35 gen_src = custom_target('gen-output',
36 input : ['somefile1.c', 'file2.c'],
37 output : ['out.c', 'out.h'],
38 command : [mycomp, '@INPUT@',
39 '--c-out', '@OUTPUT0@',
40 '--h-out', '@OUTPUT1@'])
41 ```
42
43 The `@INPUT@` there will be transformed to `'somefile1.c'
44 'file2.c'`. Just like the output, you can also refer to each input
45 file individually by index.
46
47 Then you just put that in your program and you're done.
48
49 ### Generating headers
50
51 Adding a generated header to a source list will ensure that the header
52 is generated and that the proper include paths are created for the
53 target:
54
55 ```meson
56 prog_python = [[#find_program]]('python3')
57
58 foo_c = custom_target(
59 'foo.c',
60 output : 'foo.c',
61 input : 'my_gen.py',
62 command : [prog_python, '@INPUT@', '--code', '@OUTPUT@'],
63 )
64
65 foo_h = custom_target(
66 'foo.h',
67 output : 'foo.h',
68 input : 'my_gen.py',
69 command : [prog_python, '@INPUT@', '--header', '@OUTPUT@'],
70 )
71
72 libfoo = static_library('foo', [foo_c, foo_h])
73
74 executable('myexe', ['main.c', foo_h], link_with : libfoo)
75 ```
76
77 Each target that depends on a generated header should add that header
78 to its sources, as seen above with `libfoo` and `myexe`. This is
79 because there is no way for Meson or the backend to know that `myexe`
80 depends on `foo.h` just because `libfoo` does, it could be a private
81 header.
82
83 ### Generating multiple files at a time
84
85 Sometimes it makes sense for a single generator to create two or more
86 files at a time, (perhaps a header and source file), Meson has this
87 case covered as well. `custom_target`s can be indexed like a list to
88 get each output file separately. The order is the same as the order of
89 the output argument to `custom_target`
90
91 ```meson
92 prog_python = [[#find_program]]('python3')
93
94 foo_ch = custom_target(
95 'foo.[ch]',
96 output : ['foo.c', 'foo.h'],
97 input : 'my_gen.py',
98 command : [prog_python, '@INPUT@', '@OUTPUT@'],
99 )
100
101 libfoo = static_library('foo', [foo_ch])
102
103 executable('myexe', ['main.c', foo_ch[1]], link_with : libfoo)
104 ```
105
106 In this case `libfoo` depends on both `foo.c` and `foo.h` but `myexe`
107 only depends on `foo.h`, the second output.
108
109 ### Using dependencies to manage generated resources
110
111 In some cases it might be easier to use `declare_dependency` to
112 "bundle" the header and library dependency, especially if there are
113 many generated headers:
114
115 ```meson
116 idep_foo = declare_dependency(
117 sources : [foo_h, bar_h],
118 link_with : [libfoo],
119 )
120 ```
121
122 See [dependencies](Dependencies.md#declaring-your-own), and
123 [[declare_dependency]] for more
124 information.
125
126 ## Using generator()
127
128 Generators are similar to custom targets, except that we define a
129 *generator*, which defines how to transform an input file into one or
130 more output files, and then use that on as many input files as we
131 want.
132
133 Note that generators should only be used for outputs that will only be
134 used as inputs for a build target or a custom target. When you use the
135 processed output of a generator in multiple targets, the generator
136 will be run multiple times to create outputs for each target. Each
137 output will be created in a target-private directory `@BUILD_DIR@`.
138
139 If you want to generate files for general purposes such as for
140 generating headers to be used by several sources, or data that will be
141 installed, and so on, use a
142 [[custom_target]] instead.
143
144
145 ```meson
146 gen = generator(mycomp,
147 output : '@[email protected]',
148 arguments : ['@INPUT@', '@OUTPUT@'])
149 ```
150
151 The first argument is the executable file to run. The next file
152 specifies a name generation rule. It specifies how to build the output
153 file name for a given input name. `@BASENAME@` is a placeholder for
154 the input file name without preceding path or suffix (if any). So if
155 the input file name were `some/path/filename.idl`, then the output
156 name would be `filename.c`. You can also use `@PLAINNAME@`, which
157 preserves the suffix which would result in a file called
158 `filename.idl.c`. The last line specifies the command line arguments
159 to pass to the executable. `@INPUT@` and `@OUTPUT@` are placeholders
160 for the input and output files, respectively, and will be
161 automatically filled in by Meson. If your rule produces multiple
162 output files and you need to pass them to the command line, append the
163 location to the output holder like this: `@OUTPUT0@`, `@OUTPUT1@` and
164 so on.
165
166 With this rule specified we can generate source files and add them to
167 a target.
168
169 ```meson
170 gen_src = gen.process('input1.idl', 'input2.idl')
171 executable('program', 'main.c', gen_src)
172 ```
173
174 Generators can also generate multiple output files with unknown names:
175
176 ```meson
177 gen2 = generator(someprog,
178 output : ['@[email protected]', '@[email protected]'],
179 arguments : ['--out_dir=@BUILD_DIR@', '@INPUT@'])
180 ```
181
182 In this case you cannot use the plain `@OUTPUT@` variable, as it
183 would be ambiguous. This program only needs to know the output
184 directory, it will generate the file names by itself.
185
186 To make passing different additional arguments to the generator
187 program at each use possible, you can use the `@EXTRA_ARGS@` string in
188 the `arguments` list. Note that this placeholder can only be present
189 as a whole string, and not as a substring. The main reason is that it
190 represents a list of strings, which may be empty, or contain multiple
191 elements; and in either case, interpolating it into the middle of a
192 single string would be troublesome. If there are no extra arguments
193 passed in from a `process()` invocation, the placeholder is entirely
194 omitted from the actual list of arguments, so an empty string won't be
195 passed to the generator program because of this. If there are multiple
196 elements in `extra_args`, they are inserted into to the actual
197 argument list as separate elements.
198
199 ```meson
200 gen3 = generator(genprog,
201 output : '@[email protected]',
202 arguments : ['@INPUT@', '@EXTRA_ARGS@', '@OUTPUT@'])
203 gen3_src1 = gen3.process('input1.y')
204 gen3_src2 = gen3.process('input2.y', extra_args: '--foo')
205 gen3_src3 = gen3.process('input3.y', extra_args: ['--foo', '--bar'])
206 ```