
.. _INSTALL:

*******
Install
*******

License
=======

:ref:`Modified-Artistic-License-2.0 <MODIFIED_ARTISTIC_LICENSE_20>` = :ref:`Artistic-License-2.0 <ARTISTIC_LICENSE_20>` + :ref:`Forced-Fairplay-Constraints <LICENSES_AMENDMENTS>` 

* Artistic-License-2.0(base license): :ref:`ArtisticLicense20 <ARTISTIC_LICENSE_20>`

* Forced-Fairplay-Constraints(amendments): :ref:`licenses-amendments <LICENSES_AMENDMENTS>` 

   
Copyright (C) 2018-2019 Arno-Can Uestuensoez @Ingenieurbuero Arno-Can Uestuensoez

Resources
=========

   .. raw:: html
   
      <div class="indextab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">
   
   +--------------+-------------+----------------------------------------------+
   | prerequisite | reference   | description                                  |
   +==============+=============+==============================================+
   | Download     | PyPI        | https://pypi.python.org/pypi/setupjavax      |
   +--------------+-------------+----------------------------------------------+
   |              | Sourceforge | https://sourceforge.net/projects/setupjavax/ |
   +--------------+-------------+----------------------------------------------+
   |              | github.com  | https://github.com/ArnoCan/setupjavax/       |
   +--------------+-------------+----------------------------------------------+
   | Documents    | sourceforge | https://setupjavax.sourceforge.io/           |
   +--------------+-------------+----------------------------------------------+

   
   .. raw:: html
   
      </div>
      </div>
      </div>

Online Help
===========

For help on extensions to standard options call online context-help:

   .. parsed-literal::

      python setup.py **--help-setupjavax**

Install from PyPI.org
=====================

Install from PyPI.org by calling:

   .. parsed-literal::
   
      pip install setupjavax

Once installed any supported implementation will work.

The runtime package is distinct from the source package, which is also called the SDK - Sofware Developemnt Kit.
The prerequisites of both are frequently slightly different.
For the *SDK* and the installation from sources including offline-installation see following sections.

.. _INSTALL_PREREQUISITES:

