Thanks for doco. A few typos to fix On Mon, Aug 10, 2020 at 8:33 PM <chr...@rtems.org> wrote: > > From: Chris Johns <chr...@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 <chr...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
