[PATCH] user/gsoc: GSoC Getting Started Instructions

Mon Mar 23 01:13:01 UTC 2020

On 2020-03-18 07:36, G S Niteesh Babu wrote:
> ---
>   user/index.rst       |   1 +
>   user/start/gsoc.rst  | 453 +++++++++++++++++++++++++++++++++++++++++++
>   user/start/index.rst |   1 +
>   3 files changed, 455 insertions(+)
>   create mode 100644 user/start/gsoc.rst
> 
> diff --git a/user/index.rst b/user/index.rst
> index 0e644c9..f253ea6 100644
> --- a/user/index.rst
> +++ b/user/index.rst
> @@ -10,6 +10,7 @@ RTEMS User Manual (|version|).
>   
>   .. topic:: Copyrights and License
>   
> +    | |copy| 2020 Niteesh Babu
>       | |copy| 2019 Vijay Kumar Banerjee
>       | |copy| 2018 Amaan Cheval
>       | |copy| 2018 Marçal Comajoan Cara
> diff --git a/user/start/gsoc.rst b/user/start/gsoc.rst
> new file mode 100644
> index 0000000..071c1cc
> --- /dev/null
> +++ b/user/start/gsoc.rst
> @@ -0,0 +1,453 @@
> +.. comment: SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. comment: Copyright (C) 2020 Niteesh Babu <niteesh.gs at gmail.com>
> +.. comment: All rights reserved.
> +
> +
> +.. _QuickStartGSoC:
> +
> +GSoC Getting Started
> +====================
> +
> +The goal of this page is to help you get RTEMS compiled and running so you can
> +start with the real work.
> +
> +Please join the :r:list:`users` and :r:list:`devel` mailing lists and ask questions.
> +Help correct any deficiencies in the code or documentation you spot, including
> +those on the wiki. The ultimate goal of GSoC is to help you become part of the
> +open source community.
> +
> +.. _QuickStartConfigureComputer:
> +
> +Configure a Development Computer > +--------------------------------
> +
> +You will be best served by using a GNU/Linux environment,

This should reference the Host section and ask the student to select one 
of the supported hosts. Recommending a Unix host is fine.

> which could be in a
> +virtual machine, for example that uses `Virtualbox <https://www.virtualbox.org/>`_

This is fine.

> +and should run on most modern desktop systems. You should also be able to work
> +with a MacOS or Windows system, but might encounter more difficulty than a *nix
> +environment.

For some people Unix is more difficult.

> +
> +Feel free to ask questions on the rtems-users mailing list in case you face
> +trouble with the steps. If you want tools for another architecture, replace
> +sparc in the RSB directions with another architecture, such as arm or mips. You
> +can also use the RSB to build RTEMS directly, but we recommend that you learn
> +how to build RTEMS by itself with the compiler tools generated by RSB.
> +
> +As you will be compiling a lot of code, it is recommended to have a reasonably
> +fast development machine.
> +
> +The instructions in this chapter will help you in quickly setting up a
> +development environment. For a detailed set of instruction please refer to the
> +:ref:`QuickStart` chapter.
> +
> +You need tools for your host’s operating system to build the RTEMS tool suite
> +from source. Please have a look at the :ref:`host-computer` chapter for the
> +instructions to install the tools.
> +
> +Choosing an Installation Prefix
> +-------------------------------

 From here on I would prefer references to the existing documentation 
with any GSoC details list here. I would prefer we avoid duplicating 
prefix, sources and building anywhere in the documentaion as it will 
only confuse search engines, normal users and GSoC students. The Quick 
Start Guide has taken a long time to get to where it is. If there is 
something in the Quick Start guide that needs fixing please let me know.

I am sorry I have not commented before now, I have been distracked.

Thanks
Chris

