rBuild

From rPath Wiki

rBuild is a developer tool for building products using rPath's other technologies: Conary, rMake, and rBuilder. After defining a product in rBuilder, developers use rBuild to control rBuilder, Conary, and rMake to build and manage the product. rBuild is designed to make it easy to use rPath's best practices when using Conary, rMake and rBuilder to build a product. It therefore trades some of the flexibility of using the individual tools for an easier user experience.

Products

rBuild is driven by a product definition: A package that is the central storage for information about a product. The product definition is created in the rBuilder Web user interface, and is updated both in the rBuilder Web user interface and by rBuild. That product definition contains some key information:

• Platform: What operating system platform is the product based on? Examples include rPath Linux 1, rPath Linux 2, rPath Appliance Platform Linux Service 1 and 2, SLES 10 Delivered by rPath (available only by subscription), and CentOS 5 Delivered by rPath.

• Output Image Types: How will the product be provided to users? Will it be limited to 32-bit, or also support 64-bit processors? VMWare images? Xen? CD/DVD ISO image files to install on hardware?

• Labels: Where is the product stored in a Conary repository? These locations are called "labels", and rBuilder creates some automatically as part of creating a product.

• Group Name: Conary bundles software together into named groups, and the product definition includes the name of the group that holds the software content of the product.

Getting rBuild

The best way to get rBuild is to use an operating system or image that includes rBuild. If you do not already have one, the easiest way is to download the latest devimage images, which are available both as virtual machines and as ISO images that can be installed on other systems.

Alternatively the rPath Linux text development environment, when updated to the latest version, includes rBuild, as do the most recent versions of the Foresight desktop operating system.

Note that if you are going to build 64-bit x86_64 images, you will need either to have a 64-bit x86_64 development environment (64-bit kernel, not just 64-bit-capable hardware) or use an rMake server running on a 64-bit x86_64 system, such as the rMake server embedded in rBuilder.

Using rBuild

Using rBuild is a lot like using a source code control system. To start working on a product (initializing it), rBuild creates a subdirectory tree which stores the context for working on that product. Further rBuild commands are run from within that subdirectory tree and do things that are appropriate for the subdirectory they are run in.

rBuild also creates (through a short, one-time interview) a file in the developer's home directory with information that it needs to access products, such as information about the rBuilder to use (rBuilder Online or a local installation of rBuilder). rBuild will start this interview process the first time you run a command that requires that the interview be complete.

The rbuild command has subcommands (like help, checkout, and build) and takes more options (like the name of the thing to check out) and command-line arguments (like --verbose). The help command is particularly useful; try rbuild help and rbuild help init for examples of help output.

When rBuild initializes a product on a local development system, that product must already have been created in rBuilder. rBuild needs to know how to get at that product via "short name" and "version" (say, "example" and "1") or via a "label" (say, "example.rpath.org@rpath:example-1").

rBuilder will also have created a group name for the product: Here, group-example-appliance

Note that some of the operations that rBuild takes are long-running; rBuild will signal some long-running operations by printing a timestamp and a summary of the kind of operation it is about to perform.

Initialize the Product

The rbuild init command initializes a product on the local system. The rbuild help init command shows the arguments and describes the options. Using the "example 1" from above, either run rbuild init example 1 or rbuild init example.rpath.org@rpath:example-1. In either case, rBuild will say that it has created the example-1 directory. To work on the example product, cd example-1

There are three obvious subdirectories: Development, QA, and Release. For now, focus on development: cd Development

Checking Out Packages

To check out the group, run the command rbuild checkout group-example-appliance (use the name for your product).

You may also check out packages, which may be packages that are unique to your product, packages from the platform that you want to rebuild or modify, or packages from elsewhere that you wish to rebuild or modify. The command rbuild help checkout describes the options for checking out new or existing packages.

Building

To build the packages that have been checked out (and possibly other packages in the product that rBuild notices need to be built) run the command rbuild build packages -- this will use rMake and Conary to build all the necessary configurations of all the appropriate packages. Many choices are automated, so do not be surprised if rBuild takes a while to determine all the actions that need to be taken. The rbuild help build packages command gives more information on the available options.

After building packages, the packages must be assembled into groups. To build groups for the product, run the command rbuild build groups -- this will (again) use rMake and Conary to build all the necessary configurations of the groups that contain the packages. The command rbuild help build groups gives more information on the available options.

After building groups, it is possible to build images that contain the packages contained by the groups. To build all the images defined in the product definition, run the command rbuild build images -- this will use rMake and rBuilder to build all the system images defined in the product definition.

If you have already built images, your newly-built groups will be available as updates to the images that you have built. Note that newly-built packages will not normally show up as updates until they have been included in groups.

Promoting

When development software is ready for testing by QA, run the command rbuild promote to make the packages included in the current Development group available on the QA label. Note that until now, the product has been built in development; in the example so far, that means that it would show up on the example.rpath.org@rpath:example-1-devel label. The QA group would be available on the example.rpath.org@rpath:example-1-qa label. Note that versions of packages that have been built but are not yet included in groups will not be promoted to the QA stage.

When QA has been completed, the latest version of the group on the QA stage can be promoted by changing to the QA directory (example-1/QA) and again running the rbuild promote command -- rBuild uses the current working directory to know which stage to promote from; it always promotes to the next stage, so it will not overwrite software back on the Development stage.

Note that images built for Development or QA are specifically for Development or QA, respectively, and reference the labels used for Development or QA. Released products need images built for the released software. Change to the Release directory (example-1/Release) and run the rbuild build images command to build the images for the released software.

Updating

When a single developer uses multiple development systems, multiple developers develop a product, or modifications are made to the product definition in the rBuilder Web user interface, those updates need to be reflected in the initialized product. The rbuild status all command will show a summary of all the outstanding changes, and the rbuild update all command will update to reflect all the outstanding changes committed to the repositories but not yet included locally.

rBuild does not change the versions of the packages from the platform on which a product is based unless it is asked to. Therefore, unless it is specifically asked to update the platform, security updates and bug fixes included in the platform will not be included in new versions of the product. This is done in order to make it easy to change only one thing at a time and know whether problems are due to changes in the platform or in the packages included in the product. However, it also means that updating to the latest version of the platform is a good idea, both from security and bug fix standpoints. To update to the latest version of the platform on which the product is based, run the rbuild rebase command.