X-Git-Url: http://git.tdb.fi/?a=blobdiff_plain;f=Readme.txt;h=3a26dcc93b40f16e68c2771f3cb5d1d964334434;hb=402a19ee62dc2d3465b48fc518bdae265fc3e090;hp=c0004ad9ad4f866fd350acb8c860a4ab0059a1ab;hpb=0d80cabf649b931b26e7055385156c75a7385d35;p=builder.git diff --git a/Readme.txt b/Readme.txt index c0004ad..3a26dcc 100644 --- a/Readme.txt +++ b/Readme.txt @@ -1,14 +1,34 @@ Builder -Copyright © 2006 Mikko Rasa, Mikkosoft Productions -Version 0.1 +Copyright © 2006-2012 Mikkosoft Productions +Version 2.0 readme +------------------------------------------------------------------------------- + +Contents + +1. Description +2. Building Builder +3. Using Builder +4. Command line options +5. Architectures and cross-compilation +6. Dependency analysis +7. Writing Build files +8. Contact information +9. License + +------------------------------------------------------------------------------- + +1. Description Builder is a program for building other programs, similar to make, scons and -others. It is specifically designed to suit my needs, with the goal of -minimizing the amount of per-package configuration. +others. Its main design goals are minimizing duplication of configuration +between packages and being as fast as possible. Features include integrated +configuration, dependency resolution for C and C++ sources, multi-package +builds, cross-compilation and pkg-config integration. +------------------------------------------------------------------------------- -* Building Builder +2. Building Builder Builder is normally built using itself. However, if you just downloaded the source and don't yet have a Builder binary, how is that possible? To resolve @@ -16,12 +36,366 @@ this problem, there's a script called bootstrap.sh in the Builder main directory. Before running it, make sure you have the following libraries available: -MSP libraries: misc core parser path regex++ getopt++ +MSP libraries: core datafile Others: sigc++-2.0 Since the MSP libraries are also normally built with Builder, the script will -need to have their sources available. By default, it will look at ../libs. -You can change this by setting the LIBPATH evironment variable for the script. -If everything goes well, you should have a builder-stage1 binary that you can -use to build a normal version of Builder. +need to have their sources available. By default, it will look at the parent +directory of builder. You can change this by setting the LIBPATH evironment +variable for the script. If everything goes well, the script will build a +builder-stage1 binary and then proceed to build a normal version with it. + +------------------------------------------------------------------------------- + +3. Using Builder + +In the simplest and most common case, Builder is invoked in the package's root +directory without any arguments. It will look for a file called Build and +load it. An alternative file can be specified with the -f option. The first +package loaded from this file is called the main package and will determine +what to build by default. + +While loading the package, other packages may be pulled in through require +statements. Builder tries to locate the source for each required package by +consulting pkg-config and looking through its package path. If the source +can't be found, a binary package is tried next, from pkg-config and Builder's +internal package database. If the package still can't be found, the build +will fail. Loading external source packages can be disabled with the -x +option. + +When building, the primary targets of each package are placed in the package's +root directory. To build a subset of targets from the package, the desired +targets can be named on the command line. Paths are interpreted relative to +Builder's working directory. The analyzer can be useful in finding out what +targets are available; see section 6 for details. + +To configure optional package features, arguments of the form key=value may be +given. To obtain a list of available features, use the --help option in the +package directory. + +Temporary files produced during the build are stored in a dedicated temporary +directory. By default a directory named temp is created for each package, but +this can be changed with the --tempdir option. Subdirectories are used to +separate files for different build types and architectures. + +When multiple packages are involved in a build, Builder will need to install +files for other packages to use them. By default these go in $HOME/local, but +this can be changed with the --prefix option. + +------------------------------------------------------------------------------- + +4. Command line options + +When both Builder and GNU make offer the same functionality, the command line +option to invoke it is the same as well. + +-a, --analyze MODE + Perform dependency analysis. See section 6 for details. + +-b, --build + Perform a build. This is the default action. This option can be used to + build even of some other action is specified. + +-c, --clean + Clean buildable targets. Any dependencies are cleaned up as well. Giving + this option twice cleans all packages. + +-f, --file=FILE + Read build instructions from FILE. The default is Build. + +-h, --help + Display a summary of command line options as well as configuration for the + main package. + +-j, --jobs NUM + Run up to NUM tasks in parallel. It's not very useful to specify a number + far in excess of the amount of logical CPU cores in the system. + +-l, --log LIST + Enable output from a comma-separated list of log channels. + +-n, --dry-run + Show what would be done without actually doing it. This is useful in + combination with -W or -l to find out what Builder would do in different + situations. + +-s, --silent + Don't print any messages other than errors. + +-t, --build-type TYPE + Sets the build type. The supported types are defined in the builderrc file. + The shipped configuration contains build types debug, optimized_debug, + release and static_release. + +-v, --verbose + Print more information about what's going on. This option may be specified + multiple times to enable progressively more output. Internally it translates + to enabling predefined sets of log channels. + +-x, --no-externals + Do not load external source packages. + +-A, --conf-all + Apply configuration to all packages. Normally, only the main package is + configured, but with this option all packages can be configured at once. + +-B, --build-all + Build all targets, even if their dependencies haven't been modified. + +-C, --chdir DIR + Change to DIR before doing anything else. This is equivalent to doing cd DIR + before invoking builder. It's of little practical value in a shell, but may + be useful in scripts to avoid cd commands. All filenames on the command line + will be interpreted relative to this directory. + +-P, --progress + Display progress while building. + +-W, --what-if FILE + Pretend that FILE has changed. + +--arch ARCH + Build for architecture ARCH. If the architecture is not native, this will + result in cross-compilation. See section 5 for details. + +--conf-only + Stop after configuring packages. This can be useful if you want to + configure a package being used in a multi-package build. + +--full-paths + Output full paths in analysis. Normally only target names are displayed. + +--max-depth NUM + Show up to NUM levels in analysis. Depths less than 3 are generally not very + useful. The default is 4. + +--prefix DIR + Install things to DIR. The default is $HOME/local. + +--tempdir DIR + Store temporary files in DIR. If a relative path is specified, each package + will have its own temp directory. The default is ./temp. + +------------------------------------------------------------------------------- + +5. Architectures and cross-compilation + +If the necessary compilers and other tools are available, Builder can cross- +compile binaries for other systems. To activate cross-compilation, use the +--arch option. + +An architecture specification consists of cpu type and model, bitness and +operating system. The fields are separated by dashes and can appear in any +order. A partial architecture specification can also be given; any missing +fields are filled in from the native architecture. + +The --arch option can also be used to build native binaries optimized for a +specific cpu model. Simply specify the desired model as an architecture. By +default, no cpu model is used, which will generally result in code that can be +executed by all cpus of the same type. + +In cross-compile mode, the build results are stored in a directory named after +the architecture. Similarly, the default prefix is $HOME/local/$ARCH. + +------------------------------------------------------------------------------- + +6. Dependency analysis + +Builder can perform a dependency analysis in various ways. This can provide +useful insight to the relations between targets. It may also be helpful if +you suspect Builder isn't picking up all of your files. + +The following analysis modes are available: + +deps + Display most targets, but skip over those that have a predictable 1-to-1 + relationship with their sources. Currently this includes ObjectFiles and + InstalledFiles. + +alldeps + Display all targets. + +rebuild + Display all targets, but stop descending as soon as a target not in need of + rebuilding is encountered. + +rdeps + Instead of displaying the dependencies of the targets on the command line, + display which targets depend on them. This provides similar information as + builder -a rebuild -W target world, but displayed in a different way. + +------------------------------------------------------------------------------- + +7. Writing Build files + +Before going into details about Builder instruction files, it's beneficial to +understand the basic concepts used in Builder. There are three kinds of major +entities: packages, components and targets. + +Packages are distributable units of software. + +Components make up the contents of a package. They define the high-level +goals such as libraries and executables. + +Targets are the individual files taking part in the build process. They are +created automatically from components. + +The canonical name for the instruction file is Build. It is written in a +structured declarative language, with syntax somewhat resembling the C +language. The basic unit is a statement, which consists of a keyword, +optional arguments and an optional block of sub-statements. Each statement is +terminated with a semicolon. + +Typically, the Build file for a project defines a single package: + + package "mylib" + { + ... + }; + +Inside the package can be some informational statements: + + version "0.1"; + description "My awesome library"; + +Packages may also depend on other packages: + + require "otherlib"; + +pkg-config is used to locate dependencies, and failing that, some heuristics +are applied to find Builder-enabled packages. + +To be useful, a package must define one or more components. At present, there +are four types: +- program: Build an executable program +- library: Build a library (both shared and static) +- module: Build a module for a program +- tarball: Pack files up in a .tar file + +Each of these statements takes the component name as an argument. The final +target name is composed of the component name and a possible platform-specific +prefix and suffix. For example, the statement: + + library "mylib" + { + ... + }; + +Will create a file called libmylib.so on Linux and libmylib.dll on Windows. + +Components must contain one or more source statements telling where sources +are found: + + source "mylib.cpp"; + +Directories may be specified; each file inside the directory will be added to +the source list. Subdirectories are not included. The list is filtered +according to the component type and only applicable files are used. + +If you want a component to be installed, you can state it: + + install true; + +The default is not to install any components. The installation directory is +automatically determined from the component type. Library components will also +install any headers which were used to build the library. + +Packages may want to offer optional features, for example to allow the user to +choose whether to use a particular external library: + + feature "foolib" + { + description "Use foolib to perform magic"; + }; + +Enabled features will automatically cause a macro to be defined when compiling +C or C++ code. The macro consists of a WITH_ prefix followed by the feature +name in uppercase. The above feature would define the macro WITH_FOOLIB. + +To specify additional effects of a feature, such as required packages, a +conditional statement may be used: + + if_feature "foolib" + { + ... + }; + +Any statements inside the conditional block are evaluated if the feature is +enabled. This can be negated with a !. Conditionals can appear at the package +level and may contain anything that the package statement can. + +When making cross-platform software, it's often necessary to use different +libraries on different platforms. Another kind of conditional can be used for +this: + + if_arch "windows" + { + ... + }; + +See section 5 for more information on how to specify an architecture. The +conditional block is evaluated if all parts in the condition match the target +architecture. + +Sometimes a library doesn't support pkg-config and can't be pulled in through a +require statement. This is commonly the case with system libraries. The +build_info statement can be used for this: + + build_info + { + library "gdi32"; + }; + +In many cases these libraries are specific to that system, so it's best to wrap +them in an if_arch statement. + +Another case for using build_info is if you want to keep your headers separate +from source files: + + incpath "include"; + +Paths are interpreted relative to the package's root directory. It is not +recommended to use absolute paths, as this can make your package difficult to +build for others. + +For real-life examples, see the Build files in Builder itself or any of the +MSP libraries. + +------------------------------------------------------------------------------- + +8. Contact information + +The latest releases can be found at http://www.tdb.fi/builder.shtml + +Bug reports, feature requests etc. may be sent to tdb@tdb.fi + +Read-only git access is available at http://git.tdb.fi/builder + +------------------------------------------------------------------------------- + +9. License + +Builder is copyright © 2006-2012 Mikko Rasa, Mikkosoft Productions + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Full license text can be found in License.txt. + + +7. Version history + +0.9 +- First released version