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

Wed Aug 12 00:30:22 UTC 2020

On 11/8/20 11:33 pm, Gedare Bloom wrote:
> Thanks for doco. A few typos to fix

Thanks for the review. I will make the corrections and push.

> 
> 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

Yes I will reword this.

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

No they do not. No way to make a portable link in a PDF, ie --prefix != hosting URL.

Thanks
Chris

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