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 ``bindep.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
``bindep.txt`` file by hand if they choose, or install `bindep`
first and then use it.
If no ``bindep.txt`` file exists, `bindep` will look at the
old location ``other-requirements.txt``.
The output from bindep is fairly verbose normally, but passing an option of
-b/--brief outputs just the missing packages one per line, suitable for feeding
to your package management tool of choice.
If you need to maintain multiple requirements list files you can pass a
specific filename with the -f/--file command line option. If you want to read
the list from standard input in a pipeline instead, use a filename of "-".
When bindep runs, its exit code is ``0`` if no described packages are missing,
but ``1`` if there are packages which it believes need to be installed.
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 ``bindep.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.
Note that platform selectors are treated as kind of filter: If a line
contains a platform selector, then the package only gets installed if
at least one of the platform selectors matches in addition to the
match on the other selectors. As an example, ``[platform:rpm test]``
would only install a package on a RPM platform if the test selector is
used.
Profiles can also be grouped together using ``()``. In a group, all profiles
must match for the group to match. Given the example
``[test (ceph glance !lvm)]``, to select the package you must either specify
``test`` OR (``ceph`` AND ``glance`` AND NOT ``lvm``). Platform selectors will
not work inside of the group.
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,
except that they require a space between the dep and version constraints).
Comments are allowed: everything from the first ``#`` to the end of the line is
ignored.
Examples
--------
A simple example with using a test profile is::
# A runtime dependency
libffi6
# A build time dependency
libffi-devel [test]
bindep would select the ``libffi6`` package in all cases and if the
``test`` profile gets choosen with ``bindep test``, then both packages
would be selected.
If a repository needs for deployment the libxml2 development
libraries for support of Debian, Gentoo, and RPM based distros, the
``bindep.txt`` file can contain::
libxml2-dev [platform:dpkg]
libxml2-devel [platform:rpm]
libxml2-utils [platform:dpkg]
dev-libs/libxml2 [platform:gentoo]
This would select ``libxml2-dev`` and ``libxml2-utils`` packages on
Debian based distributions like Debian and Ubuntu since those entries
have the ``platform:dpkg`` profile, ``libxml2-devel`` on RPM based
distributions like CentOS, Fedora, openSUSE, Red Hat, or SUSE Linux
since those entries have the ``platform:rpm`` profile, and
``dev-libs/libxml2`` on Gentoo since the entry has the
``platform:gentoo`` profile.
Additionally, you can use ``platform:redhat`` or ``platform:suse`` to only
match RedHat-like or SUSE-like distributions respectively as shown in the
following example::
openssh-server [platform:redhat]
openssh [platform:suse]
If you need to distinguish between operating systems where python2 or python3
is the official interpreter, you can use `base-py2` and `base-py3` labels.
Keep in mind that only one would be exposed for a specific operating system
even if the system could support installation of multiple python versions::
python3-lxml [(platform:redhat platform:base-py3)]
python-lxml [(platform:redhat platform:base-py2)]
The example above will install lxml python modules on official python used
by platform. Keep it mind that ``base-py[23]`` support is currently implemented
only on Debian, Ubuntu, RedHat flavours and MacOS.
To select Python3 development packages, you can use::
python3-all-dev [platform:dpkg !platform:ubuntu-precise]
python3-devel [platform:fedora]
python34-devel [platform:centos]
This selects ``python3-all-dev`` on all Debian based distributions
with the exception of Ubuntu Precise, ``python3-devel`` on Fedora and
``python34-devel`` on CentOS.
To select the curl package::
curl [!platform:gentoo]
net-misc/curl [platform:gentoo]
This selects the ``curl`` package on all distributions with the
exception of Gentoo, and selects ``net-misc/curl`` on Gentoo only.
To select a package based on a group of profiles::
ceph-common [ceph]
python-rbd [(ceph glance)]
This selects the ``ceph-common`` package when the profile ``ceph`` is
specified. However, it will only select the ``python-rbd`` package when both
``ceph`` and ``glance`` profiles are active.
To specify package versions::
python >=3.7,<=3.8
grep >=3.3
# OR with a platform profile
python [platform:brew] ==3.7.3
For a more comprehensive example check bindep.txt_ file that is used to
test bindep itself on multiple platforms.
.. _bindep.txt: https://opendev.org/opendev/bindep/src/master/bindep/tests/bindep.txt
Raw data
{
"_id": null,
"home_page": "https://docs.opendev.org/opendev/bindep",
"name": "bindep",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "binary dependency distribution distro package commandline",
"author": "OpenDev Contributors",
"author_email": "service-discuss@lists.opendev.org",
"download_url": "https://files.pythonhosted.org/packages/8e/89/689d7f17c559dea2849d27365f53bd40f134056392db9e88a2590eb3dc29/bindep-2.11.0.tar.gz",
"platform": null,
"description": "Introduction\n============\n\nBindep is a tool for checking the presence of binary packages needed to\nuse an application / library. It started life as a way to make it easier to set\nup a development environment for OpenStack projects. While OpenStack depends\nheavily on `pip` for installation of Python dependencies, some dependencies are\nnot Python based, and particularly for testing, some dependencies have to be\ninstalled before `pip` can be used - such as `virtualenv` and `pip` itself.\n\nBasics\n------\n\nCreate a file called ``bindep.txt`` and in that list any\nrequirements your application / library has. In your README or INSTALL or\nother documentation you can tell users to run `bindep` to report on missing\ndependencies. Users without `bindep` installed can consult the\n``bindep.txt`` file by hand if they choose, or install `bindep`\nfirst and then use it.\n\nIf no ``bindep.txt`` file exists, `bindep` will look at the\nold location ``other-requirements.txt``.\n\nThe output from bindep is fairly verbose normally, but passing an option of\n-b/--brief outputs just the missing packages one per line, suitable for feeding\nto your package management tool of choice.\n\nIf you need to maintain multiple requirements list files you can pass a\nspecific filename with the -f/--file command line option. If you want to read\nthe list from standard input in a pipeline instead, use a filename of \"-\".\n\nWhen bindep runs, its exit code is ``0`` if no described packages are missing,\nbut ``1`` if there are packages which it believes need to be installed.\n\nProfiles\n--------\n\nProfiles can be used to describe different scenarios. For instance, you might\nhave a profile for using PostgreSQL which requires the PostgreSQL client\nlibrary, a profile for MySQL needing that client library, and a profile for\ntesting which requires both libraries as well as the servers. To select a\nprofile just pass it when running `bindep` - e.g.::\n\n $ bindep test\n\nWhen running bindep a single profile can be chosen by the user, with no\nexplicit selection resulting in the selected profile being ``default``.\n`bindep` will automatically activate additional profiles representing the\nplatform `bindep` is running under, making it easy to handle platform specific\nquirks.\n\nThe available profiles are inferred by inspecting the requirements file\nand collating the used profile names. Users can get a report on the \navailable profiles::\n\n $ bindep --profiles\n\n\nWriting Requirements Files\n--------------------------\n\nThe requirements file ``bindep.txt`` lists the dependencies for\nprojects. Where non-ascii characters are needed, they should be UTF8 encoded.\n\nThe file is line orientated - each line is a Debian binary package name, an\noptional profile selector and optional version constraints. (Note - if you are\nwriting an alternative parser, see the Debian policy manual for the parsing\nrules for packagenames). Debian package names are used as a single source of\ntruth - `bindep` can be taught the mapping onto specific packaging systems.\nAlternatively, profiles may be used to encode platform specific requirements.\n\nProfiles are used to decide which lines in the requirements file should be\nconsidered when checking dependencies. Profile selectors are a list of space\nseparated strings contained in ``[]``. A selector prefixed with ``!`` is a negative\nselector. For a line in the requirements file to be active:\n\n* it must not have a negative selector that matches the active profile.\n* it must either have no positive selectors, or a positive selector that\n matches the active profile.\n\nFor instance, the profile selector ``[!qpid]`` will match every profile except\n``qpid`` and would be suitable for disabling installation of rabbitmq when qpid\nis in use. ``[default]`` would match only if the user has not selected a\nprofile (or selected ``default``). ``[default postgresql test]`` would match\nthose three profiles but not ``mysql``. ``[platform:rhel]`` will match only\nwhen running in a RHEL linux environment.\n\nNote that platform selectors are treated as kind of filter: If a line\ncontains a platform selector, then the package only gets installed if\nat least one of the platform selectors matches in addition to the\nmatch on the other selectors. As an example, ``[platform:rpm test]``\nwould only install a package on a RPM platform if the test selector is\nused.\n\nProfiles can also be grouped together using ``()``. In a group, all profiles\nmust match for the group to match. Given the example\n``[test (ceph glance !lvm)]``, to select the package you must either specify\n``test`` OR (``ceph`` AND ``glance`` AND NOT ``lvm``). Platform selectors will\nnot work inside of the group.\n\nVersion constraints are a comma separated list of constraints where each\nconstraint is (== | < | <= | >= | > | !=) VERSION, and the constraints are ANDed\ntogether (the same as pip requirements version constraints,\nexcept that they require a space between the dep and version constraints).\n\nComments are allowed: everything from the first ``#`` to the end of the line is\nignored.\n\nExamples\n--------\n\nA simple example with using a test profile is::\n\n # A runtime dependency\n libffi6\n # A build time dependency\n libffi-devel [test]\n\nbindep would select the ``libffi6`` package in all cases and if the\n``test`` profile gets choosen with ``bindep test``, then both packages\nwould be selected.\n\nIf a repository needs for deployment the libxml2 development\nlibraries for support of Debian, Gentoo, and RPM based distros, the\n``bindep.txt`` file can contain::\n\n libxml2-dev [platform:dpkg]\n libxml2-devel [platform:rpm]\n libxml2-utils [platform:dpkg]\n dev-libs/libxml2 [platform:gentoo]\n\nThis would select ``libxml2-dev`` and ``libxml2-utils`` packages on\nDebian based distributions like Debian and Ubuntu since those entries\nhave the ``platform:dpkg`` profile, ``libxml2-devel`` on RPM based\ndistributions like CentOS, Fedora, openSUSE, Red Hat, or SUSE Linux\nsince those entries have the ``platform:rpm`` profile, and\n``dev-libs/libxml2`` on Gentoo since the entry has the\n``platform:gentoo`` profile.\n\nAdditionally, you can use ``platform:redhat`` or ``platform:suse`` to only\nmatch RedHat-like or SUSE-like distributions respectively as shown in the\nfollowing example::\n\n openssh-server [platform:redhat]\n openssh [platform:suse]\n\nIf you need to distinguish between operating systems where python2 or python3\nis the official interpreter, you can use `base-py2` and `base-py3` labels.\nKeep in mind that only one would be exposed for a specific operating system\neven if the system could support installation of multiple python versions::\n\n python3-lxml [(platform:redhat platform:base-py3)]\n python-lxml [(platform:redhat platform:base-py2)]\n\nThe example above will install lxml python modules on official python used\nby platform. Keep it mind that ``base-py[23]`` support is currently implemented\nonly on Debian, Ubuntu, RedHat flavours and MacOS.\n\nTo select Python3 development packages, you can use::\n\n python3-all-dev [platform:dpkg !platform:ubuntu-precise]\n python3-devel [platform:fedora]\n python34-devel [platform:centos]\n\nThis selects ``python3-all-dev`` on all Debian based distributions\nwith the exception of Ubuntu Precise, ``python3-devel`` on Fedora and\n``python34-devel`` on CentOS.\n\nTo select the curl package::\n\n curl [!platform:gentoo]\n net-misc/curl [platform:gentoo]\n\nThis selects the ``curl`` package on all distributions with the\nexception of Gentoo, and selects ``net-misc/curl`` on Gentoo only.\n\nTo select a package based on a group of profiles::\n\n ceph-common [ceph]\n python-rbd [(ceph glance)]\n\nThis selects the ``ceph-common`` package when the profile ``ceph`` is\nspecified. However, it will only select the ``python-rbd`` package when both\n``ceph`` and ``glance`` profiles are active.\n\nTo specify package versions::\n\n python >=3.7,<=3.8\n grep >=3.3\n\n # OR with a platform profile\n python [platform:brew] ==3.7.3\n\nFor a more comprehensive example check bindep.txt_ file that is used to\ntest bindep itself on multiple platforms.\n\n.. _bindep.txt: https://opendev.org/opendev/bindep/src/master/bindep/tests/bindep.txt\n\n\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Binary dependency utility",
"version": "2.11.0",
"project_urls": {
"Browse Source": "https://opendev.org/opendev/bindep",
"Bug Reporting": "https://storyboard.openstack.org/#!/project/opendev/bindep",
"Documentation": "https://docs.opendev.org/opendev/bindep",
"Git Clone URL": "https://opendev.org/opendev/bindep",
"Homepage": "https://docs.opendev.org/opendev/bindep",
"License Texts": "https://opendev.org/opendev/bindep/src/branch/master/LICENSE",
"Release Notes": "https://docs.opendev.org/opendev/bindep/latest/releasenotes.html"
},
"split_keywords": [
"binary",
"dependency",
"distribution",
"distro",
"package",
"commandline"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8945a1059b364ae3534e941950f21fbdceddef20e1aa4d17f373c375bcc1883",
"md5": "26c9410de12a40d67bfe60a45e06e86c",
"sha256": "6abe2f721e5388b518affb8bf8c8945977e75e88803e229799b3599a6da32b01"
},
"downloads": -1,
"filename": "bindep-2.11.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "26c9410de12a40d67bfe60a45e06e86c",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34037,
"upload_time": "2022-04-18T19:02:15",
"upload_time_iso_8601": "2022-04-18T19:02:15.239942Z",
"url": "https://files.pythonhosted.org/packages/f8/94/5a1059b364ae3534e941950f21fbdceddef20e1aa4d17f373c375bcc1883/bindep-2.11.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e89689d7f17c559dea2849d27365f53bd40f134056392db9e88a2590eb3dc29",
"md5": "4d086dd9d7ad35d5dee6b6d6ca5e972a",
"sha256": "acb2f259bce1fd1508873479609bbde5b9aae508378476a68d6b6a19002e7e2f"
},
"downloads": -1,
"filename": "bindep-2.11.0.tar.gz",
"has_sig": false,
"md5_digest": "4d086dd9d7ad35d5dee6b6d6ca5e972a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42317,
"upload_time": "2022-04-18T19:02:16",
"upload_time_iso_8601": "2022-04-18T19:02:16.902618Z",
"url": "https://files.pythonhosted.org/packages/8e/89/689d7f17c559dea2849d27365f53bd40f134056392db9e88a2590eb3dc29/bindep-2.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-04-18 19:02:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bindep"
}
JSON