/*
    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.
 * details This article will explain how to setup a free toolchain for use with
 * ChibiOS/RT and general embedded development.<br>
 * 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 does not cover</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.
 * - Use of the toolchain, the use is covered by the @ref article_eclipse2
 *   article.
 * .
 *
 * <h2>Article Index</h2>
 * - @ref required_components
 * - @ref install_chibios
 * - @ref install_compiler
 * - @ref install_eclipse
 * - @ref install_zylin
 * - @ref install_openocd
 * - @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>.
 * - <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>. Linux users can try
 *   <a href="http://home.comcast.net/~mcatudal/" target="_blank">here</a>.
 * - <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
 *   <a href="http://github.com/esden/summon-arm-toolchain" target="_blank">
 *   here</a>, 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.
 *   <br><br>
 *   @image html tool001.jpg
 *   <br>
 * - 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.
 *   <br><br>
 *   @image html tool002.jpg
 * .
 *
 * @section install_openocd OpenOCD Installation
 * Windows users just have to use the installer. Linux user should follow the
 * normal installation procedure for deb or rpm packages, of course it is also
 * possible to build it from the source code.
 *
 * @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
 * http://download.gna.org/eclox/update as URL. Install "Eclox" not "Eclox
 * Hot".
 * After installing Eclox you will be able to compile Doxygen documentation
 * using the button with the blue @@ inside.
 */