The pl-build-tools-vanagon repo is what we use to build packages to satisfy build-time dependencies for puppet-agent. By standardizing our own toolchain, we are able to create a consistent build process for use with our continuous integration processes. We also avoid having to workaround problems related to the plethora of different build tools (and versions) available by default on each target platform.
Internally at Puppet Inc, we ship these build packages to package repositories on our internal network. To help our partners and the community use these packages, we have mirrored them to externally accessible package repositories at FIXME: ADD URL TO PUBLIC REPO HERE.
The build tools and libraries you can build using this repository can be found in the configs/projects/ directory, and includes:
- pl-gcc
- pl-boost (build requires pl-gcc)
- pl-cmake (build requires pl-gcc)
- pl-yaml-cpp (build requires pl-gcc, pl-boost, and pl-cmake)
among others.
The packages we generate use the "pl-" prefix (for Puppet Labs) and get installed under /opt/pl-build-tools/ in order not to conflict with system packages.
A modern Linux or Mac OS X operating system with a recent version of Ruby (1.9 or later) with the bundler gem is required to run these builds.
This repository makes use of the Vanagon build system, which is written in Ruby. The Gemfile included in this repo specifies all of the needed ruby libraries to build a target project. Additionally, vanagon requires a virtualization engine to build target packages in. More information on the different virtualization engine options is available in the vanagon repo.
Begin by cloning this repository:
git clone https://github.com/puppetlabs/pl-build-tools-vanagon.git
and install the required Ruby gems with the bundle install command:
cd pl-build-tools-vanagon/
bundle install
By default, our Gemfile specifies a particular version of Vanagon (typically, the latest master branch checked out from the vanagon GitHub repo). There are times where you may wish to use a customized version of vanagon from a git repository branch, or a copy of Vanagon stored locally on your filesystem. You can do this by setting the environment variable VANAGON_LOCATION when running bundle install:
0.3.14- Use a specific git tag from the Vanagon git repogit@github.com:puppetlabs/vanagon#master- Customize the remote git location and/or branchfile:///workspace/vanagon- Absolute file pathfile://../vanagon- File path relative to the project directory
Let's say you want to build pl-gcc for Debian 8 (Jessie) 64-bit. First verify that you have a project pl-gcc (configs/projects/pl-gcc.rb) and a platform file for Debian 8 (configs/platforms/debian-8-amd64.rb). Ensure you are current in the root directory of the repo, and run:
bundle exec build pl-gcc debian-8-amd64 <target host>
where target host is the hostname or IP address of a 64-bit Debian 8 server or VM that the build will be run on. Internally at Puppet we have a dynamic vmpooler infrastructure that provides VMs for all of our target platforms, so target host is not necessary in that case.
The build process will take the configuration defined in configs/projects/pl-gcc.rb and build any component dependencies required from configs/components. The final project will then be packaged and made available under the output/ directory.
The build command above comes from the vanagon gem, and it has a number of position-dependent arguments:
The name of the project to build. A file named project_name.rb must be present in the configs/projects/ directory.
The name of the platform to build for. A file named platform_name.rb must be present in the configs/platforms/ directory.
You can specify multiple platforms to build for at once by using a comma-separated list (e.g, platform1,platform2).
Target host is an optional argument which overrides the host selection. Instead of using a vm collected from the pooler, the build will attempt to ssh to the target host as root.
If you're building multiple platforms at once, multiple target hosts can also be specified using a comma-separated list (e.g, host1,host2). If fewer targets are specified than platforms, the default build engine (the pooler) will be used for platforms without a target host. If more target hosts are specified than platforms, the extra target hosts will be ignored.
To add a new platform, begin by adding the platform definition file in configs/platforms. Then additional customizations when building components for that platform can be added to the component definitions in configs/components. If this is an entirely new platform (and not just a new version of a platform already supported), you may need to make changes in vanagon as well. Using the build dependency graph above, start with pl-gcc and work your way through the dependency chain. Once packages for all of the relevant pl-build-tools have been generated, you can then move on to building a puppet-agent package using the puppet-agent repository.
New projects require an entry in configs/projects. A file for anything this project includes, with instructions on how to configure and build it, should also be added under configs/components if it does not already exists. Refer to existing projects in this repo or to the example in vanagon for more details.
Puppet, Inc. offers community-based support for this repository. Questions should be directed to the Puppet Developers mailing list. Some code in this repository is related to platforms available only to Puppet Enterprise users, (e.g, Solaris and AIX), and we only offer support for those platforms to official partners of Puppet, Inc.