		       G N A T   E X A M P L E S
		       =========================

This example features a dynamic plugin facility implemented with the
Operating System Dynamic Library facility and the GNAT Pro Standalone
libraries support. The UNIX Version is described in this README, but 
the Windows version is roughly similar.

This example comprises a main program which probes regularly for the
existence of shared libraries in known location. If such libraries
are present, it uses them to implement features initially not
present in the main program.

Building and Running the application
------------------------------------

The application can be built using the set of project files provided in
this directory.  The 'base' project is shared by the 'main' project,
which is used to compile the main program, and the 'clocks', 'gauges'
and 'speedometers' projects used to build the plugins. 

These projects are differenciated to use the right operating system
facilities. To do so, they use an external variable called OS_Name that
can take two values: Unix or Win32.

To build on Unix, you can therefore do:

        gnatmake -XOS_Name=Unix -Pmain

The main program is called 'demo'. You can start it immediately by doing 
"./demo". Demo first ask for an increment in milliseconds. Type for instance
'1000' and press enter. As there is no available plugin for the time being,
'demo' just loops endlessly. If we build now the first plugin:

	gnatmake -XOS_Name=Unix -Pgauges

'demo' will be able to discover the newly built library (see Discover_Plugins)
and then load it (see Plugins.Load) using a binding to the dlopen () function
provided by the C library. Then 'demo' will use Plugins.Call to 
1) retrieve an access to a symbol in the dynamic library using the dlsym ()
   routine.
2) call the routine pointed to by the returned address 

Therefore, we can see that the output of 'demo' changes at the next iteration
after the compilation of gauges has completed. If you compile the remaining 
examples now:

        gnatmake -XOS_Name=Unix -Pclocks
        gnatmake -XOS_Name=Unix -Pgauges
        gnatmake -XOS_Name=Unix -Pspeedometers

those new features will appear as well.

Features tested
---------------

A number of interesting features are used by this example:

* The main.gpr project is configured with the OS_Name variable;
  according to the values of this variable, different bodies are
  used for the system-speciifc Plugins package. 

* The 'gauges', 'speedometers' and 'clocks' use standalone libraries.
  Examine the attributes contained in the projets, which describe the
  corresponding library. The meaning of most of them is obviousr. 
  'Library_Interface' is specific to standalone libraries, that is 
  libraries that contain all the required elaboration code to be
  used whatever the main is. The 'Library_Interface' is a list of
  units that are made visible by the library.

* the Dash_Board package instanciates the Ada.Containers.Vector package.

* The Hashed_Strings package is an instanciation of the 
  Ada.Containers.Hashed_Sets package.

* The procedure Discover_Plugins in procedure Demo used the
  Ada.Directories package to search for new shared libraries.
