Buildyard

Quick Start

Buildyard facilitates the build and development of multiple, dependent projects from installed packages, git or svn repositories. The following projects are currently available, with optional projects drawn as dotted bubbles, and optional dependencies linked using dotted arrows:

Visual Studio

It is highly recommended to install a precompiled boost version using the installers provided on SourceForge (http://sourceforge.net/projects/boost/files/boost-binaries).

Use cmake to generate a Visual Studio Solution. Open this solution and build at least once the 'build' target to download and install all dependencies. See 'Targets' below for more details.

For development, open [build]/[Project]/[Project].sln and work there as usual. This solution will build the (pre-configured) project without considering any dependencies. Use the [build]/Buildyard.sln target to build a project considering all dependencies.

Others

On Ubuntu, use 'make apt-get' to install all known package dependencies. On Mac OS X, use 'make port-get' to install all known MacPorts dependencies.

Execute 'make build' or 'make [Project]' at least once, which downloads, configures and builds debug versions of all or the specified project. See 'Targets' below for more details.

For development, cd into src/[Project] and work there as usual. The default make target will build the (pre-configured) project without considering any dependencies. 'make all' will build the project considering all (pre-configured) dependencies.

Custom CMake binary directories are supported and can be used through the top-level make using 'make BUILD=[directory]' or 'export BUILD=[directory]; make'.

Generic external dependencies

Major open source packages, such as Qt or Boost, are assumed to be installed as packages on the system. If this is not the case, and they should be build from source, enable config.extra in config/depends.txt.

Options

BUILDYARD_UPDATE_REBASE: Try to rebase fetched updates into the project source folder. Default on. Aborts the rebase on merge conflicts.
BUILDYARD_BUILD_OPTIONAL: Build optional dependencies when building a project. Default on.
BUILDYARD_FORCE_BUILD: Force building all non-optional projects from source, if they have a source code repository configured. Default off.
BUILDYARD_INSTALL_PATH: Change the path for installed artefacts produced by the projects. Default [directory]/install.

Targets

Generic Targets

The per-project targets below are also available as aggregate targets for all projects, e.g., 'alls' builds all projects.

apt-get: Install all packages using apt-get on Ubuntu.
port-get: Install all MacPorts packages needed on Mac OS X.
update: Update all Buildyard configurations when called from Buildyard source directory, and updates project when called from project source directory.
info: Display the result of the last configuration run

Per-Project Targets

PROJECT: downloads, configures and build the project and all its dependencies. Typically only used in the beginning to bootstrap
PROJECT-only: Build only the given project without considering dependencies, update and configure steps. This is the recommended way to rebuild a project in a bootstrapped Buildyard instance.
PROJECT-all: Build the given project and all its dependencies without considering the update and configure steps. This is the recommended way to rebuild a project and all its dependencies in a bootstrapped Buildyard instance.
PROJECT-projects: Build all non-optional dependees of the given project, useful for testing downstream projects after API changes.
PROJECT-snapshot: Create one environment module including all dependencies (Release builds only)
PROJECT-reset: Cleans all working changes in the project's source directory.
PROJECT-stat: Run 'SCM status' on the project.

In addition, the targets created by ExternalProject.cmake (download, update, configure, build and install) are also available, but are not really useful in the context of Buildyard.

In-source Targets

Buildyard will set up a Makefile in src/Project, if it is safe to do so. This Makefile forwards to build/Project and allows to build all targets defined by the project. It also provides the following, additional targets:

default: Build this project only, equivalent to PROJECT-only in the build directory
all: Build this project and all dependencies, equivalent to PROJECT-all in the build directory
configure: Reconfigure this project using cmake, equivalent to 'cmake Build/PROJECT'

How does it work?

Buildyard uses simple configuration files grouped in per-organisation config.[org] folders, for example config.eyescale. Simply clone the desired config repositories into the Buildyard directory.

Each config folder may contain a depends.txt, which lists config folders this config folder depends on. This allows extending the base configuration with custom projects from other sources, e.g., https://github.com/Eyescale/config/blob/master/depends.txt

Each config folder contains project .cmake configuration files, for example Equalizer.cmake. It contains the following variables:

PROJECT_VERSION: the required version of the project.
PROJECT_DEPENDS: list of dependencies, OPTIONAL and REQUIRED keywords are recognized. Projects with missing required dependencies will not be configured.
PROJECT_DEPENDEE_COMPONENTS: list of COMPONENTS for find_package.
PROJECT_REPO_TYPE: optional, git, git-svn or svn. Default is git.
PROJECT_REPO_URL: git or svn repository URL.
PROJECT_REPO_TAG: The svn revision or git tag to use to build the project.
PROJECT_REPO_USERNAME: The username to access the repository. Currently only for svn repositories.
PROJECT_REPO_PASSWORD: The password to access the repository. Currently only for svn repositories.
PROJECT_REPO_DEPTH: Depth of the git clone for shallow clones.
PROJECT_ROOT_VAR: optional CMake variable name for the project root, as required by the project find script. Default is PROJECT_ROOT.
PROJECT_TAIL_REVISION: The oldest revision a git-svn repository should be cloned with.
PROJECT_CMAKE_ARGS: Additional CMake arguments for the configure step. The character '!' can be used to separate list items.
PROJECT_AUTOCONF: when set to true, the autoconf build system is used to build the project.
PROJECT_DEB_NAME: Name of the debian package for this project. Used for apt-get target.
PROJECT_DEB_DEPENDS: Debian package names of dependencies. Used for apt-get target and Travis CI configuration files.
PROJECT_PORT_DEPENDS: MacPorts package names of dependencies. Used for port-get target.

The Buildyard CMakeLists pulls in all dependent config folders, reads all .cmake files from the config* directories, and configures each project using ExternalProject.cmake.

Directory Layout

config/ : The builtin configuration files
config.[name] : a configuration module, e.g., config.eyescale
config.[name]/depends.txt : modules upon which the module depends, e.g., config.eyescale/depends.txt. Dependencies will be cloned by Buildyard automatically.
config.[name]/[Project].cmake : A project configuration file (see Configuration)
Build/ : The build directory where all generated files end up.
Build/[Project] : The per-project build directory, including binaries
Release/... : Same as build, but for a 'make release' build
src/ : The directories into which all project sources are cloned
src/[Project] : The source directory for the project. You can work from here, since a Makefile is generated by Buildyard for you (see Using).

Tips and Tricks

Local overrides

For customizing the shipped configurations one can override and extend those configurations with a config.local configuration folder, e.g., eile's config.local. Additional options are available there to specify a user fork for instance. Note that this options are only valid for git repositories:

PROJECT_USER_URL: the URL of the new origin for the project
PROJECT_ORIGIN_NAME: the new remote name of the original origin (optional, default 'root')

Force build from source

Setting PROJECT_FORCE_BUILD to ON will disable finding installed versions of the project, causing the project to be always build from source.

Bootstrapping from project source

Buildyard does configure the project so it can self-bootstrap. This requires the CMake subtree in the project and the setup described in CMake/Buildyard.cmake.

Macports files

Buildyard automatically creates portfiles for MacPorts. Simply add Buildyard/Build/install/ports to your sources:

sudo vi /opt/local/etc/macports/sources.conf
[...]
file:///Users/eilemann/Software/Buildyard/Build/install/ports/
[...]
sudo port install Equalizer +universal

Known issues

Boost build not automatically triggered on VS2010 and later (#17)

chevtche / Buildyard