Builder
-Copyright © 2006 Mikko Rasa, Mikkosoft Productions
-Version 0.1
+Copyright © 2006-2009 Mikkosoft Productions
+Version 1.0 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
directory. Before running it, make sure you have the following libraries
available:
-MSP libraries: misc core parser path regex++ getopt++
+MSP libraries: core datafile fs strings io
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 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.
+
+Full license text can be found in License.txt.
+
+
+7. Version history
+
+0.9
+- First released version
projects / builder.git / blobdiff