2 Copyright © 2006-2012 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. 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
43 MSP libraries: core datafile
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
55 -------------------------------------------------------------------------------
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.
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.
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.
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
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.
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.
89 -------------------------------------------------------------------------------
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.
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.
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).
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.
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
119 A package that can't be found after all these steps might as well not exist.
121 -------------------------------------------------------------------------------
123 5. Command line options
125 When both Builder and GNU make offer the same functionality, the command line
126 option to invoke it is the same as well.
129 Perform dependency analysis. See section 9 for details.
132 Perform a build. This is the default action. This option can be used to
133 build even of some other action is specified.
136 Clean buildable targets. Any dependencies are cleaned up as well. Giving
137 this option twice cleans all packages.
140 Read build instructions from FILE. The default is Build.
143 Display a summary of command line options as well as configuration for the
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.
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.
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
161 Don't print any messages other than errors.
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.
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.
174 Do not load external source packages.
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.
181 Build all targets, even if their dependencies haven't been modified.
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.
190 Display progress while building.
193 Pretend that FILE has changed.
196 Build for architecture ARCH. If the architecture is not native, this will
197 result in cross-compilation. See section 8 for details.
200 Stop after configuring packages. This can be useful if you want to
201 configure a package being used in a multi-package build.
204 Output full paths in analysis. Normally only target names are displayed.
207 Show up to NUM levels in analysis. Depths less than 3 are generally not very
208 useful. The default is 4.
211 Install files to DIR. The default is $HOME/local.
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.
217 -------------------------------------------------------------------------------
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.
226 Depends on everything that can be built.
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.
233 Depends on all installed files. This also includes .pc files, which are
234 otherwise not normally built.
237 Depends on source tarballs of all packages.
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.
243 -------------------------------------------------------------------------------
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
253 Source tarballs are named as <package>-<version>.tar. Currently compression
256 -------------------------------------------------------------------------------
258 8. Architectures and cross-compilation
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
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.
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.
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.
277 -------------------------------------------------------------------------------
279 9. Dependency analysis
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.
285 The following analysis modes are available:
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
296 Display all targets, but stop descending as soon as a target not in need of
297 rebuilding is encountered.
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.
304 -------------------------------------------------------------------------------
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.
315 Prints commands that are not directly related to building targets, such as
316 pkg-config invocations. Enabled at verbosity level 3.
319 Displays cached values as they are loaded. Generates a lot of spam.
322 Prints commands used for building targets. Internal commands will print
323 "<internal>". Enabled at verbosity level 2.
326 Shows conditionals encountered in package Build files and whether they
330 Displays overall parameters used in the build. Enabled at verbosity level 2.
333 Indicates files that are being read or written, as well as directory scans.
334 Enabled at verbosity level 3.
337 Shows what's being done to locate 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.
344 Shows why targets are being rebuilt. Similar to -a rebuild.
347 Displays a brief summary of what will be done. Enabled by default.
350 Displays abstract descriptions of what is being done. Enabled by default.
353 Displays information related to tools, such as versions.
356 Shows what files are being looked for and where. Generates a lot of spam.
358 -------------------------------------------------------------------------------
360 11. Writing Build files
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.
366 Packages are distributable units of software.
368 Components make up the contents of a package. They define the high-level
369 goals such as libraries and executables.
371 Targets are the individual files taking part in the build process. They are
372 created automatically from components.
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.
380 Typically, the Build file for a project defines a single package:
387 Inside the package can be some informational statements:
390 description "My awesome library";
392 Packages may also depend on other packages:
396 See section 4 for how packages are located.
398 To be useful, a package must define one or more components. At present, there
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
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:
414 Will create a file called libmylib.so on Linux and libmylib.dll on Windows.
416 Components must contain one or more source statements telling where sources
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.
425 If you want a component to be installed, you can state it:
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.
433 Components can have requirements, just like packages. They can also use
434 library components from the same package:
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.
442 Packages may want to offer optional features, for example to allow the user to
443 choose whether to use a particular external library:
447 description "Use foolib to perform magic";
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.
454 To specify additional effects of a feature, such as required packages, a
455 conditional statement may be used:
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.
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
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
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:
488 In many cases these libraries are specific to that system, so it's best to wrap
489 them in an if_arch statement.
491 Another case for using build_info is if you want to keep your headers separate
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
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.
504 For real-life examples, see the Build files in Builder itself or any of the
507 -------------------------------------------------------------------------------
509 12. Contact information
511 The latest releases can be found at http://www.tdb.fi/builder.shtml
513 Bug reports, feature requests etc. may be sent to tdb@tdb.fi
515 Read-only git access is available at git://git.tdb.fi/builder
517 -------------------------------------------------------------------------------
521 Builder is copyright © 2006-2012 Mikko Rasa, Mikkosoft Productions
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.
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.
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.
537 Full license text can be found in License.txt.
projects / builder.git / blob