/catkin_virtualenv

Bundle python requirements in a catkin package via virtualenv

Primary LanguagePython

catkin_virtualenv

License: GPL v2

Build Status

This package provides a mechanism to:

  • export python library requirements in requirements.txt format via package.xml.
  • bundle a virtualenv within a catkin package, inheriting requirements from any dependencies.
  • wrap python scripts and tests in a catkin package with a virtualenv loader.

At build time, CMake macros provided by this package will create a virtualenv inside the devel space, and create wrapper scripts for any Python scripts in the package. Both will be included in any associated bloom artifacts.

This library is GPL licensed due to the inclusion of dh_virtualenv.

For general help, please check the FAQ. Report bugs on the issue tracker.

Exporting python requirements:

The package containing python modules with external library dependencies should define a requirements.txt:

GitPython>=2.1.5
psutil>=5.2.2
wrapt>=1.10.10

Add an export to package.xml:

<export>
  <pip_requirements>requirements.txt</pip_requirements>
</export>

Make sure to install the requirements file in CMakeLists.txt:

install(FILES requirements.txt
  DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION})

Bundling virtualenv:

It's possible to bundle all of a catkin package's python requirements, as well as those of its catkin dependencies, into a virtualenv. This process will also override the standard catkin_install_python macro to wrap a virtualenv loader around the specified python scripts.

Add an build dependency to package.xml:

<build_depend>catkin_virtualenv</build_depend>

In CMakeLists.txt:

# Make sure to find-package `catkin_virtualenv`
find_package(catkin REQUIRED ... catkin_virtualenv ...)

# Must be called before catkin_generate_virtualenv
catkin_package()

# Generate the virtualenv:
catkin_generate_virtualenv()

# Make sure your python executables are installed using `catkin_install_python`:
catkin_install_python(
  PROGRAMS
    scripts/do_python_things
  DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

Departing from convention, if these scripts are executable, catkin build will make them non-executable. This is because catkin_install_python will now generate new wrapper scripts into the devel and install space that bootstrap the virtualenv and rosrun gets confused if there's two executable scripts by the same name.

Unit and integration tests will automatically pick up the virtualenv as well. The only change is to add a dependency from the test target to the virtualenv target:

if(CATKIN_ENABLE_TESTING)

  # nosetests
  catkin_add_nosetests(test
    DEPENDENCIES ${PROJECT_NAME}_generate_virtualenv
  )

  # rostests
  find_package(rostest)
  catkin_install_python(
    PROGRAMS
      test/test_script
    DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

  add_rostest(test/run_test_script.test
    DEPENDENCIES ${PROJECT_NAME}_generate_virtualenv
  )
)

Additional CMake Options:

The following options are supported by catkin_generate_virtualenv():

catkin_generate_virtualenv(
  # Select an alternative major version of the python interpreter - it must be installed on the system.
  PYTHON_VERSION_MAJOR 3  # Default 2

  # Choose not to use underlying system packages. This excludes any python packages installed by apt or system-pip from the environment.
  USE_SYSTEM_PACKAGES FALSE  # Default TRUE

  # Disable including pip requirements from catkin dependencies of this package.
  ISOLATE_REQUIREMENTS TRUE  # Default FALSE
)