diff options
author | Chris Johns <chrisj@rtems.org> | 2020-08-11 12:33:03 +1000 |
---|---|---|
committer | Chris Johns <chrisj@rtems.org> | 2020-08-12 11:06:23 +1000 |
commit | b71f7f6960a628c0e1c930b5769d19c5957a6998 (patch) | |
tree | ad8d2b2fcac1cebd5b85be3ffe4cb8ad3f8edcb4 /user/hosts/python.rst | |
parent | user, eclipse: Remove RSB sb-bootstrap command (diff) | |
download | rtems-docs-b71f7f6960a628c0e1c930b5769d19c5957a6998.tar.bz2 |
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
Diffstat (limited to '')
-rw-r--r-- | user/hosts/python.rst | 137 |
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 |