user, README: Add Python script host set up information

- Add Python3 and venv to the README

- Add a section on how to set up a host if the python command is
  not available.

Update #4037

README.txt

@@ -101,14 +101,20 @@ command.
 
 Please add your host as you set it up.
 
-The best environment to use is `virtualenv`. It can create a specific python
+The best results are produced with Python3 and a virtual environment`. It can
-environment using `pip`.
+create a specific python environment using `pip`.
 
-Virtualenv
+Virtual Environment
-~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
 
-Create a directory to house the virtualenv, create the envrionment and the
+Create a directory to house the virtual environment, create the envrionment
-activate it:
+and the activate it. This example assumes Python3 and the `venv` module:
+
+  $ mkdir sphinx
+  $ python3 -m venv sphinx
+  $ . ./sphinx/bin/activate
+
+Alternatively you can use the `virtualenv` command:
 
   $ mkdir sphinx
   $ virtualenv sphinx

user/hosts/index.rst

@@ -15,11 +15,11 @@ development computer, more often called the host computer. These are typically
 your desktop machine or a special build server. All RTEMS tools and runtime
 libraries are built from source on your host machine. The RTEMS Project does
 not maintain binary builds of the tools. This differs to what you normally
-experience with host operating systems, and it is, however this approach works
+experience with host operating systems however this approach works well. RTEMS
-well. RTEMS is not a host operating system and it is not a
+is not a host operating system and it is not a distrbution. Deploying binary
-distrbution. Deploying binary packages for every possible host operating system
+packages for every possible host operating system is too big a task for the
-is too big a task for the RTEMS Project and it is not a good use of core
+RTEMS Project and it is not a good use of core developer time. Their time is
-developer time. Their time is better spent making RTEMS better and faster.
+better spent making RTEMS better and faster.
 
 The RTEMS Project's aim is to give you complete freedom to decide on the
 languages used in your project, which version control system, and the build
@@ -37,14 +37,16 @@ engineer a development environment that suites you. The basic specs are:
 
 RTEMS makes no demands on graphics.
 
-If you are using a VM or your host computer is not a fast modern machine do not
+If you are using a VM or your host computer is not a fast modern machine do
-be concerned. The tools may take longer to build than faster hardware however
+not be concerned. The tools may take longer to build than faster hardware
-building tools is something you do once. Once the tools and RTEMS is built all
+however building tools is something you do once. Once the tools and RTEMS are
-your time can be spent writing and developing your application. Over an hour
+built all your time can be spent writing and developing your application. It
-can happen and for the ARM architecture and with all BSPs it can be many hours.
+may take longer than an hour for the ARM architecture and with all BSPs it can
+be many hours.
 
 .. toctree::
 
+   python
    os
    posix
    macos

user/hosts/python.rst

@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 Chris Johns <chrisj@rtems.org>
+
+.. _host-os:
+
+Python
+======
+
+RTEMS uses Python in a range of host tools for users and
+developer. RTEMS supports:
+
+#. Python3 and Python2 for user tools,
+
+#. Python3 for developer tools.
+
+Python2 is now **end of life** however the RTEMS Project will continue to
+provide support for its user commands. We do this to support older host
+operating systems some users may be forced to use. At some point the
+project will drop support for Python2 so we recommend users look at ways to
+transition to Python3 if it is not easily available.
+
+Developers of RTEMS are required to have Python3 available. RTEMS tools used
+by developers for the development and maintenance of RTEMS are Python3 only.
+
+All RTEMS Tools that can be invoked from the command line start with the
+following line:
+
+.. code-block::
+
+  #! /usr/bin/env python
+
+The ``env`` command is available on all POSIX host operating systems and it
+searches the ``$PATH`` environment variable for the ``python`` command invoking
+it with the script as the first argument. This means you need to have a
+suitable ``python`` command on your host to run the RTEMS user tools. Not all
+hosts provide a ``python`` command. If your host does not you need to find a
+way to provide one. The following are some examples you can use to solve this
+problem.
+
+Python2 by default always provides a ``python`` command.
+
+Virtual Environment
+~~~~~~~~~~~~~~~~~~~
+
+Python3 provides virtual environment support. This is a great way to manage
+Python on a single host. You can have a number of virtual environments with a
+different mix of installed Python packages with different versions that do not
+clash.
+
+Virtual environment always provide a ``python`` command. This makes it ideal
+if your host only provides Python3 and there is no default ``python`` command.
+
+A virtual environment is created once and when you need to use it you activate
+it and when finished you deactivate it.
+
+The following shows how to create a virtual environment using different
+methods. You can select the method that best suites you.
+
+To create a virtual environment using the Python3 ``venv`` module:
+
+.. code-block:: none
+
+  python3 -m venv rtems-py
+
+To create a virtual environment for a specific version of Python3 you
+can enter the command:
+
+.. code-block:: none
+
+  python3.7 -m venv rtems-py
+
+You can also install the ``virtualenv`` package on your host if it is
+avaliable then enter the following create command:
+
+.. code-block:: none
+
+  virtualenv rtems-py
+
+To activate the virtual environment:
+
+.. code-block:: none
+
+  . rtems-py/bin/activate
+
+You will see your prompt change to reflect the virtual environment you
+have active.  To check if you now have a ``python`` command enter:
+
+.. code-block:: none
+
+  type python
+
+The output will be something similar to the following:
+
+.. code-block:: none
+
+  (rtems-py) $ type python
+  python is /home/chris/development/rtems-py/bin/python
+
+Symbolic Link
+~~~~~~~~~~~~~
+
+If your host does not provide the ``python`` command you can add a symbolic
+link to it.
+
+.. note::
+
+  We recommend you do not add the symbolic link in any of your operating
+  system controlled directories as it is changing your operating system.
+
+We suggest you add the symbolic link to a directory under your home directory
+adding that directory to your environment's ``PATH`` variable. The following
+commands show how to do this:
+
+.. code-block:: none
+
+  cd
+  mkdir bin
+  cd bin
+  ln -s `command -v python3` python
+  export PATH=$HOME/bin:$PATH
+
+.. note::
+
+  You will need to modify your shell's initialization scripts to make the
+  ``PATH`` change permanent.
+
+Directly Invoking Python
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is valid to specifically invoke any python script directly. To do this
+simply prepend the specific version of python you wish to use. For example to
+run the ``waf`` build system command with Python3 use:
+
+.. code-block:: none
+
+  python3 ./waf