-Builder
-Copyright © 2006-2008 Mikko Rasa, Mikkosoft Productions
-Version 0.1
+Builder 0.9 Readme
+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 and dependency resolution for C and C++ sources.
-* 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
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 the parent
directory of builder. 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.
+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 to build projects
+
+In the simplest and most common case, Builder is invoked in the package's root
+directory without any arguments. An arbitary working directory may be
+specified with -C, or an alternative Build file with -f.
+
+To build a subset of the targets known to the package, the desired targets can
+be named on the command line. Note that if -C is used, the targets will be
+interpreted relative to that directory, not the one where Builder is invoked
+from.
+
+To change package configuration, arguments of the form key=value may be given.
+By default they will only affect the current package, but with the -A switch,
+all active packages may be configured at once.
+
+By default, files will be installed in $HOME/local. If you are not happy with
+this, the --prefix switch may be used to use another directory. Note that
+files may be installed due to dependencies when building multiple packages at
+once even if you don't specify the install target.
+
+
+4. Using Builder in your project
+
+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 insturction 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 five 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 tarbal
+- includes: Install headers for a library
+
+Each of these statements takes the component name as an argument. The 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.
+For headers component, the name defines a subdirectory of the prefix include
+directory to install headers in.
+
+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. 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 specify so:
+
+ install true;
+
+The default is not to install any components. The installation directory is
+automatically determined from the component type.
+
+For a complete example, see Builder's own Build file.
+
+
+5. 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 SVN access is available at http://svn.tdb.fi/builder
+
+
+6. License
+
+Builder is copyright © 2006-2009 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.
-* Using Builder in your project
+Full license text can be found in License.txt.
-To use Builder, you need to create a Build file that tells what it should
-build. This file defines two main types of entities: packages and components.
-usually there is only one package definition in a Build file.
-The Build file uses a C-like structured language. It consists of statements
-and blocks. Statements are terminated with a semicolon (';'). Blocks are
-enclosed in braces ('{' and '}'). If a statement contains a block of
-substatements, the semicolon comes after the closing brace.
+7. Version history
-For a simple example, look at Builder's own Build file.
+0.9
+- First released version
projects / builder.git / blobdiff