rBuilder Online:Appliance Building Tutorial

From rPath Wiki

  rPath Tutorials

This tutorial provides instruction for building a software appliance on rBuilder Online (rBO) using a local build environment in place of rBO's Group Builder.

Some of the instructions for configuring your build environment are abbreviated, and this does not include details for packaging your own software for Conary. Use the New Package Tutorial for more instruction on these topics.

Things You Will Need

To build an appliance for your rBuilder Online project, a few basic things are needed:

• A Conary-based system (such as rPath Linux or Foresight Linux) as a local build environment
• The conary-build package installed on that system (run conary update conary-build as root to get it)
• An rBO project for the appliance; use an existing rBO project for one or more appliances, or create a new rBO project for the appliance

The user root cannot perform all of the package-building activities described in this tutorial. The cvc cook commands which have a potential to cause inadvertant changes to users' systems are disallowed from being run as root for security reasons. rPath thus recommends that you perform regular package-building activities as a user other than root on your local Conary-based system. If you have a sudo package installed on your system, you can execute software installation commands as any user by preceding the command with sudo on the command line. Add your user to the sudoers list (/etc/sudoers) to take advantage of this option.

Set Up a Build Environment

Record the following information about your rBO project:

• Project URL: This should be projectname.rpath.org where projectname is the name of your project in all lower-case letters. Navigate to http://projectname.rpath.org to verify that you are directed to your new project's information page.
• Project Repository URL: The URL to your project's repository should be https://www.rpath.org/rbuilder/repos/projectname/ where projectname is the name of your project in all lower-case letters.
• Project Branch Name: Click edit project beside your project's name on its main project page in rBO, and record the value in the Default Branch Name text box. For this tutorial, you will use the default rpl:devel branch name.

Establish a local build environment on your Conary-based system by creating directories, a .conaryrc configuration file, and a configuration context to use in appliance building.

If you have already stepped through the New Package Tutorial, you can skip most of the set up and just create a new context if you are using a different rBO project.

Directories

Create a conary directory in your home directory on your Conary-based system. Then, create two subdirectories:

[user@localhost ~]$ mkdir -p conary conary/builds conary/cache

• conary/builds is where packages are actually built by Conary
• conary/cache is used by Conary to store the source archives downloaded during the build process, avoiding the necessity of repetitively downloading the same source archive each time you attempt a build

These directories will be specified in the .conaryrc configuration file (created in your next step).

Also, for each project, you should create directories associated with the project. This is described in the Context section.

.conaryrc

Create a text file at ~/.conaryrc with information appropriate for your build environment. The following is an example .conaryrc file showing how each directive is added to the file:

contact             <email_address_or_url>
name                <user_preferred_name>
user                *.rpath.org <rBuilder_Online_username> <rBuilder_Online_password>

[<projectname>]
buildLabel         <projectname>.rpath.org@<project_branch_name>

See the Conary:Configuration for information about each directive.

Use the text editor of your choice and create your own .conaryrc file like this example using your own information appropriate to each directive:

• Use an email address or URL which can be used to contact you in place of <email_address_or_url>
• Use a preferred name, such as your first and last name, in place of <user_preferred name>
• Use only one user line, which is for *.rpath.org
• Replace <rBuilder_Online_username> with your rBO username
• Replace <rBuilder_Online_password> with your rBO password
• Replace <projectname> with the project name as it is displayed in the project URL
• Replace <project_branch_name> with the project branch name; rBO projects typically use the branch name rpl:devel

As previously linked, the conaryrc directives are explained with more detail in Conary:Configuration.

Save the file, and keep it open to learn about your <projectname> configuration context in the next step.

Context

Complete set up of your build environment by establishing and setting up a configuration context. Establish a context to tell Conary which repository you are using at the moment.

For each rBO project, you will need to:

1. Create a context entry in ~/.conaryrc
2. Create a directory under in ~/conary corresponding to the project name
3. Run the cvc context command in the project directory

Create a context entry for each project in ~/.conaryrc: [<projectname>] buildLabel <projectname>.rpath.org@<project_branch_name> Each context entry must, at minimum, specify a buildLabel for the context. The entry can also reference a repositoryMap, which translates the hostname to an available repository URL, and a matching installLabelPath.

For your .conaryrc:

• Add appropriate repositoryMap and installLabelPath directives for your project's repository. (Note that these two lines can be placed in the context-specific entry or with the other directives at the top of the file.)
• Add the context-specific entry for your project including the buildLabel path.

Save and close your .conaryrc file.

Set up your context by running the cvc content command in the project directory. Use the following commands, replacing projectname where appropriate:

[user@localhost ~]$ cd conary/projectname/
[user@localhost projectname]$ cvc context projectname

List the directory contents and verify the CONARY subdirectory was created as part of setting up your context.

Create the Group and Group Recipe

Create the group with cvc newpkg in the project directory, replacing appliancename with a name representing your appliance (often the same as the project name):

[user@localhost projectname]$ cvc newpkg group-<appliancename>
[user@localhost projectname]$ cd group-<appliancename>
[user@localhost group-<appliancename>]$ ls
CONARY

Using your preferred text editor, create the file group-<appliancename>.recipe that will define the contents of your appliance. Examine group recipes from other project as a guide, and use the group recipe documentation as a reference. The following is an example; keep the recipe conforming to Python syntax by using spaces instead of tabs:

