Conary:Recipe Conventions

From rPath Wiki

Recipes are written on Conary's code base, which is in the Python programming language. Python knowledge is encouraged, but not required. rPath recommends that packagers use sample recipes and the recipe templates as a resource to start a new recipe, and to follow the conventions described here.

Be sure to use the Recipe Structure page to supplement this reference.

Basic Recipe Syntax

Use the following syntax guidelines to keep Conary recipes consistent in form. Many of these overlap with typically recommended Python syntax:

• Use 4 space indentation, not tabs
  NOTE: In the vi text editor, packages can set the tab key to enter four spaces with each use: set expandtab softabstop=4 sw=4
• Keep line lengths to 78 characters, exceeding this for strings without natural breaks
• When breaking up a function, indent the next line of the function to the open parenthesis ( ( ) opening the function, or (if more lines are needed) increase indentation one level
• Avoid excessive ( \ ) in strings when possible
• Use grouped single quotes ( '' ) instead of multiple-line triple-double quotes ( """ ... """ ) for function arguments, such as in the following example:

r.Configure('options here'
            ' --more-option=here'
            ' --still-more-options')

If you are using \n at the end of each line, use """ ... """ instead.

As of 1.2.10, Conary automatically escapes spaces in URLs.

Naming Conventions

The actual class name in a recipe does not matter, but rPath recommends that it is a CamelCase version of the name string provided, removing any characters that are not allowed in Python identifiers. Also, the current class instance, which is typically self in standard Python code, is called r in Conary recipes.

Other naming conventions recommended by rPath are as follows:

• Use extraConfig for config options that are based on Use/Arch flags
• Use r.macros.x for values that are used in strings
• Use a local variable when branching on that value; this is useful when branching can be useful for features that do not deserve a Use flag but may need to be turned on or off by individual packagers
• In URLs that change directories with versions, do not use %(version)s in the filename

Ordering

There are no restrictions to the ordering of lines in a recipe provided that the setup function and macro settings are executed prior to other actions. However, rPath has some basic recommendations for recipe readability. See the following skeleton used to demonstrate this recommended order:

class PackageName(PackageRecipe):
    name = 'name'
    version = '4.5'
 
    buildRequires = []
 
    def setup(r):
        r.addArchive
        r.addPatch
        r.addSource #if the source code is one-off files that do not interact with patches
        r.addAction
 
        <setting cflags, mflags macros; they last throughout build>
 
        r.Configure
        r.Make
 
        r.MakeDirs
        r.MakeInstall
        r.Install
        r.Symlink
        r.Doc
        r.Remove, other cleanup
 
        r.Ownership/SetModes
        r.PackageSpec
        r.ComponentSpec

Some packagers may prefer a logical order while others prefer a chronological order. Additionally, some packagers need more blank lines than others to help organize the code. Note the types of methods called to plan recipe structure, and ensure that the structure facilitates efficient code update work.

Packagers making use of the --resume option when cooking should be aware of the impact of logical versus chronological recipes. Essentially; the --resume option will do what you expect only in recipes that are ordered chronologically.