1 files changed, 137 insertions, 0 deletions
diff --git a/user/hosts/python.rst b/user/hosts/python.rst
new file mode 100644
index 0000000..7da0f1c
--- /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@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