]> git.tdb.fi Git - builder.git/blob - Readme.txt
Support gcc's -iquote feature
[builder.git] / Readme.txt
1 Builder
2 Copyright © 2006-2012 Mikkosoft Productions
3 Version 2.0 readme
4
5 -------------------------------------------------------------------------------
6
7 Contents
8
9 1. Description
10 2. Building Builder
11 3. Using Builder
12 4. Locating packages
13 5. Command line options
14 6. Virtual targets
15 7. Tarballs
16 8. Architectures and cross-compilation
17 9. Dependency analysis
18 10. Logging
19 11. Writing Build files
20 12. Contact information
21 13. License
22
23 -------------------------------------------------------------------------------
24
25 1. Description
26
27 Builder is a program for building other programs, similar to make, scons and
28 others.  Its main design goals are minimizing duplication of configuration
29 between packages and being as fast as possible.  Features include integrated
30 configuration, dependency resolution for C and C++ sources, multi-package
31 builds, cross-compilation and pkg-config integration.
32
33 -------------------------------------------------------------------------------
34
35 2. Building Builder
36
37 Builder is normally built using itself.  However, if you just downloaded the
38 source and don't yet have a Builder binary, how is that possible?  To resolve
39 this problem, there's a script called bootstrap.sh in the Builder main
40 directory.  Before running it, make sure you have the following libraries
41 available:
42
43 MSP libraries: core datafile
44
45 Others: sigc++-2.0
46
47 You should be able to get the MSP libraries from the same place you got
48 Builder itself from.  Since they are also normally built with Builder, the
49 script will need to have their sources available.  By default, it will look at
50 the parent directory of builder.  You can change this by setting the LIBPATH
51 evironment variable for the script.  If everything goes well, the script will
52 build a builder-stage1 binary and then proceed to build a normal version with
53 it.
54
55 -------------------------------------------------------------------------------
56
57 3. Using Builder
58
59 In the simplest and most common case, Builder is invoked in the package's root
60 directory without any arguments.  It will look for a file called Build and
61 load it.  An alternative file can be specified with the -f option.  The first
62 package loaded from this file is called the main package and will determine
63 what to build by default.
64
65 While loading the package, other packages may be pulled in through require
66 statements.  Refer to section 4 for how packages are located.  A package that
67 can't be found will cause the build to fail.  If the -x option was specified,
68 builder will only consider binary packages when looking for dependencies.
69
70 When building, the primary targets of each package are placed in the package's
71 root directory.  To build a subset of targets from the package, the desired
72 targets can be named on the command line.  Paths are interpreted relative to
73 Builder's working directory.  The analyzer can be useful in finding out what
74 targets are available; see section 9 for details.
75
76 To configure optional package features, arguments of the form key=value may be
77 given.  To obtain a list of available features, use the --help option in the
78 package directory.
79
80 Temporary files produced during the build are stored in a dedicated temporary
81 directory.  By default a directory named temp is created for each package, but
82 this can be changed with the --tempdir option.  Subdirectories are used to
83 separate files for different build types and architectures.
84
85 When multiple packages are involved in a build, Builder will need to install
86 files for other packages to use them.  By default these go in $HOME/local, but
87 this can be changed with the --prefix option.
88
89 -------------------------------------------------------------------------------
90
91 4. Locating packages
92
93 Most packages are not self-contained, but depend on other packages.  When such
94 dependencies are encountered, the packages need to be located.  This section
95 describes the various places Builder looks for them from.
96
97 First, Builder asks pkg-config if it knows the location of the source
98 directory of the package.  This is stored in the source variable in the .pc
99 file, and is automatically put there by Builder.  If the variable is found,
100 Builder further verifies that it refers to an existing directory which
101 contains a Build file, so that removed sources do not cause undue failures.
102
103 If pkg-config does not know about the source, Builder consults its own package
104 path.  Currently this is hardcoded to contain the main package's source
105 directory and its parent directory.  To be found this way, the directory
106 should be named the same as the package, optionally followed by a dash and a
107 version number (or really anything; the part after the last dash is ignored).
108
109 If the source can't be found at all, Builder will then turn to using a binary
110 package.  Builder's native packages are considered first.  They are normally
111 stored in <prefix>/share/builder with the extension bpk.  The base part of the
112 filename should be the as the package's name.
113
114 Finally, pkg-config is consulted for the build flags of the package in the
115 normal way.  The flags need to be translated to Builder's internal
116 representation, so if the package requires very unusual flags, it may not
117 work.
118
119 A package that can't be found after all these steps might as well not exist.
120
121 -------------------------------------------------------------------------------
122
123 5. Command line options
124
125 When both Builder and GNU make offer the same functionality, the command line
126 option to invoke it is the same as well.
127
128 -a, --analyze MODE
129   Perform dependency analysis.  See section 9 for details.
130
131 -b, --build
132   Perform a build.  This is the default action.  This option can be used to
133   build even of some other action is specified.
134
135 -c, --clean
136   Clean buildable targets.  Any dependencies are cleaned up as well.  Giving
137   this option twice cleans all packages.
138
139 -f, --file=FILE
140   Read build instructions from FILE.  The default is Build.
141
142 -h, --help
143   Display a summary of command line options as well as configuration for the
144   main package.
145
146 -j, --jobs NUM
147   Run up to NUM tasks in parallel.  It's not very useful to specify a number
148   far in excess of the amount of logical CPU cores in the system.
149
150 -l, --log LIST
151   Enable output from a comma-separated list of log channels.  This is mainly
152   useful for debugging Builder itself; for normal use the -v option is almost
153   always enough.  Refer to section 10 for the available log channels.
154
155 -n, --dry-run
156   Show what would be done without actually doing it.  This is useful in
157   combination with -W or -l to find out what Builder would do in different
158   situations.
159
160 -s, --silent
161   Don't print any messages other than errors.
162
163 -t, --build-type TYPE
164   Sets the build type.  The supported types are defined in the builderrc file.
165   The shipped configuration contains build types debug, optimized_debug,
166   release and static_release.
167
168 -v, --verbose
169   Print more information about what's going on.  This option may be specified
170   multiple times to enable progressively more output.  Internally it translates
171   to enabling predefined sets of log channels.
172
173 -x, --no-externals
174   Do not load external source packages.
175
176 -A, --conf-all
177   Apply configuration to all packages.  Normally, only the main package is
178   configured, but with this option all packages can be configured at once.
179
180 -B, --build-all
181   Build all targets, even if their dependencies haven't been modified.
182
183 -C, --chdir DIR
184   Change to DIR before doing anything else.  This is equivalent to doing cd DIR
185   before invoking builder.  It's of little practical value in a shell, but may
186   be useful in scripts to avoid cd commands.  All filenames on the command line
187   will be interpreted relative to this directory.
188
189 -P, --progress
190   Display progress while building.
191
192 -W, --what-if FILE
193   Pretend that FILE has changed.
194
195 --arch ARCH
196   Build for architecture ARCH.  If the architecture is not native, this will
197   result in cross-compilation.  See section 8 for details.
198
199 --conf-only
200   Stop after configuring packages.  This can be useful if you want to
201   configure a package being used in a multi-package build.
202
203 --full-paths
204   Output full paths in analysis.  Normally only target names are displayed.
205
206 --max-depth NUM
207   Show up to NUM levels in analysis.  Depths less than 3 are generally not very
208   useful.  The default is 4.
209
210 --prefix DIR
211   Install files to DIR.  The default is $HOME/local.
212
213 --tempdir DIR
214   Store temporary files in DIR.  If a relative path is specified, each package
215   will have its own temp directory.  The default is ./temp.
216
217 -------------------------------------------------------------------------------
218
219 6. Virtual targets
220
221 Builder provides virtual targets for certain tasks, as well as for internal
222 organization of the build graph.  They can appear on the command line along
223 with file-based targets.
224
225 world
226   Depends on everything that can be built.
227
228 default
229   Depends on the targets that are built by default.  If no targets are
230   specified on the command line, then this target will be built.
231
232 install
233   Depends on all installed files.  This also includes .pc files, which are
234   otherwise not normally built.
235
236 tarballs
237   Depends on source tarballs of all packages.
238
239 goals
240   Depends on all targets on the command line.  Trying to add this target to the
241   command line will cause Builder to abort due to a circular dependency.
242
243 -------------------------------------------------------------------------------
244
245 7. Tarballs
246
247 Since the source tree usually contains files that do not belong to a release
248 archive, be they version control metadata or temporary build files, Builder
249 provides a way to create a clean source tarball for a package.  It will
250 contain all non-buildable files belonging to the package, including its Build
251 file.
252
253 Source tarballs are named as <package>-<version>.tar.  Currently compression
254 is not supported.
255
256 -------------------------------------------------------------------------------
257
258 8. Architectures and cross-compilation
259
260 If the necessary compilers and other tools are available, Builder can cross-
261 compile binaries for other systems.  To activate cross-compilation, use the
262 --arch option.
263
264 An architecture specification consists of cpu type and model, bitness and
265 operating system.  The fields are separated by dashes and can appear in any
266 order.  A partial architecture specification can also be given; any missing
267 fields are filled in from the native architecture.  
268
269 The --arch option can also be used to build native binaries optimized for a
270 specific cpu model.  Simply specify the desired model as an architecture.  By
271 default, no cpu model is used, which will generally result in code that can be
272 executed by all cpus of the same type.
273
274 In cross-compile mode, the build results are stored in a directory named after
275 the architecture.  Similarly, the default prefix is $HOME/local/$ARCH.
276
277 -------------------------------------------------------------------------------
278
279 9. Dependency analysis
280
281 Builder can perform a dependency analysis in various ways.  This can provide
282 useful insight to the relations between targets.  It may also be helpful if
283 you suspect Builder isn't picking up all of your files.
284
285 The following analysis modes are available:
286
287 deps
288   Display most targets, but skip over those that have a predictable 1-to-1
289   relationship with their sources.  Currently this includes ObjectFiles and
290   InstalledFiles.
291
292 alldeps
293   Display all targets.
294
295 rebuild
296   Display all targets, but stop descending as soon as a target not in need of
297   rebuilding is encountered.
298
299 rdeps
300   Instead of displaying the dependencies of the targets on the command line,
301   display which targets depend on them.  This provides similar information as
302   builder -a rebuild -W target world, but displayed in a different way.
303
304 -------------------------------------------------------------------------------
305
306 10. Logging
307
308 Sometimes you need to figure out what Builder is doing, perhaps because it's
309 doing it wrong or you're just curious.  To this end, a number of logging
310 channels are provided.  To specify which channels to enable, use the -l
311 option.  Some channels are also turned on by the -v option; the default
312 verbosity level is 1.  The -s option disables all channels.
313
314 auxcommands
315   Prints commands that are not directly related to building targets, such as
316   pkg-config invocations.  Enabled at verbosity level 3.
317
318 cache
319   Displays cached values as they are loaded.  Generates a lot of spam.
320
321 commands
322   Prints commands used for building targets.  Internal commands will print
323   "<internal>".  Enabled at verbosity level 2.
324
325 configure
326   Shows conditionals encountered in package Build files and whether they
327   matched.
328
329 environment
330   Displays overall parameters used in the build.  Enabled at verbosity level 2.
331
332 files
333   Indicates files that are being read or written, as well as directory scans.
334   Enabled at verbosity level 3.
335
336 packagemgr
337   Shows what's being done to locate packages.
338
339 packages
340   Displays a list of active packages at startup, together with their target
341   counts if they are source packages.  Enabled at verbosity level 2.
342
343 rebuild
344   Shows why targets are being rebuilt.  Similar to -a rebuild.
345
346 summary
347   Displays a brief summary of what will be done.  Enabled by default.
348
349 tasks
350   Displays abstract descriptions of what is being done.  Enabled by default.
351
352 tools
353   Displays information related to tools, such as versions.
354
355 vfs
356   Shows what files are being looked for and where.  Generates a lot of spam.
357
358 -------------------------------------------------------------------------------
359
360 11. Writing Build files
361
362 Before going into details about Builder instruction files, it's beneficial to
363 understand the basic concepts used in Builder.  There are three kinds of major
364 entities: packages, components and targets.
365
366 Packages are distributable units of software.
367
368 Components make up the contents of a package.  They define the high-level
369 goals such as libraries and executables.
370
371 Targets are the individual files taking part in the build process.  They are
372 created automatically from components.
373
374 The canonical name for the instruction file is Build.  It is written in a
375 structured declarative language, with syntax somewhat resembling the C
376 language.  The basic unit is a statement, which consists of a keyword,
377 optional arguments and an optional block of sub-statements.  Each statement is
378 terminated with a semicolon.
379
380 Typically, the Build file for a project defines a single package:
381
382   package "mylib"
383   {
384     ...
385   };
386
387 Inside the package can be some informational statements:
388
389   version "0.1";
390   description "My awesome library";
391
392 Packages may also depend on other packages:
393
394   require "otherlib";
395
396 See section 4 for how packages are located.
397
398 To be useful, a package must define one or more components.  At present, there
399 are four types:
400 - program: Build an executable program
401 - library: Build a library (both shared and static)
402 - module: Build a module for a program
403 - tarball: Pack files up in a .tar file
404
405 Each of these statements takes the component name as an argument.  The final
406 target name is composed of the component name and a possible platform-specific
407 prefix and suffix.  For example, the statement:
408
409   library "mylib"
410   {
411     ...
412   };
413
414 Will create a file called libmylib.so on Linux and libmylib.dll on Windows.
415
416 Components must contain one or more source statements telling where sources
417 are found:
418
419   source "mylib.cpp";
420
421 Directories may be specified; each file inside the directory will be added to
422 the source list.  Subdirectories are not included.  The list is filtered
423 according to the component type and only applicable files are used.
424
425 If you want a component to be installed, you can state it:
426
427   install true;
428
429 The default is not to install any components.  The installation directory is
430 automatically determined from the component type.  Library components will also
431 install any headers which were used to build the library.
432
433 Components can have requirements, just like packages.  They can also use
434 library components from the same package:
435
436   use "mylib_common";
437
438 This can be useful in organizing code when multiple components in a package
439 share a common part.  If the used library is not specified to be installed,
440 it will be linked statically.  
441
442 Packages may want to offer optional features, for example to allow the user to
443 choose whether to use a particular external library:
444
445   feature "foolib"
446   {
447     description "Use foolib to perform magic";
448   };
449
450 Enabled features will automatically cause a macro to be defined when compiling
451 C or C++ code.  The macro consists of a WITH_ prefix followed by the feature
452 name in uppercase.  The above feature would define the macro WITH_FOOLIB.
453
454 To specify additional effects of a feature, such as required packages, a
455 conditional statement may be used:
456
457   if_feature "foolib"
458   {
459     ...
460   };
461
462 Any statements inside the conditional block are evaluated if the feature is
463 enabled.  This can be negated with a !.  Conditionals can appear at package and
464 component scopes and may contain anything that the enclosing statement can.
465
466 When making cross-platform software, it's often necessary to use different
467 libraries on different platforms.  Another kind of conditional can be used for
468 this:
469
470   if_arch "windows"
471   {
472     ...
473   };
474
475 See section 8 for more information on how to specify an architecture.  The
476 conditional block is evaluated if all parts in the condition match the target
477 architecture.
478
479 Sometimes a library doesn't support pkg-config and can't be pulled in through a
480 require statement.  This is commonly the case with system libraries.  The
481 build_info statement can be used for this:
482
483   build_info
484   {
485     library "gdi32";
486   };
487
488 In many cases these libraries are specific to that system, so it's best to wrap
489 them in an if_arch statement.
490
491 Another case for using build_info is if you want to keep your headers separate
492 from source files:
493
494   incpath "include";
495
496 Paths are interpreted relative to the package's root directory.  It is not
497 recommended to use absolute paths, as this can make your package difficult to
498 build for others.
499
500 To include additional files in the package's source tarball, such as
501 documentation, use the source_tarball statement.  It takes no argument, as the
502 name is generated internally, but otherwise it behaves as a tarball component.
503
504 For real-life examples, see the Build files in Builder itself or any of the
505 MSP libraries.
506
507 -------------------------------------------------------------------------------
508
509 12. Contact information
510
511 The latest releases can be found at http://www.tdb.fi/builder.shtml
512
513 Bug reports, feature requests etc. may be sent to tdb@tdb.fi
514
515 Read-only git access is available at git://git.tdb.fi/builder
516
517 -------------------------------------------------------------------------------
518
519 13. License
520
521 Builder is copyright © 2006-2012  Mikko Rasa, Mikkosoft Productions
522
523 This program is free software; you can redistribute it and/or modify
524 it under the terms of the GNU General Public License as published by
525 the Free Software Foundation; either version 2 of the License, or
526 (at your option) any later version.
527
528 This program is distributed in the hope that it will be useful,
529 but WITHOUT ANY WARRANTY; without even the implied warranty of
530 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
531 GNU General Public License for more details.
532
533 You should have received a copy of the GNU General Public License along
534 with this program; if not, write to the Free Software Foundation, Inc.,
535 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
536
537 Full license text can be found in License.txt.