mars-flaim/README.W32

flaim-projects README.W32 file 
==============================

Contents:
--------
1. Tools for Building on Windows
2. FLAIM Runtime Library Use
3. GUI or Command-Line Build
4. Legacy Makefile

Tools for Building on Windows
-----------------------------

Visual C++ 2008 Express is good, but more to the point, it's free.
To build the FLAIM projects, you will need to download and install 
Visual C++ 2008 Express (which now thankfully comes with a reasonably 
late version of the Windows Platform SDK).

You can get Visual C++ 2008 Express here:

   http://www.microsoft.com/express/vc

The ">> Download Now!" link on that page, and decide whether you want to
install from the web (slow) or install off-line (also slow - there's no 
fast solution, sorry). 

Once Visual C++ 2008 Express has been installed you may simply double 
click on any of the flaim project solution files to bring up the flaim 
project in the Visual C++ 2008 IDE. Use the main or context menu options 
to build the desired targets.

The flaim project solution files are located in the win32 directories
in the following locations:

trunk\flaim
   flaim\win32\flaim    - flaim.sln
   ftk\win32\ftk        - flaimtk.sln
   sql\win32\sql        - flaimsql.sln
   xflaim\win32\xflaim  - xflaim.sln
   win32\flaim-projects - flaim-projects.sln 

The projects may be build individually from each of the lower-level 
solution files, or all at once from the flaim-projects solution file.

WARNING: The flaim-projects solution file refers to the same project
files as the individual lower-level solution files, so if you make 
changes in one of these, they'll be reflected in the other.

FLAIM Runtime Library Use
-------------------------

FLAIM libraries - both static and dynamic - and the flaim utilities
consume the dynamic (DLL) form of the Visual C++ 2008 runtime libraries. 
This is in alignment with the use of runtime libraries on Unix platforms.
It's more efficient and flexible to use the DLL versions of these libraries, 
and it allows Microsoft to update these libraries as necessary to fix 
security holes and defects which may be found in the future.

With each new version of Windows and Microsoft tools, Microsoft 
platforms become more security minded - and more secure. This is 
generally done by copying features from Unix platforms into the Windows 
operating system and into the tools themselves. Visual Studio 2008 is no 
exception. The most significant security feature in Visual C++ 2008 (IMHO)
is secure package deployment and executable module manifests. This is nothing
less than the direct equivalent of RPATH's in Unix and Linux, and the usual 
security features - and annoying issues - come along with it.

The Visual C++ 2008 runtime libraries include MSVCR90.DLL, MSVCP90.DLL and 
MSVCM90.DLL, which represent the C standard library, the C++ standard
library, and the C math library, respectively. These libraries may no 
longer be simply dropped into the same directory as your executable and 
consumed. Executables and consumer DLL's need to be configured to build 
with a manifest file (a default setting for new projects), and the runtime 
libraries need to be "deployed". Deployment consists of running a 
significant algorithm to determine platform requirements and features, 
and making the right decisions to install these runtime libraries. 

Developers (like you) will not have a problem executing your own 
projects built against the FLAIM libraries because you've installed VC8, 
which consumes the VC8 runtime libraries, and so deploys it during its
install process. For more information, see this excellent article on 
the CodeProjects website:

   http://www.codeproject.com/cpp/vcredists_x86.asp

GUI or Command-Line Build
-------------------------

The flaim SVN repository is divided into four sub-projects, named for the 
sub-directories in which they reside:

  * flaim
  * ftk
  * sql
  * xflaim

Each of these sub-projects is a complete project in its own right. However,
the flaim, sql and xflaim projects each depend on the flaimtk libraries built
by the ftk project, and on the flaimtk.h header file.

When one of these higher-level projects is is built from the 
flaim\win32\flaim-projects directory, using the flaim-projects.sln solution 
file or the buildall.cmd file in that directory, the dependencies are managed 
for you by this umbrella solution. 

However, when you build one of these three higher-level database projects by 
themselves, using the <project>\win32\<project>\<project>.sln solution file,
then you need to provide the location of the flaimtk libraries and the 
flaimtk.h header file by setting a few environment variables in the 
environment from which you launch the VC++ 2008 IDE, via the "devenv" command,
as in the following command sequence:

  c:> set FTKINC=c:\full\path\to\ftk\src\directory
  c:> set FTKLIB_STATIC_DEBUG=c:\full\path\to\debug\flaimtk_static.lib
  c:> set FTKLIB_STATIC_RELEASE=c:\full\path\to\release\flaimtk_static.lib
  c:> set FTKLIB_DEBUG=c:\full\path\to\debug\flaimtk.lib
  c:> set FTKLIB_RELEASE=c:\full\path\to\release\flaimtk.lib
  c:> devenv <project>.sln

(or) 

  c:> buildall.cmd [debug|release]

NOTE: You may also use relative paths in these variables, but this is tricky, 
because each project is built from the directory containing the solution 
(.sln) file, so you'll have to calculate these paths relative to the 
flaim/win32/flaim directory, as that's where the flaim.sln file is located.

Legacy Makefile
---------------

There is also a legacy makefile (GNUMakefile) that has been hand written 
to target flaim for all of the platforms that flaim currently supports. If you
don't want to use autotools, and you don't feel comfortable in the Visual C++
2008 IDE, then you may build for windows by simply running make from the root 
of the FLAIM project. This makefile accepts multiple auxilliary targets, which 
modify the build in various ways. These auxilliary targets include:

   debug
   release
   32bit
   64bit
   verbose
   usegcc
   flm_dbg_log

True build targets include:

   libs (default) - flaim libraries (static and dynamic)
   checkdb - checkdb.exe
   rebuild - rebuild.exe
   view - view.exe
   ut_basictest - basic unit tests
   sample - sample.exe

CAVEAT: We're trying to phase out the legacy GNU makefile build system, so:

1) Don't expect it to last forever, and 
2) Don't be surprised if it doesn't work all the time

Enjoy!