Read Me

Before Building the Library
---------------------------
Before you start building the library, you have to decide what features
you want in your library. For example, if you think you will need support
for the Lua scripting language or the SQLite database, you can enable
support for those libraries in the framework. 

Once you decide to install a particular set of features in the framework,
you need to do the following:
1. Install all the prerequisite libraries (eg: Lua or SQLite) on your
   development environment.
2. Download and extract the source code into a specific directory and set
   the EMPACT_DIR environment variable to point to this directory.
3. Customize the framework to enable or disable support for specific
   features.

Depending on what platform or OS you plan to build your framework on, the
steps to install prerequsites may change. For a list of prerequisites we
use, check the PACKAGES file in the root directory of the install. You
will also want to check out the BUILDING file that outlines all the
built-in and optional packages you may require to customize the 
framework.

Documentation
-------------
Documentation is generated automatically using the ClassDoc tool included
in the framework. A recent version of the generated files is available 
in the root directory as a docs.tar.gz. You will need to unzip it 
before you read it. The index to the documentation is in the file 
index.xml that you will find in the extracted documentation directory.


Customizing the Library
-----------------------
There are several macros that are used to customize the framework. The 
available flags are setup in the following file.

$(EMPACT_DIR)\code\external\include\common\econfig.h

Some modules are loaded dynamically at runtime. For example, the framework
does not directly link to the SQLite library, but loads it dynamically at
runtime. To configure what specific shared library (or DLL) gets loaded
at runtime you can configure the macro declarations in the following file.

$(EMPACT_DIR)\code\external\include\common\dsocfg.h

For more specific details on customizing your install, please read the 
BUILDING file in this distribution.


Reporting bugs
--------------
If you have a bug or feature request you would like us to look at, please 
open a ticket online. The URL is as follows:

http://sourceforge.net/p/empact/tickets/


Building on Win32
-----------------
You require Visual Studio 2010 or better to build the Empact framework. 

1. Install the external libraries for the project. The prerequisite 
   external libraries are part of the package external.tar.gz. Copy it and 
   unzip it into a suitable directory.
2. Extract and unzip the empact.tar.gz library into a suitable directory. 
3. Setup the environment variable $(EMPACT_DIR) to point to the root of 
   the empact extract.
4. Setup the environment variable $(EXTERNAL_DIR) to point to the root 
   of the external extract.
5. Open the workspace empact/libs/core/win32/core.sln
6. Build the solution.

(Optionally, you can also build on Visual Studio 6.0. The workspace files 
are typically in the same directory as the Visual Studio 2010 solutions.)

Building on Linux
-----------------
You require a number of packages to build the Empact framework. A 
comprehensive list is available in the file PACKAGES. 
1. Once all the prerequisite packages are installed the build follows 
   the standard GNU autoconf/automake methodology. For instructions 
   refer the INSTALL file. But basically you make the following calls 
   from the root directory.

   aclocal
   autoconf
   automake
   ./configure
   make

2. The detault build will copy all the binaries to 'lib' directory under
   the source code root. To allow applications build using the library 
   to pick up the binaries from this lib directory, you will need to 
   set the LD_LIBRARY_PATH environment variable. You can set this up 
   in your .bashrc in your root directory (assuming you are using the 
   bash shell). You do this by the following command in your .bashrc.

   export LD_LIBRARY_PATH='/home/myusername/pathtoempact/lib'



Building on FreeBSD
-------------------
************ NOTE: The FreeBSD build is experimental ************
The FreeBSD build may be broken. The following steps will give you a fully
compiled binary that runs alright. You should be able to run the samples
in general. But there is a known bug that the application will crash when 
an exception is thrown from the framework. This is very likely a GCC 
setting in the build. We are currently not focusing on this issue, but 
will in the near future. If you do figure out what the issue is, please 
let us know and we will make it part of the build.

1. As of FreeBSD 10.0, gcc is not part of the main build system. What 
   this meansis that although you may have gcc installed, it will not be 
   your default compiler. To fix this problem you will need to create 
   appropriate symbolic links to the gcc compiler. You will do something 
   like the following (Note: that the sample assume that you have gcc49, 
   check your system /usr/local/bin for the appropriate gcc version).

		# cd /usr/local/bin
		# ln -s gcc49 gcc
		# ln -s g++49 g++

  The current build environment is also not compatible with BSD. So the 
  build will fail in the copy step. This is because the default build  
  attempts to copy the libraries to /usr/lib. A temporary fix to the  
  problem is to explicitly set the default directory in the configure  
  step. So the build will be something like the following

	   aclocal
	   autoconf
	   automake
	   ./configure --prefix=/home/myusername/pathtoempact
	   make

   This should build all the files for the library, but will fail during 
   the copy step as with the default build. To rectify this, execute the 
   following command to copy the files to the appropriate 
   $(EMPACT_DIR)/lib directory.
	   make install-exec 

   This is currently a workaround. We'd like to fix it, so if you are a 
   FreeBSD guru and are familiar with autotools, perhaps you can take a  
   crack at it. We'd like to hear from you if you have a fix. Our contacts
   are in the AUTHORS file in the root directory.

2. The detault build will copy all the binaries to 'lib' directory under 
   the source code root. To allow applications build using the library to 
   pick up the binaries from this lib directory, you will need to set the 
   LD_LIBRARY_PATH environment variable. You can set this up in your 
   .bashrc in your root directory (assuming you are using the 
   bash shell). You do this by the following command in your .bashrc.

	   export LD_LIBRARY_PATH='/home/myusername/pathtoempact/lib'



Building the samples
--------------------
There are several samples in the $(EMPACT_DIR)\samples directory that 
demonstrates and tests individual features of a particular module. These
samples are not built along with the main build you will need to go the
directory of a specific sample and build the application from the 
particular directory.

We are moving toward a standard testing framework. This framework is 
built into the 'utils' library of the framework. 

All samples using this framework build executables that work in a similar 
fashion. The samples allow you to execute individual modules, individual 
tests or entire suites depending on your testing requirements. To get 
started with a sample for example named 'mysample', execute the following 
command to get all the options available to you.

./mysample -h

Supported Operating Systems
---------------------------
The current supported operating systems include the following:
Windows 2003 and above
Windows XP and above
Ubuntu Linux 14.04

The system should compile on any modern POSIX compliant operating system. 
But we do not test support extensively during development. If you are 
testing the library on an alternate operating system we would like to hear 
back from you about your experience. Contact us using the information in
the AUTHORS file in the root directory and we will help you make it part
of the next release if a change is required to make Empact work for you.