Skip to content

Commit

Permalink
Docs: Fixed installation on Windows.
Browse files Browse the repository at this point in the history 
Details:

- The installation for Windows documented the use of `pip install pywbem`.
  This was incorrect because pip now uses the package metadata and
  attempts to install the `M2Crypto` package.

- The installation for Windows did not document the prerequisite
  Python packages, specifically the `wheel` package which lead
  to an error during M2CryptoWin32 installation. It now documents
  this prerequisite, and adds a trouble shooting item for this.

Signed-off-by: Andreas Maier <maiera@de.ibm.com>
  • Loading branch information
@andy-maier
andy-maier committed Feb 11, 2018
1 parent 2b9ebb6 commit cb7f8d3
Show file tree
Hide file tree
Showing 5 changed files with 172 additions and 44 deletions.
22 changes: 22 additions & 0 deletions docs/appendix.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,28 @@ installs the necessary Python SDK package for C/C++ (or displays its package
name). On RHEL, the missing package is `python-dev`.
For more details, see :ref:`Prerequisite operating system packages`.


Pip install of M2CryptoWin32 fails with option not recognized
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In native Windows with a 32-bit version of Python, the following error has been
observed when attempting to install the `M2CryptoWin32` package::

> pip install M2CryptoWin32
. . .
usage: -c [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: -c --help [cmd1 cmd2 ...]
or: -c --help-commands
or: -c cmd --help
error: option --single-version-externally-managed not recognized

This has been reported to be fixed by installing the Python `wheel` package
into the active Python environment, and repeating the installation::

> pip install wheel
> pip install M2CryptoWin32


.. _'Glossary`:

Glossary
Expand Down
6 changes: 4 additions & 2 deletions docs/changes.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,11 @@ pywbem v0.11.1

Released: 2018-mm-dd

Enhancements
^^^^^^^^^^^^
Bug fixes
^^^^^^^^^

* Docs: Fixed the descriprion of the pywbem installation on Windows, and added
trouble shooting information.


pywbem v0.11.0
Expand Down
58 changes: 58 additions & 0 deletions docs/development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,64 @@ Python environment. The command ``make help`` (or just ``make``) displays a
list of valid Make targets and a short description of what each target does.


.. _`Manual setup on Windows`:

Manual setup on Windows
^^^^^^^^^^^^^^^^^^^^^^^

For development of pywbem, it is recommended to use one of the Unix-like
environments on Windows (such as CygWin, MinGW, Babun, or Gow). The pywbem
tests that run on the Appveyor CI use CygWin.

Note that Unix-like environments on Windows bring their own Python, so double
check that the active Python environment is the one you want to install to.

The development environment needs the ``xmllint`` utility and the ``lxml``
Python package.

The ``lxml`` Python package for Windows meanwhile comes as a binary wheel
archive that includes all of its dependencies, so it has no additional
dependencies you would need to take care about.

The ``xmllint`` utility is part of CygWin and likely also part of the other
Unix-like environments.


.. _`Prerequisite operating system packages for development`:

Prerequisite operating system packages for development
------------------------------------------------------

The following table lists the prerequisite operating system packages along with
their version requirements for development of pywbem, for the supported
operating systems and Linux distributions.

The prerequisite operating system packages for installing and running pywbem
are also needed for development, and can be found in section
:ref:`Prerequisite operating system packages for install`.

This section is just for information. These packages will be installed as part
of the steps described in :ref:`Setting up the development environment`.

+--------------------------+--------------------+----------------------+-------+
| Op.system / Distribution | Package name | Version requirements | Notes |
+==========================+====================+======================+=======+
| Linux RedHat family | | | |
| (RHEL, CentOS, Fedora) | | | |
+--------------------------+--------------------+----------------------+-------+
| Linux Debian family | | | |
| (Ubuntu, Debian, | | | |
| LinuxMint) | | | |
+--------------------------+--------------------+----------------------+-------+
| Linux SUSE family | | | |
| (SLES, openSUSE) | | | |
+--------------------------+--------------------+----------------------+-------+
| OS-X | | | |
+--------------------------+--------------------+----------------------+-------+
| Windows | xmllint | | |
+--------------------------+--------------------+----------------------+-------+


.. _`Building the documentation`:

Building the documentation
Expand Down
122 changes: 80 additions & 42 deletions docs/intro.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,38 @@ approaches shown below:
$ pip install git+https://github.com/pywbem/pywbem.git@master
Special note for installing on Windows:

* The commands shown above do not work in version 0.11 of pywbem because Pip
does not invoke pywbem's `setup.py` and instead goes by the package metadata.
Therefore, installation on Windows (both for native Windows and in UNIX-like
environments on Windows such as CygWin) needs to be done as follows:

- Clone the Git repository of pywbem and check out the stable branch for the
desired version (e.g. branch `stable_0.11` for the latest fix version
0.11.x):

.. code-block:: text
> git clone https://github.com/pywbem/pywbem.git
> cd pywbem
> git checkout stable_0.11
- Install the Python prerequsite packages for starting the installation of
pywbem, making sure they are at the minimum required version:

.. code-block:: text
> pip install "setuptools>=0.9.8"
> pip install "wheel>=0.24.0"
> pip install "pip>=8.1"
- Install the checked-out version of pywbem using its `setup.py`:

.. code-block:: text
> python setup.py install
These examples install pywbem and its prerequisite Python packages into the
currently active Python environment. By default, the system Python environment
is active. This is probably the right choice if you just want to use the
Expand Down Expand Up @@ -201,48 +233,54 @@ done, and documents these packages.
* For pywbem before 0.8: Install the required packages manually, based upon
the table shown below.

For manual installation of the prerequisite operating system packages, or for
including pywbem in distributions, the following table lists the packages and
their version requirements for the Linux distributions that are supported
by the scripts:

+----------------------------+---------------------+--------------------------+
| Distributions | Package name | Version requirements |
+============================+=====================+==========================+
| RedHat, CentOS, Fedora | openssl-devel | >=1.0.1 |
| +---------------------+--------------------------+
| | gcc-c++ | >=4.4 |
| +---------------------+--------------------------+
| | python-devel | for Python 2.6, 2.7 |
| +---------------------+--------------------------+
| | python3{N}u-devel | for Python 3.{N} from IUS|
| | | community (python3{N}u) |
| +---------------------+--------------------------+
| | python3{N}-devel | for Python 3.{N} not from|
| | | IUS (python3{N}) |
| +---------------------+--------------------------+
| | swig | >=2.0 |
+----------------------------+---------------------+--------------------------+
| Ubuntu, Debian, LinuxMint | libssl-dev | >=1.0.1 |
| +---------------------+--------------------------+
| | g++ | >=4.4 |
| +---------------------+--------------------------+
| | python-dev | for Python 2.6, 2.7 |
| +---------------------+--------------------------+
| | python3-dev | for Python 3.4 - 3.6 |
| +---------------------+--------------------------+
| | swig | >=2.0 |
+----------------------------+---------------------+--------------------------+
| SLES, OpenSUSE | openssl-devel | >=1.0.1 |
| +---------------------+--------------------------+
| | gcc-c++ | >=4.4 |
| +---------------------+--------------------------+
| | python-devel | for Python 2.6, 2.7 |
| +---------------------+--------------------------+
| | python3-devel | for Python 3.4 - 3.6 |
| +---------------------+--------------------------+
| | swig | >=2.0 |
+----------------------------+---------------------+--------------------------+
The following table lists the prerequisite operating system packages along with
their version requirements for installing and running pywbem, for the
supported operating systems and Linux distributions.

The prerequisite operating system packages for developing pywbem are not listed
in this table; you can find them in section
:ref:`Prerequisite operating system packages for development`.

+--------------------------+--------------------+----------------------+-------+
| Op.system / Distribution | Package name | Version requirements | Notes |
+==========================+====================+======================+=======+
| Linux RedHat family | openssl-devel | >=1.0.1 | py2 |
| (RHEL, CentOS, Fedora) +--------------------+----------------------+-------+
| | python-devel | for your Python 2.x | py2 |
| +--------------------+----------------------+-------+
| | gcc-c++ | >=4.4 | py2 |
| +--------------------+----------------------+-------+
| | swig | >=2.0 | py2 |
+--------------------------+--------------------+----------------------+-------+
| Linux Debian family | libssl-dev | >=1.0.1 | py2 |
| (Ubuntu, Debian, +--------------------+----------------------+-------+
| LinuxMint) | python-dev | for your Python 2.x | py2 |
| +--------------------+----------------------+-------+
| | g++ | >=4.4 | py2 |
| +--------------------+----------------------+-------+
| | swig | >=2.0 | py2 |
+--------------------------+--------------------+----------------------+-------+
| Linux SUSE family | openssl-devel | >=1.0.1 | py2 |
| (SLES, openSUSE) +--------------------+----------------------+-------+
| | python-devel | for your Python 2.x | py2 |
| +--------------------+----------------------+-------+
| | gcc-c++ | >=4.4 | py2 |
| +--------------------+----------------------+-------+
| | swig | >=2.0 | py2 |
+--------------------------+--------------------+----------------------+-------+
| OS-X | openssl | >=1.0.1 | py2 |
| +--------------------+----------------------+-------+
| | gcc | >=4.4 | py2 |
| +--------------------+----------------------+-------+
| | swig | >=2.0 | py2 |
+--------------------------+--------------------+----------------------+-------+
| Windows | None | | |
+--------------------------+--------------------+----------------------+-------+

Notes:

* py2: Only needed with Python 2 (not needed with Python 3).


On some distributions, the ``swig`` package is not available in the required
version. In such cases, it can be built from its sources, as follows:
Expand Down
8 changes: 8 additions & 0 deletions pywbem_os_setup.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,14 @@ elif [[ "$distro_family" == "suse" ]]; then
sudo zypper -y install python${py_mn}-devel # for M2Crypto installation
fi

elif [[ "$distro_family" == "windows" ]]; then

echo "Info: For just installing and running pywbem on Windows, no additional"
echo " OS-level packages are needed."
echo "Warning: For developing pywbem, some required OS-level packages need to be"
echo " installed manually; see the 'Development' chapter of the documentation"
echo " for instructions."

else

echo "Error: Installation of OS-level packages not supported on platform ${platform}."
Expand Down

0 comments on commit cb7f8d3

Please sign in to comment.