On Sun, Mar 22, 2020 at 7:42 PM Gedare Bloom <ged...@rtems.org> wrote:
> Hi Niteesh, > > Did you build the docs with this change > Yes, I did. Did you face any issues? I am sorry for typos and grammatical mistakes. I checked a couple of times but still missed them. > 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...@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...@gmail.com> > > +.. comment: All rights reserved. > We don't really use this phrase. > This was inspired by this source. Should I change that also? https://devel.rtems.org/wiki/Docs/New_Chapter#License > > + > > + > 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. > I'll send in a patch once his work gets merged. > > +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. > I have looked at common/rtemsdomain.py to see if any macro for the specific version was present. But I couldn't find anything. The "|version|" is being used in the headings for the chapter. But it includes both RTEMS major and minor number. |version| --> 5.927b004 > > + > > +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 j...@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 j...@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 > I have added a section below for creating patches. Should I still add a few pointers here? I am planning to add the git author information in that section. And add a ref to user/support/contrib.html#preparing-and-sending-patches here. > > > + > > +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@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 > > >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel