Added toolchain installation guide.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1767 35acf78f-673a-0410-8e92-d51de3d6d3f4

4 files changed, 165 insertions, 0 deletions

diff --git a/docs/rsc/tool001.jpg b/docs/rsc/tool001.jpg
new file mode 100644
index 000000000..f4a004fba
--- /dev/null
+++ b/docs/rsc/tool001.jpg
diff --git a/docs/rsc/tool002.jpg b/docs/rsc/tool002.jpg
new file mode 100644
index 000000000..22cf726bb
--- /dev/null
+++ b/docs/rsc/tool002.jpg
diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index ea471bdb7..1ab76bbff 100644
--- a/docs/src/articles.dox
+++ b/docs/src/articles.dox
@@ -20,6 +20,7 @@
 /**

  * @page articles Articles and Code Samples

  * ChibiOS/RT Articles and Code Examples:

+ * . @subpage article_eclipse

  * - @subpage article_create_thread

  * - @subpage article_interrupts

  * - @subpage article_wakeup

diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox
new file mode 100644
index 000000000..79e60825d
--- /dev/null
+++ b/docs/src/eclipse.dox
@@ -0,0 +1,164 @@
+/*

+    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.

+

+    This file is part of ChibiOS/RT.

+

+    ChibiOS/RT is free software; you can redistribute it and/or modify

+    it under the terms of the GNU General Public License as published by

+    the Free Software Foundation; either version 3 of the License, or

+    (at your option) any later version.

+

+    ChibiOS/RT is distributed in the hope that it will be useful,

+    but WITHOUT ANY WARRANTY; without even the implied warranty of

+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+    GNU General Public License for more details.

+

+    You should have received a copy of the GNU General Public License

+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

+*/

+

+/**

+ * @page article_eclipse Setting up a free embedded IDE

+ * @brief Free advanced embedded IDE for ChibiOS/RT

+ * This article will explain how to setup and use a free toolchain and use it

+ * with ChibiOS/RT and general embedded development. The IDE will allow you

+ * to:

+ * - Edit and reformat your source code.

+ * - Compile and verify errors.

+ * - Debug your code on the target board both in high level language and

+ *   assembler.

+ * - Generate documentation from your source code.

+ * - Develop embedded applications with or without ChibiOS/RT.

+ * .

+ * The guide is meant mainly for Windows users but notes about Linux and

+ * MAC OSX are present where the setup differs, mostly the toolchain is

+ * exactly the same.

+ *

+ * <h2>What this guide will not explain</h2>

+ * We will not enter in details of common system tasks like and not limited to:

+ * - Installing applications (unless a special procedure is required).

+ * - Creating desktop shortcuts.

+ * - Adding paths to the PATH variable.

+ * - Creating environment variables.

+ * - Any other normal PC usage task.

+ * .

+ *

+ * <h2>Article Index</h2>

+ * - @ref required_components

+ * - @ref install_chibios

+ * - @ref install_compiler

+ * - @ref install_eclipse

+ * - @ref install_zylin

+ * - @ref install_doxygen

+ * - @ref install_graphviz

+ * - @ref install_eclox

+ * .

+ *

+ * @section required_components Required Components

+ * The first thing to do is to download all the required components, beginners

+ * should avoid the optional components initially:

+ * - A JTAG probe supporting GDB and OpenOCD, a list of compatible devices is

+ *   available on the <a href="http://openocd.berlios.de/web/" target="_blank">

+ *   OpenOCD home page</a>, more exactly

+ *   <a href="http://openocd.berlios.de/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware"

+ *   target="_blank">here</a>.

+ * - An STM32 development board (but this guide apply to all the ARM targets

+ *   supported by ChibiOS/RT. This guide describes the Olimex STM32-P103.

+ * - <a href="https://sourceforge.net/projects/chibios/" target="_blank">

+ *   ChibiOS/RT latest stable release</a>.

+ * - <a href="http://www.java.com/en/" target="_blank">Java runtime</a>, you

+ *   probably already have this installed.

+ * - <a href="http://www.eclipse.org/downloads/" target="_blank">Eclipse IDE

+ *   for C/C++ Developers</a>

+ * - <a href="http://www.yagarto.de/" target="_blank">YAGARTO ARM toolchain

+ *   for Windows</a>, note that you need both the compiler and the tools (make

+ *   and binutils).

+ * - Zylin plugin for on-board debugging, see @ref install_zylin section.

+ * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but

+ *   you can download them from <a href="http://www.freddiechopin.info/"

+ *   target="_blank">here</a>. This guide will describe the use with version

+ *   3.1 but it should apply to newer releases as well.

+ * - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"

+ *   target="_blank">MinGW compiler</a>, needed if you want to compile, debug

+ *   and run the simulator from within Eclipse. Linux users do not need this

+ *   one because all Linux distributions include the native GCC.

+ * - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"

+ *   target="_blank">Doxygen</a>, it is only required if you want to

+ *   generate documentation from source files.

+ * - <b>Optional</b>, <a href="http://www.graphviz.org/" target="_blank">

+ *   Graphwiz</a>, it is only required if you want to generate diagrams

+ *   within documentation from source files.

+ * - <b>Optional</b>, <a href="http://home.gna.org/eclox/" target="_blank">

+ *   Eclox</a>, it is only required if you want to generate documentation

+ *   from source files from within Eclipse.

+ * .

+ *

+ * @section install_chibios ChibiOS/RT Installation

+ * Just unzip it into a directory in your home folder, Windows users may

+ * consider c:@\projects@\chibios. It is strongly suggested to not put version

+ * numbers into the ChibiOS/RT directory name because Eclipse workspaces

+ * have absolute paths inside and you don't want to setup everything again

+ * each time a new ChibiOS/RT version is released, use plain "chibios".

+ *

+ * @section install_compiler GCC ARM Compiler Installation

+ * Simply follow the YAGARTO installation guide. Linux/MACOS users have several

+ * other options:

+ * - Download the latest CodeSourcery free Linux package.

+ * - Build it yourself, Liam recommended a build script here:

+ *   http://github.com/esden/summon-arm-toolchain, it looks interesting.

+ * .

+ * Make sure that the compiler binaries directory is listed  in the PATH

+ * variable or Eclipse would not be able to locate it.

+ *

+ * @section install_eclipse Eclipse Installation

+ * Eclipse is distributed into a compressed archive, there is no installation

+ * procedure:

+ * - Verify if you have Java installed, if not install the runtime. You may

+ *   verify this using the command: java -version. Make sure you have at

+ *   least version 1.6.

+ * - Create an eclipse directory in your home and unpack the archive there.

+ *   Windows users may unpack it into c:@\program files@\eclipse.

+ * - Create a desktop shortcut or other way to launch the Eclipse executable

+ *   easily.

+ * - Launch Eclipse.

+ * - Eclipse will ask you a directory for its initial workspace, make it point

+ *   to the ChibiOS/RT root directory (you may have as many workspaces you

+ *   want, keep this for later), make sure to select the check box or it will

+ *   ask you again each time.

+ *   @image html tool001.jpg

+ * - Now you should see the welcome screen, close it and you will be in the

+ *   normal C/C++ perspective.

+ * - Unselect "Project->Build Automatically" unless you like insanity.

+ * - Disable the "usage collector" in Window->Preferences->Usage_Data_Collector

+ *   by unselecting "Enable capture".

+ * - If you are behind a proxy or firewall (corporate users usually are)

+ *   configure the correct parameters in Window->Preferences->General->Network_Connections.

+ * - Let Eclipse auto update to the latest version Help->Check_for_Updates.

+ * .

+ *

+ * @section install_zylin Zylin Plugin Installation

+ * Eclipse requires an hardware debugger component in order to perform on board

+ * execution and debug.

+ * - Open Eclipse, then help->Install_New_Software...

+ * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt

+ *   into the location field, then press OK. The Zylin plugin will appear in the

+ *   available plugins view, select and install it.

+ *   @image html tool002.jpg

+ * .

+ *

+ * @section install_doxygen Doxygen Installation

+ * Just use the installer, Linux users probably have Doxygen already available

+ * from the repositories. Make sure that the Doxygen binaries directory

+ * is listed in the PATH variable or Eclipse would not be able to locate it.

+ *

+ * @section install_graphviz Graphviz Installation

+ * Just use the installer, Linux users probably have Graphviz already available

+ * from the repositories. Make sure that the Graphviz binaries directory

+ * is listed in the PATH variable or Doxygen would not be able to locate it.

+ *

+ * @section install_eclox Eclox Installation

+ * Use the same installation steps used for the Zylin plugin except use the

+ * URL http://download.gna.org/eclox/update. Install "Eclox" not "Eclox Hot".

+ * After installing Eclox you will be able to compile Doxygen documentation

+ * using the button with the blue @@ inside.

+ */