[PATCH 04/10] user: Add "Obtain the Sources" section

[Chris Johns]

On 24/1/19 7:55 pm, Sebastian Huber wrote:
> ---
>  user/start/index.rst   |  1 +
>  user/start/sources.rst | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 52 insertions(+)
>  create mode 100644 user/start/sources.rst
> 
> diff --git a/user/start/index.rst b/user/start/index.rst
> index 96388f2..d5f21e7 100644
> --- a/user/start/index.rst
> +++ b/user/start/index.rst
> @@ -18,6 +18,7 @@ applications on top of RTEMS.
>  
>      host
>      prefixes
> +    sources
>  
>  The following is a quick start guide that provides a basic set of commands to
>  build the RTEMS Tools and Kernel. The quick start guide provides links to the
> diff --git a/user/start/sources.rst b/user/start/sources.rst
> new file mode 100644
> index 0000000..6fee109
> --- /dev/null
> +++ b/user/start/sources.rst
> @@ -0,0 +1,51 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. Copyright (C) 2019 embedded brains GmbH
> +.. Copyright (C) 2019 Sebastian Huber
> +
> +.. _QuickStartSources:
> +
> +Obtain the Sources
> +==================
> +
> +You chose an installation prefix previous section.  We chose
> +:file:`$HOME/quick-start/rtems/5` as the installation prefix.
> +
> +You need at least two source archives or Git repositories to work with RTEMS.
> +You can download the source archives for a released RTEMS version or you can
> +clone Git repositories to get all versions of RTEMS including the development
> +head.
> +
> +We will clone the Git repositories into :file:`$HOME/quick-start/src`.
> +
> +.. code-block:: none
> +
> +    mkdir -p $HOME/quick-start/src
> +    cd $HOME/quick-start/src
> +    git clone https://github.com/RTEMS/rtems-source-builder.git rsb
> +    git clone https://github.com/RTEMS/rtems.git

Please do not document github as _the_ way to get the code.

I understand this is an https path which some users need due to corporate
firewalls so maybe provide github as an alternative with an explanation in a
sidebar and explain github is read-only and the projects repos are in the
rtems.org domain.

> +
> +The :file:`rsb` repository clone contains the
> +:ref:`RTEMS Source Builder (RSB) <RSB>`.  We clone it into
> +:file:`rsb` to get shorter paths during the tool suite build.  The
> +:file:`rtems` repository clone contains the RTEMS sources.  These two
> +repositories are enough to get started.  There are
> +`more repositories <https://git.rtems.org>`_ available.
> +
> +Alternatively, you can download the source archives of a released RTEMS
> +version.
> +
> +.. code-block:: none
> +
> +    mkdir -p $HOME/quick-start/src
> +    cd $HOME/quick-start/src
> +    curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-4.11.3.tar.xz | tar xJf -
> +    curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-source-builder-4.11.3.tar.xz | tar xJf -
> +
> +This quick start chapter focuses on working with the Git repository clones
> +since this gives you some flexibility.  You can switch between branches to try
> +out different RTEMS versions.  You have access to the RTEMS source history.
> +The RTEMS Project welcomes contributions.  The Git repositories enable you to
> +easily create patches and track local changes. 

Using git does not give you are formal version number. This is only provided by
the release tarballs. I think this is worth noting.

> If you prefer to work with
> +archives of a released RTEMS version, then simply replace the version number 5
> +used throughout this chapter with the version number you selected, e.g. 4.11. 

This is looking good so far.

I will continue tomorrow, the tennis is over for the evening.

Chris