PyWBEM Client - Contributing

Contributing

The PyWBEM Client project has its repository at https://github.com/pywbem/pywbem.

The maintainers all have day jobs, so its development is really a community effort. Contributions are always welcome!

If you want to contribute, you can do that in a number of areas:

  • Testing on new platforms (operating systems, Python implementations and versions)
  • Extending the unit test cases
  • Reporting bugs you encounter, on the issue tracker
  • Fixing bugs or implementing feature requests listed on the issue tracker
  • Doing things listed on the ToDo list

Development

This section provides some hints when you want to participate in the development of the PyWBEM Client. You can ignore it when you just want to use the PyWBEM Client and program against it.

First, create a local clone of the PyWBEM Git repository:

git clone git@github.com:pywbem/pywbem.git
cd pywbem

It is strongly recommended to use a virtual Python environment for each version of Python supported by PyWBEM:

mkvirtualenv -p python2.6 pywbem26
mkvirtualenv -p python2.7 pywbem27

As of the PyWBEM Client v0.8, its setup script (setup.py) establishes any Python prerequisites for its own development when invoked with the "develop" command. This needs to be done in each of the virtual Python environments that were set up for PyWBEM (do not use sudo, otherwise it will install into the system Python):

cd src
workon pywbem26
python setup.py develop
workon pywbem27
python setup.py develop

In addition, the setup script establishes any OS-level prerequisites for its own development when invoked with the "develop_os" command:

sudo python setup.py develop_os

The PyWBEM Client also provides a makefile. Invoking make without arguments will print the possible targets:

make

makefile for pywbem
Package version will be: 0.8.1
Uses the currently active Python environment: Python 27
Valid targets are (they do just what is stated, i.e. no automatic prereq targets):
  develop    - Prepare the development environment by installing prerequisites
  build      - Build the distribution archive: dist/pywbem-0.8/pywbem-0.8.1.tar.gz
  buildwin   - Build the Windows installable: dist/pywbem-0.8/pywbem-0.8.1.win-amd64.exe (requires Windows 64-bit)
  builddoc   - Build documentation in: build_doc
  check      - Run PyLint on sources and save results in: pylint.log
  install    - Install distribution archive to active Python environment
  test       - Run unit tests and save results in: test_27.log
  clean      - Remove any temporary files; ensure clean build start
  all        - Do everything locally (except publish/upload)
  upload     - build + upload the distribution archive to PyPI: dist/pywbem-0.8/pywbem-0.8.1.tar.gz
  publish    - builddoc + publish documentation to: ../pywbem.github.io/pywbem/doc/0.8.1/doc
  clobber    - Remove any build products

Testing

The PyWBEM Client has some amount of unit test cases. Invoke make test to build and install the PyWBEM Client and to run the unit test cases on the current operating system and the current Python environment.

Any help in completing the unit test cases is very welcome. If you feel like helping, search for occurrences of TODO in the Python source files in directory src/testsuite.

Test Matrix

The following table lists the environments in which the installation and the unit test cases are tested. The responsible person for a row should open issues if any tests are failing.

OS Type OS Name OS Version HW platform Python Version Responsible Remarks
Linux Arch (latest) i386, x86_64 2.7 Andreas Maier Under construction
Linux CentOS 6.7 i386, x86_64 2.6, 2.7 Andreas Maier Under construction
Linux CentOS 7 x86_64 2.6, 2.7 Andreas Maier Under construction
Linux Debian 8.2 i386, x86_64 2.7 Andreas Maier Under construction
Linux Fedora 20 x86_64 2.7 Andreas Maier Under construction
Linux Fedora 22 i386 2.7 Andreas Maier Under construction
Linux openSUSE 42 i386, x86_64 2.7 Andreas Maier Under construction
Linux Ubuntu 12.04 x86_64 2.6, 2.7 Andreas Maier Results on Travis CI
Linux Ubuntu 14.04 i386, x86_64 2.7 Andreas Maier Under construction
Windows Windows 7 x86_64 2.6, 2.7 Andreas Maier Under construction

Submitting code

The number of committers in the PyWBEM Client project is small and should stay small. If you are not a committer but want to submit code, you have two choices:

  • Pull request (preferred):

    Create a fork of the PyWBEM Client project (anywhere you have a public Git server, but there are some advantages doing that on GitHub), develop and commit your changes there, and once you are done, create a pull request targeting the PyWBEM Client project on GitHub (https://github.com/pywbem/pywbem).

    It is helpful if the pull request is related to an issue in the PyWBEM Client issue tracker.

    A good description on how to use git on GitHub forks, can be found in the GitHub Guide: Forking Projects.

  • Patch file:

    Work in your local Git clone, and once you are done, create a patch file reflecting your changes. Attach the patch file to an issue in the issue tracker. The commit level in the PyWBEM Client project on GitHub for which the patch file is intended should be indicated somehow.

Troubleshooting

As a PyWBEM developer, you may work on the development environment and not everything may work right all the time. Here is a list of things that have gone wrong in the past, and how to resolve them.

These issues should not occur for users of PyWBEM, because the PyWBEM setup script (setup.py) takes care of them.

  • Error when installing M2Crypto (e.g. as part of installing the PyWBEM Client):

    unable to execute swig: No such file or directory

    Root cause: This error occurs when M2Crypto is installed as part of the PyWBEM Client installation, and the swig command is not available.

    Solution: Install Swig (Linux: package swig). The M2Crypto installation requires at least Swig version 2.0. If your operating system does not provide for such a version, download and build Swig 2.0. Note that this is done automatically by the "develop" and "install" commands of the setup script of the PyWBEM Client.

  • Error when installing M2Crypto (e.g. as part of installing PyWBEM):

    swig error : Unrecognized option -builtin

    Root cause: This error occurs when M2Crypto is installed as part of the PyWBEM Client installation, and the version of swig is not sufficient. The M2Crypto installation requires at least Swig version 2.0.

    Solution: Update your version of Swig to at least 2.0. If your operating system does not provide for such a version, download and build Swig 2.0. Note that this is done automatically by the "develop_os" and "install_os" commands of the setup script of the PyWBEM Client.

  • Error when building Swig:

    configure: error: Cannot find pcre-config script from PCRE (Perl Compatible Regular Expressions) library package.

    Root cause: The PCRE development package is not installed.

    Solution: Install the PCRE development package:

    sudo yum install pcre-devel         # if RedHat-based
sudo apt-get install pcre-devel     # if Debian-based
sudo zypper install pcre-devel      # if SUSE-based

  • Error when installing M2Crypto (e.g. as part of installing PyWBEM):

    SWIG/_m2crypto.i:31: Error: Unable to find 'openssl/opensslv.h'
    SWIG/_m2crypto.i:45: Error: Unable to find 'openssl/safestack.h'
    SWIG/_evp.i:12: Error: Unable to find 'openssl/opensslconf.h'
    SWIG/_ec.i:7: Error: Unable to find 'openssl/opensslconf.h'

    Root cause: The OpenSSL development package is not installed.

    Solution: Install the OpenSSL development package:

    sudo yum install openssl-devel      # if RedHat-based
sudo apt-get install libssl-devel   # if Debian-based
sudo zypper install openssl-devel   # if SUSE-based

  • Note that installing the PyWBEM Client to the system Python invokes the M2Crypto build also under root permissions, so the new Swig version needs to be available via the PATH of root, in this case.

    Verify that the new version is available both for your userid and for root:

    swig -version
sudo swig -version