Prerequisites
=============

   .. raw:: html
   
      <div class="indextab">
      <div class="autocoltab">
   
   +--------------+--------------------------+------------------------------------------------------------+
   | prerequisite | reference                | description                                                |
   +==============+==========================+============================================================+
   | Runtime      | Python Syntax            | Python2.7+, Python3.5+,                                    |
   +--------------+--------------------------+------------------------------------------------------------+
   |              | Python Distributions     | CPython, PyPy, Jython, IPython, IronPython                 |
   +              +                          +                                                            +
   |              |                          | MicroPython, CircuitPython                                 |
   +              +                          +                                                            +
   |              |                          | Jython is verified with: jdk-8u131, jdk-8u202, jdk-11u2    |
   +--------------+--------------------------+------------------------------------------------------------+
   |              | OS-Server/WS/Notebook    | AlpineLinux, ArchLinux, CentOS, Debian, Fedora,            |
   +              +                          +                                                            +
   |              |                          | Gentoo, LinuxMint, OpenSUSE, OracleLinux, RHEL,            |
   +              +                          +                                                            +
   |              |                          | Slackware, SLES, Ubuntu                                    |
   +              +                          +                                                            +
   |              |                          | Minix3                                                     |
   +              +                          +                                                            +
   |              |                          | FreeBSD, NetBSD, OpenBSD                                   |
   +              +                          +                                                            +
   |              |                          | DragonFlyBSD, GostBSD, NomadBSD, TrueOS                    |
   +              +                          +                                                            +
   |              |                          | SnowLeopard                                                |
   +              +                          +                                                            +
   |              |                          | Solaris(10, 11)                                            |
   +              +                          +                                                            +
   |              |                          | Cygwin                                                     |
   +              +                          +                                                            +
   |              |                          | ReactOS                                                    |
   +              +                          +                                                            +
   |              |                          | Windows10, Windows8.1, Windows7, WindowsXP, W2000WS        |
   +              +                          +                                                            +
   |              |                          | Windows2019, Windows2016                                   |
   +              +                          +                                                            +
   |              |                          | Windows2012, Windows2008, Windows2000                      |
   +              +--------------------------+------------------------------------------------------------+
   |              | OS-Special               | OpenWRT, KaliLinux, pfSense                                |
   +              +                          +                                                            +
   |              |                          | BlackArch, ParrotOS, Pentoo                                |
   +              +--------------------------+------------------------------------------------------------+
   |              | OS-Devices-altarch - ARM | AlpineLinux, ArchLinux, Armbian, BlackArchLinux, CentOS,   |
   +              +                          +                                                            +
   |              |                          | KaliLinux, OpenWRT, ParrotOS, Raspbian                     |
   +              +                          +                                                            +
   |              |                          | FreeBSD, NetBSD, OpenBSD                                   |
   +              +                          +                                                            +
   |              |                          | Windows10IoT                                               |
   +              +--------------------------+------------------------------------------------------------+
   |              | Soon / TBD               | VMWare-ESXi, XenServer, KVM, Docker, Kubernetes, OpenShift |
   +              +                          +                                                            +
   |              |                          | Hyper-V-2016, Hyper-V-2012, Hyper-V-2008                   |
   +              +                          +                                                            +
   |              |                          | AWS, Azure, Google-Cloud, IBM-Cloud                        |
   +--------------+--------------------------+------------------------------------------------------------+
   | Packages     | Python                   | pyfilesysobjects, pyplatformids, PyPythonids               |
   |              |                          | (jsonschema), (ujson/ultrajson)                            |
   +              +--------------------------+------------------------------------------------------------+
   |              | Jython                   | Supports Java integration, tested with:                    |
   +              +                          +                                                            +
   |              |                          | rte/jdk-8u131, rte/jdk-8u202, rte/jdk-11u2                 |
   +              +                          +                                                            +
   |              |                          | on WindowsNT - optional: jna-5.0.0                         |
   +--------------+--------------------------+------------------------------------------------------------+
   |              | Cygwin                   | cygwinreg                                                  |
   +              +--------------------------+------------------------------------------------------------+
   | SDK          | Python                   | CPython 2.7+, CPython 3.5+                                 |
   +--------------+--------------------------+------------------------------------------------------------+
   |              | Java                     | jdk >= 1.8                                                 |
   +              +                          +                                                            +
   |              |                          | on WindowsNT - mandatory: jna-5.0.0                        |
   +              +--------------------------+------------------------------------------------------------+
   |              | bash                     | bash-4.x                                                   |
   +              +--------------------------+------------------------------------------------------------+
   |              | documents                | Sphinx >=1.4, Epydoc >=4 or Apydoc >=4 (1)                 |
   +              +--------------------------+------------------------------------------------------------+
   |              | OS                       | Linux, Darwin, BSD, UNIX, Cygwin, Windows10                |
   +--------------+--------------------------+------------------------------------------------------------+
   
   .. raw:: html
   
      </div>
      </div>

   (1): Epydoc(4.0) and Apydoc are going to be released to public soon.


Install Procedures for Sources
==============================
The installation process itself is verified for *CPython*, it requires the *setuptools* package and
will than work with others too.

From source:

   .. parsed-literal::

      python setup.py install

Once installed any supported implementation will work.

The runtime package is distinct from the source package, which is also called the SDK - Sofware Developemnt Kit.
The prerequisites of both are frequently slightly different.


   .. raw:: html
   
      <div class="indextab">
      <div class="autocoltab">
                                                                                           
   +-------------+-------------------------------------------------------------------------+
   | environment | description                                                             |
   +=============+=========================================================================+
   | Runtime     | Standard procedure online local install e.g. into virtual environment:  |
   +             +                                                                         +
   |             | * *python setup.py install*                                             |
   +             +                                                                         +
   |             | Standard procedure online local install into user home:                 |
   +             +                                                                         +
   |             | * *python setup.py install --user*                                      |
   +             +                                                                         +
   |             | Custom procedure offline by:                                            |
   +             +                                                                         +
   |             | * *python setup.py install --user --offline*                            |
   +-------------+-------------------------------------------------------------------------+
   | SDK         | Required for document creation, add '--sdk' option, checks build tools: |
   +             +                                                                         +
   |             | * *python setup.py install --sdk*                                       |
   +             +                                                                         +
   |             | Creation of documents, requires Sphinx including 'sphinx-apidoc',       |
   |             | and Epydoc:                                                             |
   +             +                                                                         +
   |             | * *python setup.py build_doc install_project_doc install_doc*           |
   +             +                                                                         +
   |             | Compilation of Java modules for Jython, see help for suboptions.        |
   |             | The package contains the compiled standard class files,                 |
   |             | this call could be used for alternative JRE.                            |
   +             +                                                                         +
   |             | * *python setup.py build_java*                                          |
   +-------------+-------------------------------------------------------------------------+

   .. raw:: html
   
      </div>
      </div>

