[PATCH] user, README: Add Python script host set up information

Tue Aug 11 02:33:03 UTC 2020

From: Chris Johns <chrisj at rtems.org>

- 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            |  18 ++++--
 user/hosts/index.rst  |  22 ++++---
 user/hosts/python.rst | 137 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 161 insertions(+), 16 deletions(-)
 create mode 100644 user/hosts/python.rst

diff --git a/README.txt b/README.txt
index ce30505..03f57ed 100644
--- a/README.txt
+++ b/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
-environment using `pip`.
+The best results are produced with Python3 and a virtual environment`. It can
+create a specific python environment using `pip`.
 
-Virtualenv
-~~~~~~~~~~
+Virtual Environment
+~~~~~~~~~~~~~~~~~~~
+
+Create a directory to house the virtual environment, create the envrionment
+and the activate it. This example assumes Python3 and the `venv` module:
+
+  $ mkdir sphinx
+  $ python3 -m venv sphinx
+  $ . ./sphinx/bin/activate
 
-Create a directory to house the virtualenv, create the envrionment and the
-activate it:
+Alternatively you can use the `virtualenv` command:
 
   $ mkdir sphinx
   $ virtualenv sphinx
diff --git a/user/hosts/index.rst b/user/hosts/index.rst
index 5588339..29de1ce 100644
--- a/user/hosts/index.rst
+++ b/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
-well. RTEMS is not a host operating system and it is not a
-distrbution. Deploying binary packages for every possible host operating system
-is too big a task for the RTEMS Project and it is not a good use of core
-developer time. Their time is better spent making RTEMS better and faster.
+experience with host operating systems however this approach works well. RTEMS
+is not a host operating system and it is not a distrbution. Deploying binary
+packages for every possible host operating system is too big a task for the
+RTEMS Project and it is not a good use of core developer time. Their time is
+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
-be concerned. The tools may take longer to build than faster hardware however
-building tools is something you do once. Once the tools and RTEMS is built all
-your time can be spent writing and developing your application. Over an hour
-can happen and for the ARM architecture and with all BSPs it can be many hours.
+If you are using a VM or your host computer is not a fast modern machine do
+not be concerned. The tools may take longer to build than faster hardware
+however building tools is something you do once. Once the tools and RTEMS are
+built all your time can be spent writing and developing your application. It
+may take longer than an hour for the ARM architecture and with all BSPs it can
+be many hours.
 
 .. toctree::
 
+   python
    os
    posix
    macos
diff --git a/user/hosts/python.rst b/user/hosts/python.rst
new file mode 100644
index 0000000..350795b
--- /dev/null
+++ b/user/hosts/python.rst
@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 Chris Johns <chrisj at 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 it's user commands. We do this to support older host
+operating systems some users may be forced to support. 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 maintance 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
+searchs 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 bests 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 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 operaing system.
+
+We suggest you add the symbolic link to a directory under your home directory
+adding that directory 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 intialisation 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
-- 
2.24.1

