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