Readme.txt

   1 Builder
   2 Copyright © 2006-2009 Mikkosoft Productions
   3 Version 1.0 readme
   4
   5
   6 1. Description
   7
   8 Builder is a program for building other programs, similar to make, scons and
   9 others.  Its main design goals are minimizing duplication of configuration
  10 between packages and being as fast as possible.  Features include integrated
  11 configuration and dependency resolution for C and C++ sources.
  12
  13
  14 2. Building Builder
  15
  16 Builder is normally built using itself.  However, if you just downloaded the
  17 source and don't yet have a Builder binary, how is that possible?  To resolve
  18 this problem, there's a script called bootstrap.sh in the Builder main
  19 directory.  Before running it, make sure you have the following libraries
  20 available:
  21
  22 MSP libraries: core datafile fs strings io
  23
  24 Others: sigc++-2.0
  25
  26 Since the MSP libraries are also normally built with Builder, the script will
  27 need to have their sources available.  By default, it will look at the parent
  28 directory of builder.  You can change this by setting the LIBPATH evironment
  29 variable for the script.  If everything goes well, the script will build a
  30 builder-stage1 binary and then proceed to build a normal version with it.
  31
  32
  33 3. Using Builder to build projects
  34
  35 In the simplest and most common case, Builder is invoked in the package's root
  36 directory without any arguments.  An arbitary working directory may be
  37 specified with -C, or an alternative Build file with -f.
  38
  39 To build a subset of the targets known to the package, the desired targets can
  40 be named on the command line.  Note that if -C is used, the targets will be
  41 interpreted relative to that directory, not the one where Builder is invoked
  42 from.
  43
  44 To change package configuration, arguments of the form key=value may be given.
  45 By default they will only affect the current package, but with the -A switch,
  46 all active packages may be configured at once.
  47
  48 By default, files will be installed in $HOME/local.  If you are not happy with
  49 this, the --prefix switch may be used to use another directory.  Note that
  50 files may be installed due to dependencies when building multiple packages at
  51 once even if you don't specify the install target.
  52
  53
  54 4. Using Builder in your project
  55
  56 Before going into details about Builder instruction files, it's beneficial to
  57 understand the basic concepts used in Builder.  There are three kinds of major
  58 entities: packages, components and targets.
  59
  60 Packages are distributable units of software.
  61
  62 Components make up the contents of a package.  They define the high-level
  63 goals such as libraries and executables.
  64
  65 Targets are the individual files taking part in the build process.  They are
  66 created automatically from components.
  67
  68 The canonical name for the insturction file is Build.  It is written in a
  69 structured declarative language, with syntax somewhat resembling the C
  70 language.  The basic unit is a statement, which consists of a keyword,
  71 optional arguments and an optional block of sub-statements.  Each statement is
  72 terminated with a semicolon.
  73
  74 Typically, the Build file for a project defines a single package:
  75
  76   package "mylib"
  77   {
  78     ...
  79   };
  80
  81 Inside the package can be some informational statements:
  82
  83   version "0.1";
  84   description "My awesome library";
  85
  86 Packages may also depend on other packages:
  87
  88   require "otherlib";
  89
  90 pkg-config is used to locate dependencies, and failing that, some heuristics
  91 are applied to find Builder-enabled packages.
  92
  93 To be useful, a package must define one or more components.  At present, there
  94 are five types:
  95 - program: Build an executable program
  96 - library: Build a library (both shared and static)
  97 - module: Build a module for a program
  98 - tarball: Pack files up in a tarbal
  99 - includes: Install headers for a library
 100
 101 Each of these statements takes the component name as an argument.  The target
 102 name is composed of the component name and a possible platform-specific prefix
 103 and suffix.  For example, the statement:
 104
 105   library "mylib";
 106
 107 Will create a file called libmylib.so on Linux and libmylib.dll on Windows.
 108 For headers component, the name defines a subdirectory of the prefix include
 109 directory to install headers in.
 110
 111 Components must contain one or more source statements telling where sources
 112 are found:
 113
 114   source "mylib.cpp";
 115
 116 Directories may be specified; each file inside the directory will be added to
 117 the source list.  The list is filtered according to the component type and only
 118 applicable files are used.
 119
 120 If you want a component to be installed, you can specify so:
 121
 122   install true;
 123
 124 The default is not to install any components.  The installation directory is
 125 automatically determined from the component type.
 126
 127 For a complete example, see Builder's own Build file.
 128
 129
 130 5. Contact information
 131
 132 The latest releases can be found at http://www.tdb.fi/builder.shtml
 133
 134 Bug reports, feature requests etc. may be sent to tdb@tdb.fi
 135
 136 Read-only SVN access is available at http://svn.tdb.fi/builder
 137
 138
 139 6. License
 140
 141 Builder is copyright © 2006-2009  Mikko Rasa, Mikkosoft Productions
 142
 143 This program is free software; you can redistribute it and/or modify
 144 it under the terms of the GNU General Public License as published by
 145 the Free Software Foundation; either version 2 of the License, or
 146 (at your option) any later version.
 147
 148 This program is distributed in the hope that it will be useful,
 149 but WITHOUT ANY WARRANTY; without even the implied warranty of
 150 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 151 GNU General Public License for more details.
 152
 153 You should have received a copy of the GNU General Public License along
 154 with this program; if not, write to the Free Software Foundation, Inc.,
 155 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 156
 157 Full license text can be found in License.txt.
 158
 159
 160 7. Version history
 161
 162 0.9
 163 - First released version