bindep 0.0.1

Binary dependency utility

Introduction

Bindep is a tool for checking the presence of binary packages needed to use an application / library. It started life as a way to make it easier to set up a development environment for OpenStack projects. While OpenStack depends heavily on pip for installation of Python dependencies, some dependencies are not Python based, and particularly for testing, some dependencies have to be installed before pip can be used - such as virtualenv and pip itself.

Basics

Create a file called other-requirements.txt and in that list any requirements your application / library has. In your README or INSTALL or other documentation you can tell users to run bindep to report on missing dependencies. Users without bindep installed can consult the other-requirements.txt file by hand if they choose, or install bindep first and then use it.

Profiles

Profiles can be used to describe different scenarios. For instance, you might have a profile for using PostgreSQL which requires the PostgreSQL client library, a profile for MySQL needing that client library, and a profile for testing which requires both libraries as well as the servers. To select a profile just pass it when running bindep - e.g.:

$ bindep test

When running bindep a single profile can be chosen by the user, with no explicit selection resulting in the selected profile being default. bindep will automatically activate additional profiles representing the platform bindep is running under, making it easy to handle platform specific quirks.

The available profiles are inferred by inspecting the requirements file and collating the used profile names. Users can get a report on the available profiles:

$ bindep --profiles

Writing Requirements Files

The requirements file other-requirements.txt lists the dependencies for projects. Where non-ascii characters are needed, they should be UTF8 encoded.

The file is line orientated - each line is a Debian binary package name, an optional profile selector and optional version constraints. (Note - if you are writing an alternative parser, see the Debian policy manual for the parsing rules for packagenames). Debian package names are used as a single source of truth - bindep can be taught the mapping onto specific packaging systems. Alternatively, profiles may be used to encode platform specific requirements.

Profiles are used to decide which lines in the requirements file should be considered when checking dependencies. Profile selectors are a list of space separated strings contained in []. A selector prefixed with ! is a negative selector. For a line in the requirements file to be active:

• it must not have a negative selector that matches the active profile.

• it must either have no positive selectors, or a positive selector that matches the active profile.

For instance, the profile selector [!qpid] will match every profile except qpid and would be suitable for disabling installation of rabbitmq when qpid is in use. [default] would match only if the user has not selected a profile (or selected default). [default postgresql test] would match those three profiles but not mysql. [platform:rhel] will match only when running in a RHEL linux environment.

Version constraints are a comma separated list of constraints where each constraint is (== | < | <= | >= | > | !=) VERSION, and the constraints are ANDed together (the same as pip requirements version constraints).

Comments are allowed: everything from the first # to the end of the line is ignored.

Developing bindep

Either install bindep and run bindep test to check you have the needed tools, or review other-requirements.txt by hand.

Running Tests

The testing system is based on a combination of tox and testr. The canonical approach to running tests is to simply run the command tox. This will create virtual environments, populate them with depenedencies and run all of the tests that OpenStack CI systems run. Behind the scenes, tox is running testr run –parallel, but is set up such that you can supply any additional testr arguments that are needed to tox. For example, you can run: tox – –analyze-isolation to cause tox to tell testr to add –analyze-isolation to its argument list.

It is also possible to run the tests inside of a virtual environment you have created, or it is possible that you have all of the dependencies installed locally already. If you’d like to go this route, the requirements are listed in requirements.txt and the requirements for testing are in test-requirements.txt. Installing them via pip, for instance, is simply:

pip install -r requirements.txt -r test-requirements.txt

In you go this route, you can interact with the testr command directly. Running testr run will run the entire test suite. testr run –parallel will run it in parallel (this is the default incantation tox uses.) More information about testr can be found at: http://wiki.openstack.org/testr