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. Customize the framework to enable or disable support for specific
features.
3. Download and extract the source code into a specific directory and set
the EMPACT_DIR environment variable to point to this directory.
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 means
is 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.
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.
