.. _installation:

.. |space| unicode:: 0xA0 .. nbsp

**********************************
Installing the Driver Module
**********************************

**Prerequisites**
    The keysight_kt34400 driver Python module requires the following prerequisites:

    **Operating System**

    - Windows - Windows 7 SP1, Windows 8.1, Windows 10 (32 or 64-bit)
    - Linux (64-bit)
        - CentOS 7.1, 7.2, 7.3, 7.4, 7.5, 7.6 
        - Red Hat 7.1,7.2, 7.3, 7.4, 7.5, 7.6
        - Ubuntu 16.04, 18.04
		
        Note: Newer Linux versions may be used but may not support connecting via USBTMC or USB-to-GPIB converter per Keysight IO Libraries Suite kernel driver availability.

    **Python 3.6** or newer

    .. raw:: html

        <ul><li>
        Windows - <a href="https://www.python.org/downloads/windows/" target="_blank">Python for Windows</a> installer comes in 32-bit (x86) or 64-bit (x86-64) versions.</br>
        &nbsp; &nbsp; Note: When installing Python, enable the "Add Python <version> to PATH" option which is NOT checked by default.
        Multiple versions of Python can be installed.  If multiple versions are installed, 
        whichever one is listed first in your system <i>Path</i> environment variable will be used by the driver.
        </li>
        <li>
        Linux - Almost all Linux distributions come with Python installed.
        To check, open a terminal and enter: &nbsp; <code style="font-size: 100%;">python3&nbsp;--version</code> &nbsp; &nbsp;
        If not found or version < 3.6 install per your Linux distribution. &nbsp; Also required:</br>
        &nbsp; &nbsp; pip3 - Check with: &nbsp; <code style="font-size: 100%;">pip3&nbsp;--version</code></br>
        &nbsp; &nbsp; python3-devel (CentOs) - Check with: &nbsp; <code style="font-size: 100%;">yum list installed python3*devel*</code></br>
        &nbsp; &nbsp; python3.6-dev (RH/Ubuntu) - Check with: &nbsp; <code style="font-size: 100%;">apt list --installed | grep python3.6-dev</code>
        </li></ul>


    **C++ Compiler**

    .. raw:: html

        A C++ compiler is required to build and install the driver Python module.  If needed, install one of the following:
        <ul>
        <li>Windows - MSVC compiler.  Install <a href="https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2019+rc" target="_blank">Visual Studio</a>
        (any edition) with "Desktop development with C++" workload selected &nbsp;OR&nbsp; if full VS ADE not needed, 
        <a href="https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019" target="_blank">Build Tools for Visual Studio</a>
        (command line interface) with "C++ build tools" workload selected.</li>

        <li>Linux - GCC 9, the GNU compiler collection.  Almost all Linux distributions come with GCC installed.
        To check, open a terminal and enter: &nbsp; <code style="font-size: 100%;">gcc&nbsp;--version</code> &nbsp; &nbsp;
        If not found or version < 9.0 install per your Linux distribution.</li>
        </ul>


    **CMake 3.16** or newer

    .. raw:: html

        CMake tools are used to build and install the driver Python module.  If needed, install the latest stable binary 
        distribution for Windows or Linux from <a href="https://cmake.org/download/" target="_blank">CMake.org</a>. &nbsp;
        To check, from a Windows command prompt or Linux terminal, enter: &nbsp; <code style="font-size: 100%;">cmake&nbsp;--version</code>

    **VISA**

    .. raw:: html

        The driver module uses VISA to communicate with the instrument. Any compliant implementation is acceptable.
        The latest version of <a href="https://www.keysight.com/find/iosuite" target="_blank">Keysight IO Libraries Suite</a>
        is recommended, includes VISA, and supports Windows or Linux.</br>&nbsp;


**Installing the Driver Module Package**

    The Python module source archive, keysight_kt34400-2.1.2.tar.gz, is available in the same folder as this HTML Help archive.
    Package Installer for Python (pip), which is included with Python, uses this file to build and install the driver module for 
    the OS and Python version in use on your machine in a single operation.  

    To build and install the keysight_kt34400 module execute the following command, from a Windows command prompt or Linux
    terminal in the same folder as the module source archive file:

        ``pip install keysight_kt34400-2.1.2.tar.gz``

    :Note:
        On Linux use: ``pip3`` |space| |space|
        pip only installs the module for the currently in use version of Python (first in your env *Path*).  If you install a new
        version of Python or edit your *Path* order, you must run pip again (from a new command prompt) to install the module for 
        the new, in use version of Python.


**Installing on Multiple Systems**

    Optionally, you can create a binary 'wheel' file distribution from the source module archive that can be easily installed on
    multiple machines.  The additional machines do not need the C++ compiler or CMake requirements to install the pre-built binary
    wheel file distribution.  Other than Python and pip, the only requirement is that the target machines must use the same
    operating system and version of Python as the machine used to create the wheel file.

    To create a wheel file in the current directory use:
        ``pip wheel --no-deps keysight_kt34400-2.1.2.tar.gz``

    To install the new wheel file use:
        ``pip install keysight_kt34400-2.1.2-cp<ver>-cp<ver>-<OS>.whl``


**Uninstalling the Driver Module Package**

    To uninstall the driver module use the 'uninstall' option with the module name as in:
        ``pip uninstall keysight_kt34400``


**Viewing Installed Module Information**

    To view a list of all installed modules use the 'list' option as in:    
        ``pip list``

    To view detailed module information use the 'show' option with the module name as in:
        ``pip show keysight_kt34400``
