
DXIPA Installation Notes
========================

1.	Reference Environments
------------------------------

DXTools and the DXCommon kernel are portable across multiple platforms that support 
the Notes API. However there are a limited set of reference environments on which they 
are regularly built and regression tested.

Windows:

Build Environment:

Microsoft Visual Studio 2005
Version 8.0.50727.867  (vsvista.050727-8600)
Running on any supported windows workstation.
Note:  Backward compatibility tests are done with Visual Studio 2003 as that is the 
officially supported development platform for the Notes API.
Notes API Version 8.5.

Execution Environment:

Windows Standard Server 2008 R2 (32 bit).
Domino Server 8.5.1 FP3.
Note: Execution environments from Domino 6.5.x through 8.5.x are regularly used.

Linux:

Build Environment:

Gcc Version: 4.1.2 for i386-redhat-linux.
Running on Redhat Linux 2.6.18-238.12.1.el5PAE #1 SMP Sat May 7 20:37:06 EDT 2011 i686 i686 i386 GNU/Linux
Notes API Version 8.5

Execution Environment:

Redhat Linux 2.6.18-238.12.1.el5PAE #1 SMP Sat May 7 20:37:06 EDT 2011 i686 i686 i386 GNU/Linux
Domino Server 8.5.1 FP3.
Note: Execution environments from Domino 7.0.x through 8.5.x are regularly used.


2.	Notes API Installation
------------------------------

For both Windows and Linux DXTools assumes that the Notes API is installed in the default 
configuration specified in the API documentation.

3.	Directory Structure
---------------------------

For both Windows and Linux DXTools uses a reference development directory structure based on 
the Visual Studio structure.

The DXCommon kernel modules should be deployed in a directory called "DXCommon" (physical or
virtual) that is contained within one or more "Solution" directories. All applications that 
use the kernel should be deployed within that (or these) solution directories.

In Visual Studio the DXCommon project directory should have the Do Not Build property set.
In both the Windows and Linux environments it is possible to use a symbolic link for the 
DXCommon directory. This is a common deployment pattern for development environments where 
different versions of an API might need to be supported.

4.	Installing the DXCommon Kernel Sources
----------------------------------------------

Windows:

The DXCommon kernel is supplied as a zipped archive (.zip). The contents of the archive should be 
unpacked to either the <solution directory>\DXCommon directory or unpacked to a directory that will 
then be used as the base for a symbolic link from the <solution directory>\DXCommon directory.

As an example.
Unpack the DXCommon kernel into a directory c:\usr\include\DXCommon-3.12.0 and then create the 
symbolic link from within the solution directory using the following command.

mklink /D DXCommon c:\usr\include\DXcommon-3.12.0


Linux:

The DXCommon kernel is supplied as a gzipped archive (.tar.gz). The contents of the archive should be 
unpacked to either the <solution directory>/DXCommon directory or unpacked to a directory that will 
then be used as the base for a symbolic link from the <solution directory>/DXCommon directory.
File ownership and access settings should be adjusted according to your local policies.

As an example.
Unpack the DXCommon kernel into a directory /usr/include/DXCommon-3.12.0 and then create the symbolic 
link from within the solution directory using the following command.

ln -s /usr/include/DXCommon-3.12.0 DXCommon


5.	Installing the DXIPA Sources (Windows)
----------------------------------------------

The DXIPA sources are supplied as a zipped archive (.zip). Create an empty project called DXIPA in 
the <solution directory>. Then unpack the contents of archive into the project directory and add each 
of the source and header files to the project.

Header Files

AppRunSettings.h
DXIPA.h

Source Files

AppRunSettings.cpp
DXIPA.cpp

Add each source and header file that is used from the DXCommon kernel to the DXIPA project. To populate the individual filter right-click on the filter then select Add then Existing Item navigate to the required source or header file(s), select the file(s) and click the Add button. The contents of each filter are listed below.

Header Files
DXCommon\Platform\PlatBase.h
DXCommon\Platform\WCompat.h
DXCommon\RunSettings.h
DXCommon\Misc\AutoScaleFrequencyAnalyser.h
DXCommon\Threads\ThreadStructs.h


Source Files
DXCommon\RunSettings.cpp
DXCommon\Misc\AutoScaleFrequencyAnalyser.cpp



6.	Installing the DXIPA Sources (Linux)
--------------------------------------------

The DXIPA sources are supplied as a gzipped archive (.tar.gz). Create the DXIPA project directory within 
the <solution directory> unpack the contents of the archive into that directory.


7.	Building the DXIPA Application (Windows)
------------------------------------------------

The following non-default settings should then be made to the project settings. 
Any other settings should not prevent a successful build.

Section/Entry				Release Setting				Debug Setting

General		
   Character Set			Not Set					Not Set
		
C/C++ 		
   Preprocessor		
      Preprocessor Definitions		WIN32;NDEBUG;_CONSOLE;W32		WIN32;_DEBUG;_CONSOLE;W32
   Code Generation		
      Runtime Library			Multi-threaded (/MT)			Multi-threaded Debug DLL (/MTd)
      Struct Member Alignment		1 Byte (/Zp1)				1 Byte (/Zp1)
   Command Line		
      Additional Options		/Oy-					/Oy-
		
Linker		
   Input		
      Additional Dependencies							Dbghelp.lib Psapi.lib

Notes:

Static linking of the runtime is used as since the advent of Side-By-Side (SXS) assembly of 
applications it is increasingly common to find server environments that do not have the latest 
C/C++ Runtime manifests installed.
/Zp1 packing is a Notes API requirement as all Notes API structures are packed and not padded 
or member aligned.
/Oy- is an important setting, without it the compiler will use the Frame Pointer as a general 
purpose register rather than pointing to the current frame, this will cause any NSD dump to be 
complete garbage and make debugging virtually impossible.
The additional libraries for the debug settings Dbghelp.lib and Psapi.lib are used to enable 
additional debug capabilities such as memory leak detection that are provided by DXCommon kernel 
modules.

Select Build and then Build DXIPA.
The DXIPA application does not activate a Notes runtime so it can be run from anywhere.

8.	Building the DXIPA Application (Linux)
----------------------------------------------
Specify one of the following make commands to build the application.
make DXIPA
This form of the command will build any object modules that are out of date and re-link the executable.

make rebuild DXIPA

This form of the command will force a rebuild of all object modules and re-link the executable.

make rebuild DXIPA BV=DBG

 This form of the command will force a rebuild of all object modules with the _DEBUG define set and will re-link the executable.

The DXIPA application does not activate a Notes runtime so it can be run from anywhere.

