From 6ae88de040d098725b2616d8d446f645133a6ced Mon Sep 17 00:00:00 2001
From: Michael Gielda <mgielda@antmicro.com>
Date: Sat, 12 Apr 2014 01:17:29 +0200
Subject: Modified and simplified the building instructions so that they can be
 copy-pasted, closes #6

---
 doc/source/building.rst | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/doc/source/building.rst b/doc/source/building.rst
index 6aed707..d80cded 100644
--- a/doc/source/building.rst
+++ b/doc/source/building.rst
@@ -6,6 +6,16 @@ This chapter describes how to build an eCos kernel and compile eCos applications
 The build process was tested on the Gentoo, Debian, Ubuntu and Mint Linux distributions.
 The procedures described here should also work on other systems, but if you find any way to improve this manual with respect to tested platforms, please e-mail us at contact@antmicro.com.
 
+.. note::
+
+   The code blocks below, when copy-pasted to a Linux terminal, should all work, provided they were called from the same directory.
+   To avoid confusion, it is best to call them from within a new, empty directory, e.g.:
+
+   .. code-block:: bash
+
+      mkdir ~/ecos-from-scratch
+      cd ~/ecos-from-scratch
+
 .. _prerequisites:
 
 Prerequisites
@@ -84,7 +94,7 @@ The following commands will prepare a sample ``.ecc`` file for a kernel with def
 
    .. code-block:: bash
 
-      export ECOS_REPOSITORY="{path/to/ecos-colibri-vf61/ecos}/packages"  # modify
+      export ECOS_REPOSITORY="$PWD/ecos-colibri-vf61/ecos/packages"
       # Create ecos.ecc file based on Colibri VF61 default template
       ecosconfig new col_vf61 default
 
@@ -103,20 +113,22 @@ The eCos kernel is built in two stages:
   It is best to generate the build tree in a separate directory (here ``build-tree``). 
 * then, the source files are compiled
 
-A short shell script is proposed to make the compilation process easier:
+.. warning::
+
+   When copy-pasting the following to the terminal, take care not to export the PATH variable multiple times.
 
 .. topic:: Building the eCos kernel
 
    .. code-block:: bash
 
-      export ECOS_REPOSITORY="{path/to/ecos-colibri-vf61/ecos}/packages"  # modify
-      export PATH="{path/to/toolchain}/bin:$PATH"                         # modify
+      export PATH="$PWD/gnutools/arm-eabi/bin:$PATH"
+      export ECOS_REPOSITORY="$PWD/ecos-colibri-vf61/ecos/packages"
 
       mkdir -p build-tree
       rm -rf build-tree/*
       cd build-tree
 
-      ecosconfig --config={path/to}/ecos.ecc tree                         # modify
+      ecosconfig --config=$PWD/../ecos.ecc tree
       make
       cd ..
 
@@ -143,11 +155,15 @@ A listing for a short sample application (taken from :file:`ecos-colibri-vf61/ec
 
 You can compile an eCos program with a procedure similar to the following listing (which you can save for reuse, for example as ``make.sh``):
 
+.. warning::
+
+   When copy-pasting the following to the terminal, take care not to export the PATH variable multiple times.
+
 .. topic:: Building a user space application
 
    .. code-block:: bash
 
-      export PATH="{path/to/toolchain}/bin:$PATH"                         # modify
+      export PATH="$PWD/gnutools/arm-eabi/bin:$PATH"
 
       # Set compiler options
       OPT="-Wall -Wpointer-arith -Wstrict-prototypes -Wundef  \
@@ -156,7 +172,7 @@ You can compile an eCos program with a procedure similar to the following listin
            -mcpu=cortex-m4"
 
       # Set path to eCos kernel
-      BTPATH="{path/to/ecos/build-tree}"                                  # modify
+      BTPATH="$PWD/build-tree"
 
       # Do compilation and link your application with kernel
       arm-eabi-gcc -g -I./ -g -I${BTPATH}/install/include hello.c \
-- 
cgit v1.2.3