######################################################
##                      INSTALL                     ##
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~##
##                     16-03-2005                   ##
##~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~##
##                                                  ##
##  How to build and install ARTIS on your machine  ##
##                                                  ##
######################################################

- INTRODUCTION

   This document explains the ARTIS installation process. That is,
which are the software dependencies, what you will obtain once you have
installed it.


- EXTRA SOFTWARE TOOLS

   ARTIS is not only an agent architecture, it also provides a set of tools
to design applications for it.

   - Kiwi:
   
         A graphic tool to display the trace data corresponding to an execution
      of an ARTIS application.
   
   - Trace Tools:
   
         Tools used to trace the execution of ARTIS applications. mem2trace and
      trace2kiwi help the user to extract the tracing data and to translate it to
      .ktr format (which is the format kiwi understands).
   
   - TNT:
   
         A graphic tool-kit to design ARTIS applications easily. TNT generates a
      set of XML files which contain the specification of the ARTIS application.
      
   - XML parsers:
   
         A set of programs to generate the C source code corresponding to the XML
      generated by TNT.
   
   - Templates:
   
         A set of templates that are useful to create new ARTIS applications from
      scratch (i.e: without using TNT).
   
   - Scripts:
   
         A set of scripts that are useful to create from scratch and run ARTIS
      applications.
   

- SOFTWARE DEPENDENCIES

   Before describing the installation process of ARTIS, it is necessary
to specify every software dependency.

   - Linux and RT-Linux
   
         The version of RT-Linux for which ARTIS has been developed is
      rtlinux-3.2-pre1 (free version) and the Linux kernel to be patched
      should be an standard 2.4.18 or 2.4.27 kernel
      
         Probably ARTIS can also be run over later versions of Linux and
      RT-Linux, but since they have not been tested, we can't be sure of
      that...
      
      The Linux kernel can be obtained from http://www.kernel.org/ and the 
      RT-Linux kernel can be obtained from http://rtportal.upv.es/
   
   - Java
   
         To run TNT, the graphic toolkit to design ARTIS applications, you
      will need to install JDK5 or later. JDK and other Java utilites can
      be downloaded from http://java.sun.com/
   
   - ARTIS XML parsers
   
         In order to generate ths C source code from the XML files which are
      generated by TNT, you will need to have the expat XML parser installed
      on your computer. It can be obtained from http://expat.sourceforge.net/
   
   - Tcl/Tk
   
         To run kiwi, you will have to have Tcl/Tk 8.0 or later installed on
      your computer. You can obtain it from http://www.tcl.tk/


- HOW TO BUILD AND INSTALL ARTIS

   To build and install ARTIS on your machine you just have to
execute the following:

   cd <artis_src_dir>/make
   make
   make install

   Once you have made this, ARTIS will be installed in /usr/local/artis


- HOW TO UNINSTALL ARTIS

   To uninstall ARTIS from your computer just execute the following:
   
   cd <artis_src_dir>/make
   make uninstall
   
   Once you have made this, ARTIS will be uninstallled from your computer.
   
- HOW TO RUN ARTIS EXAMPLES

   Some ARTIS examples are found in <artis_src_dir>/tests

   The names of the examples are hello_world, producer_consumer and
   prod_cons_incremental. To build them and run them just execute the
   following in the directory of the test you want to run:

   cd <artis_src_dir>/tests/<example_dir>
   make
   rtload [<execution_time_in_seconds> <trace_file>]

   If you don't specify the execution time and the trace file the example runs
   until you execute
   
   rmmod rtl_tasks

   Take into account that if ARTIS has been built with trace support, it will
   generate a lot of tracing data and it may fill your HDD!!!