+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. Refer to section 4 for how packages are located. A package that
+can't be found will cause the build to fail. If the -x option was specified,
+builder will only consider binary packages when looking for dependencies.
+
+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 9 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. Locating packages
+
+Most packages are not self-contained, but depend on other packages. When such
+dependencies are encountered, the packages need to be located. This section
+describes the various places Builder looks for them from.
+
+First, Builder asks pkg-config if it knows the location of the source
+directory of the package. This is stored in the source variable in the .pc
+file, and is automatically put there by Builder. If the variable is found,
+Builder further verifies that it refers to an existing directory which
+contains a Build file, so that removed sources do not cause undue failures.
+
+If pkg-config does not know about the source, Builder consults its own package
+path. Currently this is hardcoded to contain the main package's source
+directory and its parent directory. To be found this way, the directory
+should be named the same as the package, optionally followed by a dash and a
+version number (or really anything; the part after the last dash is ignored).
+
+If the source can't be found at all, Builder will then turn to using a binary
+package. Builder's native packages are considered first. They are normally
+stored in <prefix>/share/builder with the extension bpk. The base part of the
+filename should be the as the package's name.
+
+Finally, pkg-config is consulted for the build flags of the package in the
+normal way. The flags need to be translated to Builder's internal
+representation, so if the package requires very unusual flags, it may not
+work.
+
+A package that can't be found after all these steps might as well not exist.
+
+-------------------------------------------------------------------------------
+
+5. 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 9 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. This is mainly
+ useful for debugging Builder itself; for normal use the -v option is almost
+ always enough. Refer to section 10 for the available 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 8 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 files 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.
+
+-------------------------------------------------------------------------------
+
+6. Virtual targets
+
+Builder provides virtual targets for certain tasks, as well as for internal
+organization of the build graph. They can appear on the command line along
+with file-based targets.
+
+world
+ Depends on everything that can be built.
+
+default
+ Depends on the targets that are built by default. If no targets are
+ specified on the command line, then this target will be built.
+
+install
+ Depends on all installed files. This also includes .pc files, which are
+ otherwise not normally built.
+
+tarballs
+ Depends on source tarballs of all packages.
+
+goals
+ Depends on all targets on the command line. Trying to add this target to the
+ command line will cause Builder to abort due to a circular dependency.
+
+-------------------------------------------------------------------------------
+
+7. Tarballs
+
+Since the source tree usually contains files that do not belong to a release
+archive, be they version control metadata or temporary build files, Builder
+provides a way to create a clean source tarball for a package. It will
+contain all non-buildable files belonging to the package, including its Build
+file.
+
+Source tarballs are named as <package>-<version>.tar. Currently compression
+is not supported.
+
+-------------------------------------------------------------------------------
+
+8. 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.