Getting Started
===============

Installation
------------

On Windows host, installation is performed automatically by **InstallShield**.
On Linux host, you will need first to unpack the package using :file:`tar`
utility and then launch the :file:`doinstall` script located at the toplevel
directory. In both cases, you will be prompted for an installation directory
for the simulator and the example
(later referred to as :envvar:`GNATEMULATOR_INSTALL_DIR`).

If you are using **GNATemulator** for **VxWorks 653** then once the product
is installed, you should install the BSP in the **VxWorks 653** installation.
In order to do that you need to copy the
:file:`%GNATEMULATOR_INSTALL_DIR%\\share\\gnatemulator\\ppc-vx653\\bsp\\qemu`
directory as :file:`%WIND_BASE%\\target\\config\\qemu`.

Note that the PATH to the target BSP directory that you are copying to
may be slighty different depending on your version of **VxWorks 653**.
Note in particular that this BSP uses the PPC604gnu toolchain, which is
not available on 653 2.4; so this version of 653 is not supported. 
On 653 2.5, you will also need to add ne2000End.o to the library, for
instance by doing the following:

.. code-block:: bat

  cd %WIND_BASE%\target\lib
  arppc x libPPC604gnuvx.a ne2000End.o
  cp ne2000End.o objPPC604gnuvx\ne2000End.o

Setting your environment
------------------------

In order to set your environment for **GNATemulator** you need to do on
Windows:

.. code-block:: bat

  set PATH=%GNATEMULATOR_INSTALL_DIR%\bin;%PATH%

And on Linux:

.. code-block:: bash

  export PATH=$GNATEMULATOR_INSTALL_DIR/bin:$PATH

Where :envvar:`GNATEMULATOR_INSTALL_DIR` is the root directory of your
installation.

If you need to build your own devices using **GNATBus**, then you should
also do on Windows:

.. code-block:: bat

  set ADA_PROJECT_PATH=%GNATEMULATOR_INSTALL_DIR%\lib\gnat;%ADA_PROJECT_PATH%

And on Linux:

.. code-block:: bash

  export ADA_PROJECT_PATH=$GNATEMULATOR_INSTALL_DIR/lib/gnat:$ADA_PROJECT_PATH

Note that if **GNATemulator** has been installed in the same location as your
native compiler then you don't need to modify :envvar:`ADA_PROJECT_PATH`
environment variable.

Running the examples
--------------------

In the following subsections, small examples are described for each supported
platforms except **VxWorks 6.x**. The examples sources are located in
:file:`%GNATEMULATOR_INSTALL_DIR%/share/examples/gnatemu/`. To get started on
**GNATemulator** for **VxWorks 6.x**, you should go directly to
:ref:`vx6-topics`.

.. toctree::

   vxworks653-example.rst
   leon-elf-example.rst
   leon3-elf-example.rst
   p55-elf-example.rst
   ppc-elf-example.rst
   arm-elf-example.rst
