[PATCH] user/gsoc: GSoC Getting Started Instructions

Sun Mar 22 14:11:57 UTC 2020

Hi Niteesh,

Did you build the docs with this change?

The rewrite is nice. I do have several comments below to address:

On Tue, Mar 17, 2020 at 2:36 PM G S Niteesh Babu <niteesh.gs at gmail.com> 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.
We don't really use this phrase.

> +
> +
only 1 blank

> +.. _QuickStartGSoC:
> +
> +GSoC Getting Started
> +====================
> +
> +The goal of this page is to help you get RTEMS compiled and running so you can
I think the intro at least will be better in the 3rd person for the
manual version. Replace first "you" with "new users, especially
students, " and replace second "you" with "they"

> +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
replace "you" with "students"

You can keep it in second-person below that is fine for now.

> +open source community.
> +
> +.. _QuickStartConfigureComputer:
> +
> +Configure a Development Computer
> +--------------------------------
> +
> +You will be best served by using a GNU/Linux environment, which could be in a
> +virtual machine, for example that uses `Virtualbox <https://www.virtualbox.org/>`_
> +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.
> +
> +Feel free to ask questions on the rtems-users mailing list in case you face
:r:list:`users`

> +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
s/another/that

> +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
typo: instructions

> +: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.
> +
After the chapter by Utkarsh about cross-compilers is merged, it would
be good to add a sentence here with a ref.

> +Choosing an Installation Prefix
> +-------------------------------
> +
> +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.
"from" missing?

> +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``.
"to the" -> "the"

> +
> +.. 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
lower case assembler

> +tools required for developing the software.
> +
> +You can check if your host is set up correctly using ``sb-check`` tool provided
"using the"

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

"a RTEMS" -> "an RTEMS"

> +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
hyphenate "architecture-specific"
comma after guide

> +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
replace comma with "or"

> +replacing the architecture name. For example, for ARM the tools suite name would
> +be arm-rtems5.
Does the manual have a version number macro for the specific version
of the docs that are built? It ought to... then you could replace
every hard-coded '5' version number here with that macro.

> +
> +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
C cross-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
typo: permanent

> +it your ``~/.profile`` by the following command:
> +
> +.. code-block:: none
> +
> +  echo "export PATH=$PATH:$HOME/rtems/5" >> ~/.profile
> +
The above about .profile is not portable and may not be the best
practice for all users. Maybe specify simply that the PATH
modifications can be made permanent in different ways depending on the
host OS... and give this as one example.

> +Bootstrap the RTEMS Source
> +--------------------------
> +
> +Since you have built and installed the tools required for compilation of RTEMS.
Sentence fragment. Replace "Since" with "By now"

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

It may be better to show directions with sb-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
by -> start by

> +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.
s/will the create/will create

> +
> +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
Delete "Since, " and capitalize "We"

> +Hello world example. This example is already been built during the BSP build
is -> has

> +phase.
> +
> +We can run this using the simulator provided by RSB tools suite. The SPARC tools
this -> "Hello World"

> +suite comes with SIS simulator which can we used to run your executables on your
"with the"
"your executable" -> "RTEMS executables"

> +host computer without the need for hardware.
"hardware" -> "SPARC 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
"will run"

> +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.
Add a sentence like, "Use git-commit to create your patch, and make
sure the git author information is correct."
Maybe add a ref to the user/support/contrib.html#preparing-and-sending-patches

> +
> +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
typo: committing

> +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.
delete 'is'

> +
> +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.
typo: setting

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