INSTRUCTIONS

Identification
==============

Bob is a build tool intended primarily to facilitate the development of
large C/C++/D projects by:
* Being easy to use.
* Enforcing rules like dependency management.
* Supporting code generation.

This file provides an introduction into how to use bob. Refer to the example
directory for more digestible help.


Preparation
===========

Bob assumes that all the source code and external libraries/utilities you will
need are already present. It is up to you to make this happen.

Typically you will have:
* Source code in one or more repository clones or checkouts.
* A number of required third-party packages installed in the system.
* A number of required third-party packages or in-house packages installed
  in non-standard locations.


Configuration
=============

The bob-config utility establishes a build directory, from which bob can build
your project. bob-config requires a configuration file that defines a number of
variables - see example/bob.cfg for a fully documented example.

The configured variables ultimately specify:

* The commands used to build files.

* The external libraries used by the project and the imports/includes
  that indicate a need to link with those libraries.

The build directory you specify must be outside the source-code repositories,
avoiding pollution of your repositories with build artifacts, and allowing
multiple build directories to be using the same source checkout. For example,
your repository might be in ~/source/myproject, and you might have build
directories ~/builds/myproject/debug, ~/builds/myproject/profile,
~/builds/myproject/release.

The build directory has links back to the source.

A typical repository directory structure is:

repo-root
  assorted-uninteresting-files
  assorted-uninteresting-dirs
  source-root
    bob.cfg
    assorted-source-dirs

One of the source-dirs is specified in the PROJECT variable as containing
the top level Bobfile.

To configure a build directory from a repo that looks like the above:

cd repo-root/source-root
bob-config --mode=debug ~/builds/myproject/debug


The build directory contains:

environment - Sourced to set up environment variables.
run         - Script to run a project executable.
Boboptions  - Contains variables from config file.
src
  symlinks-to-source-dirs
obj
  dirs-matching-source-dir-tree
    intermediate-build-artifacts
tmp
  assorted temporary files
priv
  dirs-matching-source-dir-tree
    private-finished-build-artifacts
dist
  lib       - Contains public static libraries and all dynamic libraries.
  bin       - Contains executables and scripts.
  data      - Contains data files.
  include   - contains public include files for public static libraries.


Building
========

Bob is the build tool. It always builds the whole project, so there is no build
target to specify on the command-line. This isn't a problem because:
* Bob determines what needs to be done quickly.
* Bob's log output is very clean.
* Bob builds files (mostly) in definition order, and stops the build when an error
  occurs, so you quickly get back to the point of failure during development.
* Bob runs and evaluates unit tests (mostly) in definition order, so if you have
  unit tests, you quickly get to the point of failure during debugging.

The "mostly" above refers to the jitter in build order that occurs when building
with multiple cores.

The build process is controlled by Bobfiles. The top-level source directory
(specified in the config file) contains the top-level Bobfile, and it brings in
other directories with its statements.

Refer to the example's Bobfiles.

Bobfile syntax is:

# This line is a comment.
<statement-type> <param0> [: <param1> [: param2 [: param3]]];

where a parameter is a space-separated list of tokens.

Statements often refer to files and directories.
The rules for determining the paths referred to are:

* Source files are either src/trail/name or obj/trail/name, where
  trail in the sequence of directory names leading to the Bobfile,
  and name is the name specified in the Bobfile statement.

  Example: if a Bobfile in tools/hammer has a library that contains source
  file claw.h, it is looked for in src/tools/hammer/claw.h and
  obj/tools/hammer/claw.h. It is an error for the file to be in both
  locations.

* Directories can be "beneath" the current directory. For example, if a
  Bobfile in tools has a "contain claw;" statement, the trail of the contained
  directory is tools/hammer.

* Directories can also be specified from the root. For example,
  "handyman: may have a "refer tools;" statement to refer to top-level directory
  "tools".


Statement types are:

Contain
-------

contain subdir-names [: protected];

eg: contain math net stream tools;

Specifies that the listed subdirectories contain Bobfiles and are included in
the build. Visibility defaults to public. Contained directories must be
specified in dependency order.


Refer
-----

refer paths-from-source-root;

eg: refer framework alg/math;

Specifies that this directory has access to the listed directories.


Static Lib
----------

static-lib lib-name : public-source [: protected-source];
public-lib lib-name : public-source [: protected-source];

eg: static-lib math : matrix.h alg.h : matrix.cc alg.cc;

Specifies a static library. All the source files should be in the same language,
or in a language from which the library's language files can be generated.
Exceptions:
* .c files can mix with others.
* Files without configured build commands (eg header files) can mix with others.

The public files are those that client code can import/include.

public-lib is identical to static-lib except that:

* The public include files are copied into dist/include/<trail>

* If the library is not contained in a dynamic library, the library file is
  copied into dist/lib.


Dynamic Lib
-----------

dynamic-lib name : static-libs;

eg: dynamic-lib tools : tools;

Dynamic libs contain all the object files contained in the specified static libs.
Executables defined after a dynamic library will link to the dynamic library
rather than the static library.

The contained static-libs all have to be declared in the current Bobfile
or in a transitively contained directory's Bobfile.
The last path element can optionally be omitted if it is the same as the
containing directory name, which is usually the case.

For example, if the directory structure is:
  one - defines dynamic library "one"
    two - defines static library "two"
    three - defines static library "three"
then the statement in one's Bobfile to generate the dynamic library is:

dynamic-lib one : two three;

or, if you want to do it in full, which you must if the names don't match:

dynamic-lib one : two/two three/three;


Executable
----------

dist-exe exe-name : source;
test-exe exe-name : source;
util-exe exe-name : source;

eg: test-exe math-test : math_test.cpp;


dist-exe places the built executable in the dist/bin directory.

util-exe places the build executable in the priv/<trail> directory.

test-exe places the built executable in the priv/<trail> directory,
and executes the test when its result file is out of date.

The test is run with the TEST_PATH environment variable set to a path
that the test can use for scratch file I/O if necessary.


Scripts, data and docs
----------------------

misc names [: dist-destination-path]

Copies or (if there is a rule to generate files from the extension)
generates files that do not contribute to libraries or executables.
If any of names is a directory, it is recursed into.

For example:

# copy/build specified files into dist/bin
misc foo.sh foo2.sh : dist/bin;

# copy/build index.rst into priv/<chain> and files in doc dir and below
# into priv/<chain>/doc, preserving any subdirectory structure.
misc index.rst doc;


Dependencies
============

Discussion
----------

Dependencies are a major preoccupation of bob. This is because on large
projects, management of dependencies is essential, and the best way to manage
something is with a tool. If you can't build software without explicitly
declaring a dependency, you can't sneak a dependency in while no-one is looking.

Bob also goes further and insists on no circularities between files or directories.
This may seem like a harsh constraint, but it is a very useful design tool, and
in the experience of the writer, leads to better, more maintainable designs.


Rules
-----

Files and their owning directories are arranged in a tree with cross-linked
dependencies. Each node in the tree can be public or protected. The root of the
tree contains its children publicly.

The dependency rules are:

* A protected node can only be referred to by sibling nodes or nodes transitively
  contained by those siblings.

* Node (A) can only refer to another node (B) if A's parent transitively refers
  to or transitively contains node B.

* Circular dependencies are not allowed.

An object file can only be used once - either in a library or an executable.
Dynamic libraries don't count as a use - they are just a repackaging.

A dynamic library cannot contain the same static library as another dynamic library.

All static libraries referred to by the static libraries in a dynamic library
must themselves be packaged in dyamic libraries.