class Dist(GroupRecipe):                                #States you are building a group recipe
    name = 'group-<appliancename>'                      #Names the group
    version = '0.1'                                     #Versions this group recipe
    autoResolve = True                                  #Tells the build system to resolve dependencies
    def setup(r):
       r.setLabelPath('<projectname>.rpath.org@rpl:devel',  #Sets the repositories to pull from
                              'conary.rpath.com@rpl:1',     #These should all be lowercase
                              'contrib.rpath.org@rpl:devel')
       r.add('<myapplication>')                         #Include an application you have packaged
       r.add('<anotherpackage>',
                  'anotherproject.rpath.org@rpl:devel') #Include a package with a specific label
       r.add('group-core', 'conary.rpath.com@rpl:1')    #Include the minimal core operating system

Add more existing packages to the appliance group by using additional r.add commands.

If myapplication is not already packaged, use Conary package techniques such as those in the New Package Tutorial, and be sure to check other Conary documentation for reference.

The <tt>autoResolve = True</tt> statement informs the build system that you want Conary to determine the dependencies for packages listed in the recipe. Likewise, build an appliance without autoResolve if you prefer to specify the components manually.

Cook the Group Recipe

Verify the group recipe cooks. The cooking process prompts Conary to assemble the group, check dependencies, provide feedback about the process, and create a changeset:

[user@localhost group-<appliancename>]$ pwd 
/home/<user>/conary/group-<appliancename>
[user@localhost group-<projectname>]$ cvc cook group-<appliancename>.recipe
info: Building group-<appliancename>
Created component: group-<appliancename> /<projectname>.rpath.org@rpl:1/0.1-4-1/local@local:COOK/2 is: x86(cmov i486 i586 i686 ~!mmx ~!x86_64) use: use(!bootstrap ~!builddocs buildtests gcj ~glibc.tls ~!kernel.debug ~!kernel.debugdata ~!kernel.numa ~!kernel.smp krb ~nptl pam pcre ~!pie ~!sasl ~!selinux ~!slang ssl)
Changeset written to: group-<appliancename>-0.1.ccs

If there are any messages during the group build, follow Conary's instructions to repair the recipe file. Advanced recipe troubleshooting techniques are covered throughout the Conary documentation.

Conary does not create static packages, but rather it creates changesets (.ccs files) that define the differences between two known states, much like a diff file.

Use conary showcs to look at the local changeset to see what it specifies:

[user@localhost group-<projectname>]$ ls
CONARY  conaryrc  group-<appliancename>-0.1.ccs  group-<appliancename>.recipe
[user@localhost group-<appliancename>]$ conary showcs group-<appliancename>-0.1.ccs
Note: changeset has no primary troves, showing all troves
group-<appliancename>                0.1-4-2 (absolute)
        New Flavor: is: x86(cmov i486 i586 i686 ~!mmx ~!x86_64)
                    use: use(!bootstrap ~!builddocs buildtests gcj ~glibc.tls ~!kernel.debug ~!kernel.debugdata ~!kernel.numa ~!kernel.smp krb ~nptl pam pcre ~!pie ~!sasl ~!selinux ~!slang ssl)

Use conary showcs options to show all available information as well:

[user@localhost group-<appliancename>]$ conary showcs --all group-<appliancename>-0.1.ccs

Commit the Group Recipe

After the group cooks correctly, commit the group recipe to the rBO project repository:

[user@localhost group-<appliancename>]$ cvc add group-<projectname>.recipe
[user@localhost group-<appliancename>]$ cvc commit --message "note explaining updates"

The add is only needed the first time the recipe is added to the list of files to check in. Use either "commit" or "ci" (for "check in") to commit to the repository. Without the --message option, the commit will prompt you with a vi interface to write a brief commit message; use vi commands to insert text, save, and quit the interface.

On your project page at rBuilder Online, use the 'Browse Repository' link to verify the group recipe file is listed.

Cook the Group

Cook the group in the rBO repository prior to creating builds of the appliance. Use cvc cook with the group name, not just the recipe file name. Because of your previous context and newpkg commands, Conary associates your command with the group in the repository:

[user@localhost group-<appliancename>]$ cvc cook group-<appliancename>
info: Building group-<appliancename>
Created component: group-<appliancename> /<projectname>.rpath.org@rpl:1/0.1-4-2 is: x86(cmov i486 i586 i686 ~!mmx ~!x86_64) use: use(!bootstrap ~!builddocs buildtests gcj ~glibc.tls ~!kernel.debug ~!kernel.debugdata ~!kernel.numa ~!kernel.smp krb ~nptl pam pcre ~!pie ~!sasl ~!selinux ~!slang ssl)
Changeset committed to the repository.

At rBuilder Online, navigate to the project repository in the rBO project and verify the group is listed.

Generate a Build, Publish a Release

Use the instructions in the rBuilder documentation to create a build (image) and a release for your rBuilder Online project using the cooked trove in the project's repository.

• Create a Build
• Create and Publish a Release

Members on a project can download a build of the appliance even if there are no published releases.

Summary

Basic steps and associated cvc commands for rBO appliance building:

1. Set up an rBuilder Online project.
2. Set up a local build environment (directories, Conary configuration, and contexts):
   cvc context <projectname>
3. Create the group and group recipe:
   cvc newpkg group-<appliancename>
4. Verify the group recipe with a local cook:
   cvc cook group-<appliancename>.recipe
5. Add the group recipe to the check in for the rBO project repository (only the first time it is committed):
   cvc add group-<appliancename>.recipe
6. Commit (or check in) the group recipe:
   cvc commit
7. Cook the group in the rBO repository:
   cvc cook group-<appliancename>
8. Use rBuilder Online to create builds (images) and releases of the appliance.

Project owners at rBO are encouraged to use up-to-date project descriptions and mailing lists to encourage others to download their appliances.