CONFIGURING APL
==============================================================================
General instructions for configuring the APL interfaces for a specific 
application and/or project.

Configuration for APL is a two step process.  Step one provides configuration
for the target platform.  This configuration is typically shared acrossed many
projects.  Step two provides configuration specific to a given project and/or 
application.


Platform Configuration
------------------------------------------------------------------------------
1. Select the desired/needed target configuration for your application's 
   platform from the apl/platmappings/ directory sub-tree.  If the needed 
   target configuration does not exist, you will need to create a new one or 
   modify an existing target configuration.  See porting.txt for details on 
   porting APL to a new target.  Note: If needed, the application can have its 
   'own' platform configuration (i.e. the platform configuration is specific 
   to the application).

2. Once the target configuration has been selected/created, modify the
   application build script(s) to point to the the target configuration's
   './platform/' sub-directory.  For example: Desired target configuration is
   for Posix user applications, then add the following to your makefile
        -I$(srcroot)/src/apl/platmappings/ansi

    Note: A application can have multiple './platform/' directories.  The only
          requirement is that there is one and only 'mapping' header file
          per interface file.
           
3. Modify the application build script(s) to build the target platform 
   specific code and/or link the neccesary libraries.



Application Configuration
------------------------------------------------------------------------------
1. Various APL interfaces require compile time configuration information.  
   This information is provided via the 'aplcfg.h' header file, which 
   typically resides in the project's root source directory.  
   
2. The 'aplcfg.h' header file should contain:
    - Pre-processor compile time directives, such as:
        #define USE_APL_LITTLE_ENDIAN

    - Application specific types, constants, etc. that override the default
      settings/values of the interfaces, such as:
        #define OPTION_APL_MEMTHIN_SIZE_HEAP    256

   NOTE: In general, do NOT include other header files.  Almost all APL
         header files are directly/indirectly dependent on the 'config.h'
         header file.  Any header file(s) that 'aplcfg.h' is dependent on,
         so are the APL interfaces.

3. Modify the application build script(s) to build the implemenation 
   directories of the required interface(s). In some cases, there are several 
   implementations of a given interface. ONLY include the desired 
   implemenation (the linker will happly complain if you accidentally include
   multiple implementations).