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

[Sebastian Huber]

On 24/01/2019 12:17, Chris Johns wrote:
>
> 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.

How difficult would it be to provide HTTPS access at git.rtems.org? It 
is quite common that the Git protocol is blocked by company firewalls. I 
would like to keep the number of alternatives and potential problems as 
low as possible in the quick start chapter. For a normal user the RTEMS 
repositories are read-only and someone with write access will probably 
know the differences.

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

Is a git checkout 4.11.3 and a bootstrap not equivalent (modulo 
timestamps and potential Autotool shortcomings) to an unpacked release 
archive?

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

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.