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

Tue Aug 11 13:33:04 UTC 2020

Thanks for doco. A few typos to fix

On Mon, Aug 10, 2020 at 8:33 PM <chrisj at rtems.org> wrote:
>
> 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
s/it's/its

> +operating systems some users may be forced to support. At some point the
s/support/use
because we say support on our side already it may be confusing on the
user's side

> +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.
maintenance

Link to SWEng Python?
https://docs.rtems.org/branches/master/eng/python-devel.html
- I don't remember if cross-manual links work well.

> +
> +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
s/searchs/searches
- I don't know if that is British vs American though?

> +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.
s/bests/best
s/suites/suits

> +
> +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:
add 'the' after enter

> +
> +.. 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.
operating

> +
> +We suggest you add the symbolic link to a directory under your home directory
> +adding that directory your environment's ``PATH`` variable. The following
add 'to' before your

> +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
typo: initialisation
- or American: initialization   ;)

> +  ``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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel