Tutorial:Conary Packaging
From rPath Wiki
|
Before stepping through this tutorial, you may want to see the following resources:
Also, prior to stepping through this tutorial, you will need a configured development environment. Use the following tutorials to establish such a development environment:
Establish a Project Repository
To package software for Conary package management, you need a Conary repository to which you have write permissions. Each rBuilder project includes a repository, and users can set up stand-alone repositories. This tutorial steps through using rBuilder Online, which sets up a free repository for each project.
If you have not already done so, do the following:
Set Up a Context
Set up a context for packaging as described in the Conary Contexts Tutorial. Use the information from your rBuilder Online project as follows:
- Repository hostname: The repository hostname is an abbreviated URL for your project that uses the project name and the domain name of the rBuilder installation. For rBuilder Online, 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 in a web browser to verify that you are directed to your new project's main page.
- Project Repository URL: The URL to your rBuilder Online project 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. Though this can be any two colon-separated values, use corp:example-1-devel for this tutorial.
 | 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 inadvertent 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. |
Create a New Package
Create a new package by using the cvc newpkg command in your context to create the package filespace and writing the recipe used to cook the package.
The package example for this tutorial will package a small application which requires a very basic recipe: Goom. In the directory of your newly created context, create the new package filespace.
[devuser@mymachine projectname]$ cvc newpkg goom
Change directories to the new goom subdirectory and create a new recipe file:
[devuser@mymachine projectname]$ cd goom
Create a text file called goom.recipe in the goom subdirectory using a text editor of your choice. Use the instructions in the package recipe step to edit this new file.
Package Recipe
The Conary package recipe provides all the instructions Conary needs to go from downloading the source to creating a package that will install as desired on a Conary-based system. Recipes range in complexity depending on the variety of options and conditions that must be considered for configuring and installing the software.
The Goom recipe is very basic because it can be built with very few instructions. Most of its instructions call established tools that automatically unpack and install typical source code. Edit your new goom.recipe file to match the following example:
class Goom(AutoPackageRecipe): name = 'goom' version = '2k4_0' buildRequires = [] def unpack(r): r.macros.upstreamVersion = r.macros.version.replace('_','-') r.addArchive('http://superb-east.dl.sourceforge.net/sourceforge/' '%(name)s/%(name)s-%(upstreamVersion)s-src.tar.gz')
In this recipe, AutoPackageRecipe takes the place of what would typically be just PackageRecipe (a super class). This tells Conary where to get the archive using a method called unpack.
One problem that Goom presents is using the hyphen (-) character in the version string. Because Conary does not allow hyphens, you are creating a macro called upstreamVersion that allows you to pull the correctly named upstream source.
The r.addArchive line provides the full URL to the upstream source using the macro values.
| | Note that the URL was broken into two lines for easy reading. On a single line, the URL would be in a single pair of quotes between the parentheses. This and other syntax is part of the Python programming language in which your recipe is written. For future recipe writing, you may wish to familiarize yourself with Python using the tutorial at Python.org. |
For future packaging, see the Develop a Package Recipe HOWTO which provides stepwise instructions for developing recipes using the information provided in Conary:Recipe and Conary:Package Recipe Classes. You may also wish to consult Conary API Documentation for lower-level recipe development.
Cooking for Packages
There are two types of cooking to be aware of when working with packages: cooking the recipe and cooking the package.
Cook the recipe to check whether the package will build, to examine what additional instructions you may need in your recipe, and to install and test the changeset prior to committing the new package to the repository. When you cook the recipe, a changeset is created that includes the packaged software. Use this changeset to test the installation of the software before committing the changeset to the repository.
Commit and cook the package to finally add the package to the repository from which it can be installed. The tutorial sections which provide instructions for this include more information about what happens when you perform these actions.
| | Another use of the term cook is in regards to groups. This is a separate type of cook used in appliance building. Cooking a group is not covered in this tutorial. |
Cook the Recipe and Test
Use the following command to cook the receipe.
[devuser@mymachine goom] cvc cook goom.recipe
The messages displayed during the cook include information about downloading, making, component creation, and writing a changeset. For this tutorial, warning messages in the output indicate modifications that can be made to the buildRequires portion of the recipe. For the tutorial, Goom displays some messages suggesting modifications to the recipe, but you will not need to change your recipe to continue.
In typical package building, you will modify the recipe and repeat cooking the recipe as many times as necessary to handle these warnings and other issues indicated by the cook messages. This is the most important and involving step in the package building process, and mastering recipe development is the key to mastering package building in Conary. As previously mentioned, see the Develop a Package Recipe HOWTO for further information about developing recipes.
Ensure things built correctly by installing the changeset file packagename-packageversion.ccs where packagename and packageversion match the package you have built. For the Goom example, it should be goom-2k4_0.ccs, and you may have seen a line in the output after the build that indicated this file was written.
Install the changeset using the following command.
[devuser@mymachine goom]$ sudo conary update goom-2k4_0.ccs
| | This command assumes the current user has rights to install software on the local system. As mentioned at the start of the tutorial, you may use sudo to do this if you are not the root user. |
If the installation worked correctly, you should have libgoom2.so in /usr/lib (or in /usr/lib64 for 64-bit architectures), and you should should have a directory full of useful information at /usr/share/doc/goom-2k4_0/.
For future package building, repeat the steps of updating the recipe, cooking the recipe, and applying the changeset until the installation works in the way you want your package to work.
Commit and Cook the Package
After the package has built and installed correctly (or as you wish for it to work), commit the recipe to the repository, and cook the package in the repository.
Commit
Change to the directory containing the recipe and use cvc add and cvc ci to commit the recipe. For the Goom recipe in this tutorial, using the following commands.
[devuser@mymachine goom-2k4_0]$ cd ~/conary/projectname/goom/ [devuser@mymachine goom]$ cvc add goom.recipe [devuser@mymachine goom]$ cvc ci
You will only need the cvc add command one time after each cvc newpkg. After the package is added and committed, any changes can be committed with cvc ci without a preceding add command.
Conary starts a session of the default text editor for the system, prompting for a commit message. If this is the vi text editor, press i to start inserting text, type New package (or something similar), and then save and quit vi. (Commands for saving and quitting in vi: Press Esc, type :wq, and press Enter.)
Verify the commit progress is displayed briefly and replaced with the next command prompt.
| | rmake commit may be used in lieu of cvc commit or cvc ci for checking in newly packages. |
| | You may occassionally see the cvc commit command in place of the cvc ci in some cases, and both commands will perform the same task. Add a --message option with an argument in single quotes to provide the commit message at the commandline instead of in the subsequent vi session. For the Goom steps, you could replace cvc ci with this command: cvc ci --message 'New package' |
| | If you are using local source files instead of a source URL, cvc ci will prompt you to use cvc add on those files in addition to the recipe file. |
Cook
Cook the package in the repository so all the troves will be created and the package will be both installable from the repository and available to add to software appliances in rBuilder projects. For the the Goom package in this tutorial, use the following commands.
[devuser@mymachine goom]$ cvc cook goom
Like the recipe cook, the package cook also displays messages during the process. Verify the last line of the output reads Changeset committed to the repository.
You can also verify the package is now available in your rBO project by navigating to the project's main page, clicking Browse Repository, and verifying the goom package is listed.
Install the Package from the Repository
After you have created the package, including committing it to the repository and cooking the package in the repository, any user who has access to install from that respository can use conary update to install the package.
Complete this tutorial by installing your new Goom package from your rBO repository. Use the following command.
[devuser@mymachine goom]$ conary update goom