Devshell API

Developement

The following document explains the key components in Fedora Devshell, and how to extend it for your own nefarious purposes. The Modules section addresses the kinds of actions Fedora Devshell can do, and how they are implemented. The Utility functions highlights some of the key components used as building blocks. The Coding Guidelines are critically important, as they must be followed to in order to submit patches. The Submission Guidelines explain how to get your patches in.

Modules, Interfaces and Base Classes

BuildSystem

BuildSystem is a Python class of type MetaBuildSystem. MetaBuildSystems are registerd with a BuildSystemFactory, which can load any BuildSystem loaded in the run time space. It's initializer takes one argument, a PackageSource either on the file system or a Python object. BuildSystem is an interface on top of common build systems such as autotools, cmake, and cabal.

It exposes five methods.

1. configure(target, *args) - runs the configure stage of the build system - can be a noop. target points to where to install it on the system, *args are passed to the underlying package source to work on a specific branch.
2. build(*args) - runs the build stage - should not be a noop. *args are passed to the underlying package soruce to work on a specific branch.
3. install(*args) - runs the install stage - cannot be a noop. *args are passed to the underlying package soruce to work on a specific branch.
4. install_source(target, *args) - configures, builds, and installs some source. target points to where to install it on the system, *args are passed to the underlying package source to work on a specific branch.
5. gen_spec() - creates a spec file specific to this build system

Cabal

Cabal is an implementation of a BuildSystem. It works on top of The Haskell Cabal, which is the build tool used for building Haskell packages. It uses the program cabal2spec provided in Fedora for generating the spec file.

PackageSource

PackageSource is a Python class of type MetaDirectory. MetaDirectorys are registered with a DirFactory, which can load any directory from the filesystem as the properly subclassed Directory in Fedora Devshell. PackageSource is a single source, be it a tarball or revision control that will go into an RPM Package.

It exposes 9 methods.

1. setup_sourceball(ver=) - sets up a source tarball if needed out of the revision control. ver is the upstream version
2. setup_sourceball_w_patches(ver=) - not sure of the behavior of this one yet, it's a placeholder
3. src_dir(*args) - a contextmanager that will run a block of code inside a specfic branch or checkout
4. src(*args) - a context manager that will run a block of code with a certain branch or checkout set as the active one.
5. set_current_src() - a hook to be implemented by the subclass, notifies the subclass when the active source has changed and runs any arbitrary code.
6. set_cur_to(*args) - where *args is processed. This parses *args, and sets the source to some source directory accordingly. Must be overridden in a subclass
7. branch(*args) - returns the relative path to where a named branch is stored, based on *args.
8. branch_dir(*args) - returns the absolute patch of branch

It exposes 10 properties

1. pkg_src - a relative path where internal files to devshell are stored inside the package source
2. pkg_src_dir - the absolute pathname to pkg_src
3. branches - a relative path to where branches are stored inside their package source
4. branches_dir - the absolute pathname to branches
5. sourceball - a relative pathname to the current source tarball equivalent to this package source
6. sourceball_loc - the absolute pathname to sourceball
7. source - a relative pathname to the currently active sourcetree
8. source_dir - the absolute pathname to source
9. buildsystem - the type of buildsystem that this sourcetree uses
10. builder - a reference to a BuildSystem that can build this package

Coding Guidelines

The following basic rules must be applied. Exceptions can be granted for any reason, provided there's a good reason.

• Basic coding standards will follow PEP 8, except where noted below.
• Code should be as big as your head. If you have a small head or a large monitor, lower your font resolution ;).
• Code should be terse, and haiku like. It should explain a single concept or action clearly, without being overrun by scaffolding.
• Scaffolding should be broken down into utility functions, all exposed in the API. They should be documented clearly.
• Where logical, use context managers. This will isolate the alogrithm from the build up and break down.
• High nesting of if/then statements is not allowed
• High nesting of context managers and for loops are allowed, although extreme nesting is discouraged.
• Read only attributes from obj.cfg should be exposed as properties as such:

@property
def spec_file(self):
    '''returns the name of the spec file as it should be accordingto 
    fedora guidelines, good for double checking'''
    return self.pkg_name + '.spec'
 
@property
def pkg_name(self):
    '''canonical name of the package in a source repository'''
    return self.cfg['pkg_name']

Submission Guidelines

All patches are welcome. The best way to submit patches initially is via email or mailing lists, or sending a pull request from another git repo. In order to get write access to the public repo, there is a one drink minimum. To demonstrate understanding of the Coding Guidelines, the submitter must have at least one other patch approved before gaining write access. This will ensure that the coder has had ample time to learn the simple guidelines.