> +
> +The term ``prefix`` refers to the path on your computer where the software is to
> +be installed.
> +In this case, we choose the home directory ``$HOME/rtems`` as our prefix.
> +
> +.. code-block:: none
> +
> +  mkdir $HOME/rtems
> +
> +Getting Sources
> +---------------
> +
> +We obtain the source code for the :ref:`RTEMS Source Builder (RSB) <RSB>` and
> +RTEMS from the RTEMS :r:url:`git`.
> +
> +The :ref:`RTEMS Source Builder (RSB) <RSB>` is the tool used to build RTEMS
> +packages from source. We will be using the RSB to build RTEMS the source.
> +Please have a look at the :ref:`RTEMS Source Builder (RSB) <RSB>` for more
> +information.
> +
> +We'll clone to the repositories to ``$HOME/rtems/src``.
> +
> +.. code-block:: none
> +
> +  mkdir -p $HOME/rtems/src
> +  cd $HOME/rtems/src
> +  git clone git://git.rtems.org/rtems-source-builder.git rsb
> +  git clone git://git.rtems.org/rtems.git
> +
> +Building the Tool suite
> +-----------------------
> +
> +Once you have cloned the repositories and installed the required tools for
> +your host operating system. You can start building the tools suite for your BSP.
> +The tools suite is the collection of compiler, debugger, Assembler and other
> +tools required for developing the software.
> +
> +You can check if your host is set up correctly using ``sb-check`` tool provided
> +in the RSB repository.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/src/rsb/source-builder
> +  ./sb-check
> +
> +If you installed all the required tools you should have the following output.
> +
> +.. code-block:: none
> +
> +  RTEMS Source Builder - Check, 5 (0b7e87143b76)
> +  Environment is ok
> +
> +.. note:: The numbers may vary depending on the RSB release.
> +
> +The tool suite for RTEMS and the RTEMS sources are tightly coupled. For example,
> +do not use a RTEMS version 5 tool suite with RTEMS version 4.11 sources and vice
> +versa. In simple words, make sure you clone both the repositories at the same
> +time.
> +
> +The tools suite is architecture specific. In this guide we will be building the
> +tools suite for the SPARC architecture. So the tool suite name is sparc-rtems5.
> +You can build the tools suite for other architectures like ARM, RISCV by
> +replacing the architecture name. For example, for ARM the tools suite name would
> +be arm-rtems5.
> +
> +The following command builds and installs the tools suite in the path mentioned
> +in the prefix option.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/src/rsb/rtems
> +  ../source-builder/sb-set-builder --prefix=$HOME/rtems/5 5/rtems-sparc
> +
> +This command should output something like this (omitted lines are denoted by …).
> +The build host appears as part of the name of the package being built. The name
> +you see may vary depending on the host you are using:
> +
> +.. code-block:: none
> +
> +  RTEMS Source Builder - Set Builder, 5.1.0
> +  Build Set: 5/rtems-sparc
> +  ...
> +  config: tools/rtems-binutils-2.34.cfg
> +  package: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
> +  building: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
> +  sizes: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1: 305.866MB (installed: 29.966MB)
> +  cleaning: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
> +  reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.txt
> +  reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.xml
> +  config: tools/rtems-gcc-7.5.0-newlib-fbaa096.cfg
> +  package: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
> +  building: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
> +  ....
> +  Build Sizes: usage: 5.684GB total: 1.112GB (sources: 143.803MB, patches: 21.348KB, installed 995.188MB)
> +  Build Set: Time 0:21:35.626294
> +
> +Once the build has successfully completed you can check if the cross C compiler
> +works with the following command:
> +
> +.. code-block:: none
> +
> +  $HOME/rtems/5/bin/sparc-rtems5-gcc --version
> +
> +This command should output something like below. The version information helps
> +you to identify the exact sources used to build the cross compiler of your RTEMS
> +tool suite.
> +
> +.. code-block:: none
> +
> +  sparc-rtems5-gcc (GCC) 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
> +  Copyright (C) 2017 Free Software Foundation, Inc.
> +  This is free software; see the source for copying conditions.  There is NO
> +  warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> +
> +Add the tools suite to your ``$PATH`` by the following command:
> +
> +.. code-block:: none
> +
> +  export PATH=$HOME/rtems/5:"$PATH"
> +
> +This is only valid for the current terminal session. To make it permanant, add
> +it your ``~/.profile`` by the following command:
> +
> +.. code-block:: none
> +
> +  echo "export PATH=$PATH:$HOME/rtems/5" >> ~/.profile
> +
> +Bootstrap the RTEMS Source
> +--------------------------
> +
> +Since you have built and installed the tools required for compilation of RTEMS.
> +It is time to build the BSP. But before that it is necessary to bootstrap the
> +the build system in the RTEMS source. Bootstrap is the process where the files
> +required for building RTEMS are generated. This process is required because
> +RTEMS does not keep the generated files under version control.
> +
> +To perform bootstrap we need to enter the cloned source directory then run the
> +bootstrap commands:
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/src/rtems
> +  ./bootstrap -c && /$HOME/rtems/src/rtems/rtems-bootstrap
> +
> +Build the BSP
> +-------------
> +
> +The Board Support Package (BSP) is the software that glues a specific board or
> +hardware to RTEMS. For information on available BSPs you can refer to :ref:`BSPs`.
> +
> +We will be building the SPARC ERC32 BSP since we have installed the SPARC tools
> +suite and also because this BSP has a robust simulator that runs the example and
> +test executables on your host computer.
> +
> +The RSB can also be used to build the BSP. But we will be building it manually.
> +You can refer to the :ref:`QuickStart` chapter for instructions on building it
> +using RSB.
> +
> +We by choosing a build directory. It must be separate from the RTEMS source
> +directory. We will be using ``$HOME/rtems/build/erc32`` as our build directory.
> +
> +.. code-block:: none
> +
> +  mkdir -p $HOME/rtems/build/erc32
> +
> +We now configure the BSP. We enable all the tests. But if you want you can
> +enable only a part of the tests by replacing `--enable-tests` with
> +`--enable-tests=samples`. This would only build the tests under
> +``$HOME/rtems/src/rtems/testsuites/samples`` and will also reduce your build
> +times significantly.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/build/erc32
> +  $HOME/rtems/src/rtems/configure \
> +      --prefix=$HOME/quick-start/rtems/5 \
> +      --enable-maintainer-mode \
> +      --target=sparc-rtems5 \
> +      --enable-rtemsbsp=erc32 \
> +      --enable-tests
> +
> +This command should output something like this (omitted lines are denoted by ...):
> +
> +.. code-block:: none
> +
> +  checking for gmake... gmake
> +  checking for RTEMS Version... 5.0.0
> +  checking build system type... x86_64-unknown-freebsd12.0
> +  checking host system type... x86_64-unknown-freebsd12.0
> +  checking target system type... sparc-unknown-rtems5
> +  ...
> +  config.status: creating Makefile
> +
> +  target architecture: sparc.
> +  available BSPs: erc32.
> +  'gmake all' will build the following BSPs: erc32.
> +  other BSPs can be built with 'gmake RTEMS_BSP="bsp1 bsp2 ..."'
> +
> +  config.status: creating Makefile
> +
> +The configure command will the create the Makefile required to build the BSP.
> +
> +We can now finally build the BSP using make.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/build/erc32
> +  make
> +
> +This command should output something like this (omitted lines are denoted by …).
> +
> +.. code-block::none
> +
> +  Configuring RTEMS_BSP=erc32
> +  checking for gmake... gmake
> +  checking build system type... x86_64-unknown-freebsd12.0
> +  checking host system type... sparc-unknown-rtems5
> +  checking rtems target cpu... sparc
> +  checking for a BSD-compatible install... /usr/bin/install -c
> +  checking whether build environment is sane... yes
> +  checking for sparc-rtems5-strip... sparc-rtems5-strip
> +  checking for a thread-safe mkdir -p... $BASE/src/rtems/c/src/../../install-sh -c -d
> +  checking for gawk... no
> +  checking for mawk... no
> +  checking for nawk... nawk
> +  checking whether gmake sets $(MAKE)... yes
> +  checking whether to enable maintainer-specific portions of Makefiles... yes
> +  checking for RTEMS_BSP... erc32
> +  checking whether CPU supports libposix... yes
> +  configure: setting up make/custom
> +  configure: creating make/erc32.cache
> +  gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
> +  ...
> +  sparc-rtems5-gcc  -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a
> +  gmake[5]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites/sptests'
> +  gmake[4]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites'
> +  gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
> +  gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
> +  gmake[1]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  gmake[1]: Entering directory '$BASE/build/b-erc32'
> +  gmake[1]: Nothing to be done for 'all-am'.
> +  gmake[1]: Leaving directory '$BASE/build/b-erc32'
> +
> +The last step is installing the BSP.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/build/erc32
> +  make install
> +
> +This command should output something like this (omitted lines are denoted by …).
> +In this output the base directory $HOME/rtems was replaced by $BASE.
> +
> +.. code-block:: none
> +
> +  Making install in sparc-rtems5/c
> +  gmake[1]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  Making install in .
> +  gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  gmake[3]: Nothing to be done for 'install-exec-am'.
> +  gmake[3]: Nothing to be done for 'install-data-am'.
> +  gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
> +  Making install in erc32
> +  gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
> +  gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
> +  Making install-am in .
> +  Making install-am in cpukit
> +  gmake[4]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
> +  gmake[5]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
> +  gmake[5]: Nothing to be done for 'install-exec-am'.
> +   $BASE/src/rtems/c/src/../../cpukit/../install-sh -c -d '$BASE/rtems/5/sparc-rtems5/erc32/lib/include'
> +  ...
> +  $BASE/src/rtems/make/Templates/Makefile.lib '$BASE/rtems/5/share/rtems5/make/Templates'
> +   $BASE/src/rtems/./install-sh -c -d '$BASE/rtems/5/make/custom'
> +   /usr/bin/install -c -m 644 $BASE/src/rtems/make/custom/default.cfg '$BASE/rtems/5/make/custom'
> +  gmake[2]: Leaving directory '$BASE/build/b-erc32'
> +  gmake[1]: Leaving directory '$BASE/build/b-erc32'
> +
> +Testing the BSP
> +---------------
> +
> +Since, we now have a BSP built and installed. We will test it by running a
> +Hello world example. This example is already been built during the BSP build
> +phase.
> +
> +We can run this using the simulator provided by RSB tools suite. The SPARC tools
> +suite comes with SIS simulator which can we used to run your executables on your
> +host computer without the need for hardware.
> +
> +The ``Hello World`` executable can be found under
> +``$HOME/rtems/build/erc32/sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe``.
> +
> +To run the executable in the simulator we use the following command:
> +
> +.. code-block:: none
> +
> +  sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
> +
> +The output will be the following:
> +
> +.. code-block:: none
> +
> +  sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
> +  SIS - SPARC/RISCV instruction simulator 2.20,  copyright Jiri Gaisler 2019
> +  Bug-reports to jiri at gaisler.se
> +  ERC32 emulation enabled
> +
> +  Loaded sparc-rtems5/c/erc32/testsuites/samples/hello.exe, entry 0x02000000
> +
> +  sis>
> +
> +This command will start the simulator and will load the executable in it. To run
> +the exe, enter run in the simulator prompt ( `sis>` ). This will running the
> +executable in the simulator and the following output will be produced.
> +
> +.. code-block:: none
> +
> +  sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
> +  SIS - SPARC/RISCV instruction simulator 2.20,  copyright Jiri Gaisler 2019
> +  Bug-reports to jiri at gaisler.se
> +  ERC32 emulation enabled
> +
> +  Loaded sparc-rtems5/c/erc32/testsuites/samples/hello.exe, entry 0x02000000
> +
> +  sis> run
> +
> +
> +  *** BEGIN OF TEST HELLO WORLD ***
> +  *** TEST VERSION: 5.0.0.c6d8589bb00a9d2a5a094c68c90290df1dc44807
> +  *** TEST STATE: EXPECTED-PASS
> +  *** TEST BUILD: RTEMS_POSIX_API
> +  *** TEST TOOLS: 7.5.0 20191114 (RTEMS 5, RSB 83fa79314dd87c0a8c78fd642b2cea3138be8dd6, Newlib 3e24fbf6f)
> +  Hello World
> +
> +  *** END OF TEST HELLO WORLD ***
> +
> +
> +  *** FATAL ***
> +  fatal source: 0 (INTERNAL_ERROR_CORE)
> +  fatal code: 5 (INTERNAL_ERROR_THREAD_EXITTED)
> +  RTEMS version: 5.0.0.c6d8589bb00a9d2a5a094c68c90290df1dc44807
> +  RTEMS tools: 7.5.0 20191114 (RTEMS 5, RSB 83fa79314dd87c0a8c78fd642b2cea3138be8dd6, Newlib 3e24fbf6f)
> +  executing thread ID: 0x08a010001
> +  executing thread name: UI1
> +  cpu 0 in error mode (tt = 0x101)
> +    116401  02009ae0:  91d02000   ta  0x0
> +
> +Prove You Can Work On RTEMS
> +---------------------------
> +
> +Modify the hello world example to include a new different print statement.
> +Something like "Hello from The Dark Side!". Then send us enough to prove to us
> +that you did this. We want to know you can work with RTEMS.
> +
> +Create a patch of your changes and send it to :r:link:`devel` along with the
> +screenshot of the output.
> +
> +If you followed this guide, this hello world modification will likely need to be
> +made to the file you'll have in ``$HOME/rtems/src/rtems/testsuites/samples/hello/init.c``.
> +You can edit the file, commit your changes using git, and then run git
> +format-patch master to generate a patch file.
> +
> +Creating Patch
> +--------------
> +
> +Once you have made the required changes in the ``init.c`` file. You will have to
> +commit those changes. Before commiting the changes make sure you are not on the
> +master branch. This is to avoid merge conflicts. You can create and work on a
> +separate local branch with the following git command.
> +
> +.. code-block:: none
> +
> +  cd $HOME/rtems/src/rtems
> +  git checkout -b gsoc
> +
> +This is will create a separate branch called `gsoc` and will switch you to it.
> +
> +Stage the file and commit using the following commands.
> +
> +.. code-block:: none
> +
> +  git add $HOME/rtems/src/rtems/testsuites/samples/hello/init.c
> +  git commit -m "<YOUR-COMMIT-MESSAGE>"
> +
> +You can now create a patch file using ``git format-patch``.
> +
> +.. code-block:: none
> +
> +  git format-patch -1
> +
> +Sending Patches
> +---------------
> +
> +Once the patch file is created. You can now send it to :r:link:`devel` using
> +``git send-email``. Please refer to `git send-email <https://git-scm.com/docs/git-send-email>`_
> +for instructions on seting up the SMTP server and other options.
> +
> +The following command will send the patch to the mailing list.
> +
> +.. code-block:: none
> +
> +  git send-email <YOUR-PATCH-FILE> --to devel at rtems.org
> diff --git a/user/start/index.rst b/user/start/index.rst
> index d6333f3..2d3ab2c 100644
> --- a/user/start/index.rst
> +++ b/user/start/index.rst
> @@ -22,3 +22,4 @@ applications on top of RTEMS.
>       bsp-build
>       bsp-test
>       app
> +    gsoc
> 