.. _TESTED_OS_PYTHON:

Tested Platforms
================

Some default installations, e.g. *PyPy* on *OpenBSD6.3* do not work from the box, but
perfectly when a specific virtual environment is created.
Thus the number of actual tests is even larger.
You may adapt it appropriately - or with some professional support from the author.

Standard Platforms
------------------
The tested Python implementations on the supported OS on standard platforms are:

   .. raw:: html
   
      <div class="teststatetab">
      <div class="autocoltab">

   +-------------------------+-----------+---------+------------+-----------+------+
   | OS-distribution         | Python implementations                              |
   +-------------------------+-----------+---------+------------+-----------+------+
   |                         | CPython   | IPython | IronPython | Jython(1) | PyPy |
   +=========================+===========+=========+============+===========+======+
   | AlpineLinux-3.9         | X         | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | AlpineLinux-3.10        | X         | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | ArchLinux-2019.04.01    | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | CentOS-6                | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | CentOS-7                | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | CentOS-8                | asap      |asap     | --         | asap      | asap |
   +-------------------------+-----------+---------+------------+-----------+------+
   | CoreOS                  | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Cygwin                  | \*        | \*      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Debian-9                | \*        | X       | --         | X         | X    |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Debian-10               | \*        | X       | --         | X         | X    |
   +-------------------------+-----------+---------+------------+-----------+------+
   | DragonFlyBSD-5.4.0      | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Fedora-27               | OK        | OK      | --         | OK        | OK   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Fedora-28               | OK        | OK      | --         | OK        | OK   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Fedora-29               | OK        | OK      | --         | OK        | OK   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Fedora-30               | OK        | OK      | --         | OK        | OK   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | FreeBSD-11.2            | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Gentoo-12.1             |           | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | GhostBSD-19.04          |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | LinuxMint-19.1          |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Minix3                  |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | NetBSD-7.2              |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | NetBSD-8.0              |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OpenBSD-6.4             | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OpenBSD-6.5             | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OpenSUSE-15.1           | \*        | \*      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OpenSUSE-42.3           | \*        | \*      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OracleLinux-OEL7        | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | OracleLinux-OEL8        | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | ReactOS-0.4.11          | \*        | \*      | \*         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | RHEL - RHEL7            | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | RHEL - RHEL8            | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | SLES                    |           |         | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Slackware-14.2          | \*        | --      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | SnowLeopard             | \*        | \*      | --         | \*        | (--) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Solaris10               | \*        | \*      | --         | --        | --   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Solaris11               | \*        | \*      | --         | \*        | (--) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | TrueOS-18.12            |           |         | --         |           |      |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Ubuntu-16.04            | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Ubuntu-18.04            | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Ubuntu-18.10            | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Ubuntu-19.04            | \*        | \*      | --         | \*        | \*   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | WindowsXP               | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows7Ultimate        | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows10Home           | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows10Professional   | OK        | OK      | OK         | OK        | OK   |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2008             | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2008R2           | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2012             | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2012R2           | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2016S            | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2016SE           | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2019S            | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+
   | Windows2019SE           | \*        | \*      | \*         | \*        | (\*) |
   +-------------------------+-----------+---------+------------+-----------+------+

   .. raw:: html
   
      </div>
      </div>

   **(1)**: Verified *Jython-2.7.0* with: jdk-8u131, jdk-8u181, jdk-8u202, jdk-11u2

See also "Supported Standard OS and Dists" [platformids]_.


Security and Network
--------------------
   
The tested Python implementations on the supported Security and Network  platforms
including physical, virtual, and embedded platforms are:

   .. raw:: html
   
      <div class="teststatetab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-----------------------+-----------+---------+------------+-----------+------+
   | OS-distribution       | Python implementations                              |
   +-----------------------+-----------+---------+------------+-----------+------+
   |                       | CPython   | IPython | IronPython | Jython(1) | PyPy |
   +=======================+===========+=========+============+===========+======+
   | BlackArchLinux        | X         | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | KaliLinux             | \*        | X       | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | KaliLinux ARM         | \*        | X       | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenBSD               | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenBSD - ARM         | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenWRT               | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenWRT - ARM         | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenWRT - MIPS        | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | ParrotOS              | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | Pentoo                | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | pfsense               | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+

   .. raw:: html
   
      </div>
      </div>
      </div>

   **(1)**: Verified *Jython-2.7.0* with: jdk-8u131, jdk-8u202, jdk-11u2

