2 Copyright © 2006-2022 Mikkosoft Productions
5 -------------------------------------------------------------------------------
13 5. Command line options
16 8. Architectures and cross-compilation
17 9. Dependency analysis
19 11. Writing Build files
20 12. Contact information
23 -------------------------------------------------------------------------------
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.
33 -------------------------------------------------------------------------------
37 Builder is normally built using itself. This creates a conundrum if you just
38 downloaded the source and don't yet have a Builder binary. To resolve the
39 problem, there's a script called bootstrap.sh in the Builder main directory.
40 Before running it, make sure you have the following libraries available:
42 MSP libraries: core crypto datafile
46 You should be able to get the MSP libraries from the same place you got
47 Builder itself from. Since they are also normally built with Builder, the
48 script will need to have their sources available. By default, it will look at
49 the parent directory of builder. You can change this with the --libpath
50 parameter for the script. If everything goes well, the script will build a
51 builder-stage1 binary and then proceed to build a normal version with it.
53 -------------------------------------------------------------------------------
57 In the simplest and most common case, Builder is invoked in the package's root
58 directory without any arguments. It will look for a file called Build and
59 load it. An alternative file can be specified with the -f option. The first
60 package loaded from this file is called the main package and will determine
61 what to build by default.
63 While loading the package, other packages may be pulled in through require
64 statements. Refer to section 4 for how packages are located. A package that
65 can't be found will cause the build to fail. If the -x option was specified,
66 builder will only consider binary packages when looking for dependencies.
68 When building, the primary targets of each package are placed in the package's
69 root directory. To build a subset of targets from the package, the desired
70 targets can be named on the command line. Paths are interpreted relative to
71 Builder's working directory. The analyzer can be useful in finding out what
72 targets are available; see section 9 for details.
74 To configure optional package features, arguments of the form key=value may be
75 given. To obtain a list of available features, use the --help option in the
78 Temporary files produced during the build are stored in a dedicated temporary
79 directory. By default a directory named temp is created for each package, but
80 this can be changed with the --tempdir option. Subdirectories are used to
81 separate files for different build types and architectures.
83 When multiple packages are involved in a build, Builder will need to install
84 files for other packages to use them. By default these go in $HOME/local, but
85 this can be changed with the --prefix option.
87 -------------------------------------------------------------------------------
91 Most packages are not self-contained, but depend on other packages. When such
92 dependencies are encountered, the packages need to be located. This section
93 describes the various places Builder looks for them from.
95 First, Builder asks pkg-config if it knows the location of the source
96 directory of the package. This is stored in the source variable in the .pc
97 file, and is automatically put there by Builder. If the variable is found,
98 Builder further verifies that it refers to an existing directory which
99 contains a Build file, so that removed sources do not cause undue failures.
101 If pkg-config does not know about the source, Builder consults its own package
102 path. Currently this is hardcoded to contain the main package's source
103 directory and its parent directory. To be found this way, the directory
104 should be named the same as the package, optionally followed by a dash and a
105 version number (or really anything; the part after the last dash is ignored).
107 If the source can't be found at all, Builder will then turn to using a binary
108 package. Builder's native packages are considered first. They are normally
109 stored in <prefix>/share/builder with the extension bpk. The base part of the
110 filename should be the as the package's name.
112 Finally, pkg-config is consulted for the build flags of the package in the
113 normal way. The flags need to be translated to Builder's internal
114 representation, so if the package requires very unusual flags, it may not
117 A package that can't be found after all these steps might as well not exist.
119 -------------------------------------------------------------------------------
121 5. Command line options
123 When both Builder and GNU make offer the same functionality, the command line
124 option to invoke it is the same as well.
127 Perform dependency analysis. See section 9 for details.
130 Perform a build. This is the default action. This option can be used to
131 build even of some other action is specified.
134 Clean buildable targets. Any dependencies are cleaned up as well. Giving
135 this option twice cleans all packages.
138 Read build instructions from FILE. The default is Build.
141 Display a summary of command line options as well as configuration for the
145 Run up to NUM tasks in parallel. It's not very useful to specify a number
146 far in excess of the amount of logical CPU cores in the system.
149 Enable output from a comma-separated list of log channels. This is mainly
150 useful for debugging Builder itself; for normal use the -v option is almost
151 always enough. Refer to section 10 for the available log channels.
154 Show what would be done without actually doing it. This is useful in
155 combination with -W or -l to find out what Builder would do in different
159 Don't print any messages other than errors.
161 -t, --build-type TYPE
162 Sets the build type. The supported types are defined in the builderrc file.
163 The shipped configuration contains build types debug, optimized_debug,
164 release and static_release.
167 Print more information about what's going on. This option may be specified
168 multiple times to enable progressively more output. Internally it translates
169 to enabling predefined sets of log channels.
172 Do not load external source packages.
175 Apply configuration to all packages. Normally, only the main package is
176 configured, but with this option all packages can be configured at once.
179 Build all targets, even if their dependencies haven't been modified.
182 Change to DIR before doing anything else. This is equivalent to doing cd DIR
183 before invoking builder. It's of little practical value in a shell, but may
184 be useful in scripts to avoid cd commands. All filenames on the command line
185 will be interpreted relative to this directory.
188 Display progress while building.
191 Pretend that FILE has changed.
194 Build for architecture ARCH. If the architecture is not native, this will
195 result in cross-compilation. See section 8 for details.
198 Stop after configuring packages. This can be useful if you want to
199 configure a package being used in a multi-package build.
202 Output full paths in analysis. Normally only target names are displayed.
205 Show up to NUM levels in analysis. Depths less than 3 are generally not very
206 useful. The default is 4.
209 Install files to DIR. The default is $HOME/local.
212 Store temporary files in DIR. If a relative path is specified, each package
213 will have its own temp directory. The default is ./temp.
215 -------------------------------------------------------------------------------
219 Builder provides virtual targets for certain tasks, as well as for internal
220 organization of the build graph. They can appear on the command line along
221 with file-based targets.
224 Depends on everything that can be built.
227 Depends on the targets that are built by default. If no targets are
228 specified on the command line, then this target will be built.
231 Depends on all installed files. This also includes .pc files, which are
232 otherwise not normally built.
235 Depends on source tarballs of all packages.
238 Depends on all targets on the command line. Trying to add this target to the
239 command line will cause Builder to abort due to a circular dependency.
241 -------------------------------------------------------------------------------
245 Since the source tree usually contains files that do not belong to a release
246 archive, be they version control metadata or temporary build files, Builder
247 provides a way to create a clean source tarball for a package. It will
248 contain all non-buildable files belonging to the package, including its Build
251 Source tarballs are named as <package>-<version>.tar. Currently compression
254 -------------------------------------------------------------------------------
256 8. Architectures and cross-compilation
258 If the necessary compilers and other tools are available, Builder can cross-
259 compile binaries for other systems. To activate cross-compilation, use the
262 An architecture specification consists of cpu type and model, bitness and
263 operating system. The fields are separated by dashes and can appear in any
264 order. A partial architecture specification can also be given; any missing
265 fields are filled in from the native architecture.
267 The --arch option can also be used to build native binaries optimized for a
268 specific cpu model. Simply specify the desired model as an architecture. By
269 default, no cpu model is used, which will generally result in code that can be
270 executed by all cpus of the same type.
272 In cross-compile mode, the build results are stored in a directory named after
273 the architecture. Similarly, the default prefix is $HOME/local/$ARCH.
275 -------------------------------------------------------------------------------
277 9. Dependency analysis
279 Builder can perform a dependency analysis in various ways. This can provide
280 useful insight to the relations between targets. It may also be helpful if
281 you suspect Builder isn't picking up all of your files.
283 The following analysis modes are available:
286 Display most targets, but skip over those that have a predictable 1-to-1
287 relationship with their sources. Currently this includes ObjectFiles and
294 Display all targets, but stop descending as soon as a target not in need of
295 rebuilding is encountered.
298 Instead of displaying the dependencies of the targets on the command line,
299 display which targets depend on them. This provides similar information as
300 builder -a rebuild -W target world, but displayed in a different way.
302 -------------------------------------------------------------------------------
306 Sometimes you need to figure out what Builder is doing, perhaps because it's
307 doing it wrong or you're just curious. To this end, a number of logging
308 channels are provided. To specify which channels to enable, use the -l
309 option. Some channels are also turned on by the -v option; the default
310 verbosity level is 1. The -s option disables all channels.
313 Prints commands that are not directly related to building targets, such as
314 pkg-config invocations. Enabled at verbosity level 3.
317 Displays cached values as they are loaded. Generates a lot of spam.
320 Prints commands used for building targets. Internal commands will print
321 "<internal>". Enabled at verbosity level 2.
324 Shows conditionals encountered in package Build files and whether they
328 Displays overall parameters used in the build. Enabled at verbosity level 2.
331 Indicates files that are being read or written, as well as directory scans.
332 Enabled at verbosity level 3.
335 Shows what's being done to locate packages.
338 Displays a list of active packages at startup, together with their target
339 counts if they are source packages. Enabled at verbosity level 2.
342 Shows why targets are being rebuilt. Similar to -a rebuild.
345 Displays a brief summary of what will be done. Enabled by default.
348 Displays abstract descriptions of what is being done. Enabled by default.
351 Displays information related to tools, such as versions.
354 Shows what files are being looked for and where. Generates a lot of spam.
356 -------------------------------------------------------------------------------
358 11. Writing Build files
360 Before going into details about Builder instruction files, it's beneficial to
361 understand the basic concepts used in Builder. There are three kinds of major
362 entities: packages, components and targets.
364 Packages are distributable units of software.
366 Components make up the contents of a package. They define the high-level
367 goals such as libraries and executables.
369 Targets are the individual files taking part in the build process. They are
370 created automatically from components.
372 The canonical name for the instruction file is Build. It is written in a
373 structured declarative language, with syntax somewhat resembling the C
374 language. The basic unit is a statement, which consists of a keyword,
375 optional arguments and an optional block of sub-statements. Each statement is
376 terminated with a semicolon.
378 Typically, the Build file for a project defines a single package:
385 Inside the package can be some informational statements:
388 description "My awesome library";
390 Packages may also depend on other packages:
394 See section 4 for how packages are located.
396 To be useful, a package must define one or more components. At present, there
398 - program: Build an executable program
399 - library: Build a library (both shared and static)
400 - module: Build a module for a program
401 - tarball: Pack files up in a .tar file
403 Each of these statements takes the component name as an argument. The final
404 target name is composed of the component name and a possible platform-specific
405 prefix and suffix. For example, the statement:
412 Will create a file called libmylib.so on Linux and libmylib.dll on Windows.
414 Components must contain one or more source statements telling where sources
419 Directories may be specified; each file inside the directory will be added to
420 the source list. Subdirectories are not included. The list is filtered
421 according to the component type and only applicable files are used.
423 If you want a component to be installed, you can state it:
427 The default is not to install any components. The installation directory is
428 automatically determined from the component type. Library components will also
429 install any headers which were used to build the library.
431 Components can have requirements, just like packages. They can also use
432 library components from the same package:
436 This can be useful in organizing code when multiple components in a package
437 share a common part. If the used library is not specified to be installed,
438 it will be linked statically.
440 Packages may want to offer optional features, for example to allow the user to
441 choose whether to use a particular external library:
445 description "Use foolib to perform magic";
448 Enabled features will automatically cause a macro to be defined when compiling
449 C or C++ code. The macro consists of a WITH_ prefix followed by the feature
450 name in uppercase. The above feature would define the macro WITH_FOOLIB.
452 To specify additional effects of a feature, such as required packages, a
453 conditional statement may be used:
460 Any statements inside the conditional block are evaluated if the feature is
461 enabled. This can be negated with a !. Conditionals can appear at package and
462 component scopes and may contain anything that the enclosing statement can.
464 When making cross-platform software, it's often necessary to use different
465 libraries on different platforms. Another kind of conditional can be used for
473 See section 8 for more information on how to specify an architecture. The
474 conditional block is evaluated if all parts in the condition match the target
477 Sometimes a library doesn't support pkg-config and can't be pulled in through a
478 require statement. This is commonly the case with system libraries. The
479 build_info statement can be used for this:
486 In many cases these libraries are specific to that system, so it's best to wrap
487 them in an if_arch statement.
489 Another case for using build_info is if you want to keep your headers separate
494 Paths are interpreted relative to the package's root directory. It is not
495 recommended to use absolute paths, as this can make your package difficult to
498 To include additional files in the package's source tarball, such as
499 documentation, use the source_tarball statement. It takes no argument, as the
500 name is generated internally, but otherwise it behaves as a tarball component.
502 For real-life examples, see the Build files in Builder itself or any of the
505 -------------------------------------------------------------------------------
507 12. Contact information
509 The latest releases can be found at http://www.tdb.fi/builder.shtml
511 Bug reports, feature requests etc. may be sent to tdb@tdb.fi
513 Read-only git access is available at git://git.tdb.fi/builder
515 -------------------------------------------------------------------------------
519 Builder is copyright © 2006-2022 Mikko Rasa, Mikkosoft Productions
521 This program is free software; you can redistribute it and/or modify
522 it under the terms of the GNU General Public License as published by
523 the Free Software Foundation; either version 2 of the License, or
524 (at your option) any later version.
526 This program is distributed in the hope that it will be useful,
527 but WITHOUT ANY WARRANTY; without even the implied warranty of
528 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
529 GNU General Public License for more details.
531 You should have received a copy of the GNU General Public License along
532 with this program; if not, write to the Free Software Foundation, Inc.,
533 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
535 Full license text can be found in License.txt.