]> git.tdb.fi Git - builder.git/blob - Readme.txt
Make mingw linker happy
[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. Command line options
13 5. Architectures and cross-compilation
14 6. Dependency analysis
15 7. Writing Build files
16 8. Contact information
17 9. License
18
19 -------------------------------------------------------------------------------
20
21 1. Description
22
23 Builder is a program for building other programs, similar to make, scons and
24 others.  Its main design goals are minimizing duplication of configuration
25 between packages and being as fast as possible.  Features include integrated
26 configuration, dependency resolution for C and C++ sources, multi-package
27 builds, cross-compilation and pkg-config integration.
28
29 -------------------------------------------------------------------------------
30
31 2. Building Builder
32
33 Builder is normally built using itself.  However, if you just downloaded the
34 source and don't yet have a Builder binary, how is that possible?  To resolve
35 this problem, there's a script called bootstrap.sh in the Builder main
36 directory.  Before running it, make sure you have the following libraries
37 available:
38
39 MSP libraries: core datafile
40
41 Others: sigc++-2.0
42
43 Since the MSP libraries are also normally built with Builder, the script will
44 need to have their sources available.  By default, it will look at the parent
45 directory of builder.  You can change this by setting the LIBPATH evironment
46 variable for the script.  If everything goes well, the script will build a
47 builder-stage1 binary and then proceed to build a normal version with it.
48
49 -------------------------------------------------------------------------------
50
51 3. Using Builder
52
53 In the simplest and most common case, Builder is invoked in the package's root
54 directory without any arguments.  It will look for a file called Build and
55 load it.  An alternative file can be specified with the -f option.  The first
56 package loaded from this file is called the main package and will determine
57 what to build by default.
58
59 While loading the package, other packages may be pulled in through require
60 statements.  Builder tries to locate the source for each required package by
61 consulting pkg-config and looking through its package path.  If the source
62 can't be found, a binary package is tried next, from pkg-config and Builder's
63 internal package database.  If the package still can't be found, the build
64 will fail.  Loading external source packages can be disabled with the -x
65 option.
66
67 When building, the primary targets of each package are placed in the package's
68 root directory.  To build a subset of targets from the package, the desired
69 targets can be named on the command line.  Paths are interpreted relative to
70 Builder's working directory.  The analyzer can be useful in finding out what
71 targets are available; see section 6 for details.
72
73 To configure optional package features, arguments of the form key=value may be
74 given.  To obtain a list of available features, use the --help option in the
75 package directory.
76
77 Temporary files produced during the build are stored in a dedicated temporary
78 directory.  By default a directory named temp is created for each package, but
79 this can be changed with the --tempdir option.  Subdirectories are used to
80 separate files for different build types and architectures.
81
82 When multiple packages are involved in a build, Builder will need to install
83 files for other packages to use them.  By default these go in $HOME/local, but
84 this can be changed with the --prefix option.
85
86 -------------------------------------------------------------------------------
87
88 4. Command line options
89
90 When both Builder and GNU make offer the same functionality, the command line
91 option to invoke it is the same as well.
92
93 -a, --analyze MODE
94   Perform dependency analysis.  See section 6 for details.
95
96 -b, --build
97   Perform a build.  This is the default action.  This option can be used to
98   build even of some other action is specified.
99
100 -c, --clean
101   Clean buildable targets.  Any dependencies are cleaned up as well.  Giving
102   this option twice cleans all packages.
103
104 -f, --file=FILE
105   Read build instructions from FILE.  The default is Build.
106
107 -h, --help
108   Display a summary of command line options as well as configuration for the
109   main package.
110
111 -j, --jobs NUM
112   Run up to NUM tasks in parallel.  It's not very useful to specify a number
113   far in excess of the amount of logical CPU cores in the system.
114
115 -l, --log LIST
116   Enable output from a comma-separated list of log channels.
117
118 -n, --dry-run
119   Show what would be done without actually doing it.  This is useful in
120   combination with -W or -l to find out what Builder would do in different
121   situations.
122
123 -s, --silent
124   Don't print any messages other than errors.
125
126 -t, --build-type TYPE
127   Sets the build type.  The supported types are defined in the builderrc file.
128   The shipped configuration contains build types debug, optimized_debug,
129   release and static_release.
130
131 -v, --verbose
132   Print more information about what's going on.  This option may be specified
133   multiple times to enable progressively more output.  Internally it translates
134   to enabling predefined sets of log channels.
135
136 -x, --no-externals
137   Do not load external source packages.
138
139 -A, --conf-all
140   Apply configuration to all packages.  Normally, only the main package is
141   configured, but with this option all packages can be configured at once.
142
143 -B, --build-all
144   Build all targets, even if their dependencies haven't been modified.
145
146 -C, --chdir DIR
147   Change to DIR before doing anything else.  This is equivalent to doing cd DIR
148   before invoking builder.  It's of little practical value in a shell, but may
149   be useful in scripts to avoid cd commands.  All filenames on the command line
150   will be interpreted relative to this directory.
151
152 -P, --progress
153   Display progress while building.
154
155 -W, --what-if FILE
156   Pretend that FILE has changed.
157
158 --arch ARCH
159   Build for architecture ARCH.  If the architecture is not native, this will
160   result in cross-compilation.  See section 5 for details.
161
162 --conf-only
163   Stop after configuring packages.  This can be useful if you want to
164   configure a package being used in a multi-package build.
165
166 --full-paths
167   Output full paths in analysis.  Normally only target names are displayed.
168
169 --max-depth NUM
170   Show up to NUM levels in analysis.  Depths less than 3 are generally not very
171   useful.  The default is 4.
172
173 --prefix DIR
174   Install things to DIR.  The default is $HOME/local.
175
176 --tempdir DIR
177   Store temporary files in DIR.  If a relative path is specified, each package
178   will have its own temp directory.  The default is ./temp.
179
180 -------------------------------------------------------------------------------
181
182 5. Architectures and cross-compilation
183
184 If the necessary compilers and other tools are available, Builder can cross-
185 compile binaries for other systems.  To activate cross-compilation, use the
186 --arch option.
187
188 An architecture specification consists of cpu type and model, bitness and
189 operating system.  The fields are separated by dashes and can appear in any
190 order.  A partial architecture specification can also be given; any missing
191 fields are filled in from the native architecture.  
192
193 The --arch option can also be used to build native binaries optimized for a
194 specific cpu model.  Simply specify the desired model as an architecture.  By
195 default, no cpu model is used, which will generally result in code that can be
196 executed by all cpus of the same type.
197
198 In cross-compile mode, the build results are stored in a directory named after
199 the architecture.  Similarly, the default prefix is $HOME/local/$ARCH.
200
201 -------------------------------------------------------------------------------
202
203 6. Dependency analysis
204
205 Builder can perform a dependency analysis in various ways.  This can provide
206 useful insight to the relations between targets.  It may also be helpful if
207 you suspect Builder isn't picking up all of your files.
208
209 The following analysis modes are available:
210
211 deps
212   Display most targets, but skip over those that have a predictable 1-to-1
213   relationship with their sources.  Currently this includes ObjectFiles and
214   InstalledFiles.
215
216 alldeps
217   Display all targets.
218
219 rebuild
220   Display all targets, but stop descending as soon as a target not in need of
221   rebuilding is encountered.
222
223 rdeps
224   Instead of displaying the dependencies of the targets on the command line,
225   display which targets depend on them.  This provides similar information as
226   builder -a rebuild -W target world, but displayed in a different way.
227
228 -------------------------------------------------------------------------------
229
230 7. Writing Build files
231
232 Before going into details about Builder instruction files, it's beneficial to
233 understand the basic concepts used in Builder.  There are three kinds of major
234 entities: packages, components and targets.
235
236 Packages are distributable units of software.
237
238 Components make up the contents of a package.  They define the high-level
239 goals such as libraries and executables.
240
241 Targets are the individual files taking part in the build process.  They are
242 created automatically from components.
243
244 The canonical name for the instruction file is Build.  It is written in a
245 structured declarative language, with syntax somewhat resembling the C
246 language.  The basic unit is a statement, which consists of a keyword,
247 optional arguments and an optional block of sub-statements.  Each statement is
248 terminated with a semicolon.
249
250 Typically, the Build file for a project defines a single package:
251
252   package "mylib"
253   {
254     ...
255   };
256
257 Inside the package can be some informational statements:
258
259   version "0.1";
260   description "My awesome library";
261
262 Packages may also depend on other packages:
263
264   require "otherlib";
265
266 pkg-config is used to locate dependencies, and failing that, some heuristics
267 are applied to find Builder-enabled packages.
268
269 To be useful, a package must define one or more components.  At present, there
270 are four types:
271 - program: Build an executable program
272 - library: Build a library (both shared and static)
273 - module: Build a module for a program
274 - tarball: Pack files up in a .tar file
275
276 Each of these statements takes the component name as an argument.  The final
277 target name is composed of the component name and a possible platform-specific
278 prefix and suffix.  For example, the statement:
279
280   library "mylib"
281   {
282     ...
283   };
284
285 Will create a file called libmylib.so on Linux and libmylib.dll on Windows.
286
287 Components must contain one or more source statements telling where sources
288 are found:
289
290   source "mylib.cpp";
291
292 Directories may be specified; each file inside the directory will be added to
293 the source list.  Subdirectories are not included.  The list is filtered
294 according to the component type and only applicable files are used.
295
296 If you want a component to be installed, you can state it:
297
298   install true;
299
300 The default is not to install any components.  The installation directory is
301 automatically determined from the component type.  Library components will also
302 install any headers which were used to build the library.
303
304 Packages may want to offer optional features, for example to allow the user to
305 choose whether to use a particular external library:
306
307   feature "foolib"
308   {
309     description "Use foolib to perform magic";
310   };
311
312 Enabled features will automatically cause a macro to be defined when compiling
313 C or C++ code.  The macro consists of a WITH_ prefix followed by the feature
314 name in uppercase.  The above feature would define the macro WITH_FOOLIB.
315
316 To specify additional effects of a feature, such as required packages, a
317 conditional statement may be used:
318
319   if_feature "foolib"
320   {
321     ...
322   };
323
324 Any statements inside the conditional block are evaluated if the feature is
325 enabled.  This can be negated with a !.  Conditionals can appear at the package
326 level and may contain anything that the package statement can.
327
328 When making cross-platform software, it's often necessary to use different
329 libraries on different platforms.  Another kind of conditional can be used for
330 this:
331
332   if_arch "windows"
333   {
334     ...
335   };
336
337 See section 5 for more information on how to specify an architecture.  The
338 conditional block is evaluated if all parts in the condition match the target
339 architecture.
340
341 Sometimes a library doesn't support pkg-config and can't be pulled in through a
342 require statement.  This is commonly the case with system libraries.  The
343 build_info statement can be used for this:
344
345   build_info
346   {
347     library "gdi32";
348   };
349
350 In many cases these libraries are specific to that system, so it's best to wrap
351 them in an if_arch statement.
352
353 Another case for using build_info is if you want to keep your headers separate
354 from source files:
355
356   incpath "include";
357
358 Paths are interpreted relative to the package's root directory.  It is not
359 recommended to use absolute paths, as this can make your package difficult to
360 build for others.
361
362 For real-life examples, see the Build files in Builder itself or any of the
363 MSP libraries.
364
365 -------------------------------------------------------------------------------
366
367 8. Contact information
368
369 The latest releases can be found at http://www.tdb.fi/builder.shtml
370
371 Bug reports, feature requests etc. may be sent to tdb@tdb.fi
372
373 Read-only git access is available at http://git.tdb.fi/builder
374
375 -------------------------------------------------------------------------------
376
377 9. License
378
379 Builder is copyright © 2006-2012  Mikko Rasa, Mikkosoft Productions
380
381 This program is free software; you can redistribute it and/or modify
382 it under the terms of the GNU General Public License as published by
383 the Free Software Foundation; either version 2 of the License, or
384 (at your option) any later version.
385
386 This program is distributed in the hope that it will be useful,
387 but WITHOUT ANY WARRANTY; without even the implied warranty of
388 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
389 GNU General Public License for more details.
390
391 You should have received a copy of the GNU General Public License along
392 with this program; if not, write to the Free Software Foundation, Inc.,
393 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
394
395 Full license text can be found in License.txt.
396
397
398 7. Version history
399
400 0.9
401 - First released version