See also "Security and Network Systems" [platformids]_.


Embedded and IoT
----------------
   
The tested Python implementations on the supported OS on embedded and IoT platforms
with alternative architecture are - RaspberryPI and Asus-TinkerBoard:

   .. raw:: html
   
      <div class="teststatetab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-----------------------+-----------+---------+------------+-----------+------+
   | OS-distribution       | Python implementations                              |
   +-----------------------+-----------+---------+------------+-----------+------+
   |                       | CPython   | IPython | IronPython | Jython(1) | PyPy |
   +=======================+===========+=========+============+===========+======+
   | AlpineLinux           | X         | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | ArchLinux-altarch     | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | Armbian               | \*        | \*      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | CentOS-7-altarch      | \*        | --      | --         | --        | --   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | CircuitPython         |           |         | --         |           |      |
   +-----------------------+-----------+---------+------------+-----------+------+
   | Fedora                | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | FreeBSD               | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | MicroPython           |           |         | --         |           |      |
   +-----------------------+-----------+---------+------------+-----------+------+
   | NetBSD                |           |         | --         |           |      |
   +-----------------------+-----------+---------+------------+-----------+------+
   | OpenBSD               | \*        | \*      | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | Raspbian              | \*        | X       | --         | \*        | \*   |
   +-----------------------+-----------+---------+------------+-----------+------+
   | Windows10IoT          | \*        | \*      | \*         | \*        | (\*) |
   +-----------------------+-----------+---------+------------+-----------+------+

   .. raw:: html
   
      </div>
      </div>
      </div>

   **(1)**: Verified *Jython-2.7.0* with: jdk-8u131, jdk-8u202, jdk-11u2

See also "Embedded Systems and IoT" [platformids]_.



Windows WSL-1.0
---------------
   
The tested within WSL-1.0:

   .. raw:: html
   
      <div class="teststatetab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | OS-distribution       | Python implementations                                                     |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   |                       | CPython   | IPython | IronPython.exe(3) | IronPython(2) | Jython(1) | PyPy |
   +=======================+===========+=========+===================+===============+===========+======+
   | AlpineLinux           | OK        | OK      | OK                | --            | --        | --   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | Debian                | OK        | OK      | OK                | \*            | OK        | OK   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | KaliLinux             | OK        | OK      | OK                | --            | OK        | OK   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | openSUSE              | OK        | OK      | OK                | --            | OK        | OK   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | SLES                  | OK        | OK      | OK                | --            | --        | --   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+
   | Ubuntu                | OK        | OK      | OK                | --            | OK        | OK   |
   +-----------------------+-----------+---------+-------------------+---------------+-----------+------+

   .. raw:: html
   
      </div>
      </div>
      </div>

   **(1)**: Verified *Jython-2.7.0* with: jdk-8u131, jdk-8u202, jdk-11u2

   **(2)**: IronPython - Call of the native IronPython as an Linux executable, e.g. as pre-alpha fro Debian, see [IronPython]_. 

   **(3)**: IronPython.exe - Call of the Windows EXE from Linux running within the WSL, see [WINWSL]_.
            Executes within native *NT* environment, thus executes within runtime-context *ostype == RTE_NT*.

App Frameworks
--------------
special test results are available soon

   .. raw:: html
   
      <div class="teststatetab">
      <div class="nonbreakheadtab">
      <div class="autocoltab">

   +----------------------------------+------------------------+---------+------------+--------+------+
   | Application Framework            | Python implementations                                        |
   +----------------------------------+------------------------+---------+------------+--------+------+
   |                                  | CPython                | IPython | IronPython | Jython | PyPy |
   +==================================+========================+=========+============+========+======+
   | IBM WebSphere Application Server | --                     | --      | --         | \*     | --   |
   +----------------------------------+------------------------+---------+------------+--------+------+
   | JBoss Application Server         | --                     | --      | --         | \*     | --   |
   +----------------------------------+------------------------+---------+------------+--------+------+
   | Oracle Weblogic Server           | --                     | --      | --         | \*     | --   |
   +----------------------------------+------------------------+---------+------------+--------+------+
   | Tomcat Server                    | --                     | --      | --         | \*     | --   |
   +----------------------------------+------------------------+---------+------------+--------+------+

   .. raw:: html
   
      </div>
      </div>
      </div>




