DX Development Environments

Ian Tree  10 May 2012 12:24:52

The Domino eXplorer Development Environments

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.

Project Directory Structure

The default Domino eXplorer development environment follows the Visual Studio paradigm of a “Solution” directory that contains multiple “Project” directories with a single application directory per application, this paradigm is followed on both Windows and Linux development environments.

Solution Directory - [any name]    Common Code Sub-Directory - "DXCommon"    Application Project Directory - [Application Name]

In Visual Studio the DXCommon project directory should have the “Do Not Build” property set.

The standard DX header and code files are NOT designed to be added to the default include search directories on either environment. The package expects to find a directory called “DXCommon” as a project level directory in each solution directory that will be used to build DX applications, these should be included in applications by relative re-direction. An include statement for the PlatBase.h header file that is located in the “Platform” sub-directory of the DXCommon package would be coded as follows.

//  Platform Includes #include        "../DXCommon/Platform/PlatBase.h"        //  Basic platform includes

Although a copy of the DXCommon package could be physically placed in each solution directory it would be more usual to place the package in a shared location on the development workstation/server and then create a symbolic link in each of the solution directories.

Windows:

The DXCommon kernel is supplied as a zipped archive (.zip). The contents of the archive should be unpacked to either the \DXCommon directory or unpacked to a directory that will then be used as the base for a symbolic link from the \DXCommon directory.
As an example.
Unpack the DXCommon kernel into a directory “c:\usr\include\DXCommon-3.14.0” and then create the symbolic link from within the solution directory using the following command.

  mklink /D DXCommon “c:\usr\include\DXcommon-3.14.0”

Linux:

The DXCommon kernel is supplied as a gzipped archive (.tar.gz). The contents of the archive should be unpacked to either the /DXCommon directory or unpacked to a directory that will then be used as the base for a symbolic link from the /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.14.0” and then create the symbolic link from within the solution directory using the following command.

  ln -s /usr/include/DXCommon-3.14.0 DXCommon

This deployment model allows different levels of the DXCommon package to be used in different solutions without reconfiguring the development environment.

Building DX Applications

Windows (32 bit):

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	notes.lib	notes.lib Dbghelp.lib Psapi.lib

Windows (64 bit):

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;NT;W32;W;W64;ND64;_AMD64_;ND64SERVER	WIN32;_DEBUG;_CONSOLE;NT;W32;W;W64;ND64;_AMD64_;ND64SERVER
Code Generation
Runtime Library	Multi-threaded (/MT)	Multi-threaded Debug DLL (/MTd)
Struct Member Alignment	Default	Default
Command Line
Additional Options	/Oy-	/Oy-
Linker
Input
Additional Dependencies	notes.lib	notes.lib 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. IMPORTANT: Do not set this option for Windows x64 (64 bit) builds, Notes uses the default structure packing on Windows 64 bit.
/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 ”.

Linux:

A makefile is supplied in the source distribution of any distributed DX application. The makefile is listed below along with any specific notes. The Makefile supports the following invocation models.

  make [application name]

This form of the command will build any object modules that are out of date and re-link the executable.

  make rebuild [application name]

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

  make rebuild [application name] BVÛG

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 following shows the common compile and link options used in DX application makefiles.

#  Define the build options CC = g++ CCOPTS = -c -march=i486 NOTESDIR = $(LOTUS)/notes/latest/linux LINKOPTS = -o [application name] DEFINES = -DUNIX -DLINUX -DHANDLE_IS_32BITS INCDIR = $(LOTUS)/notesapi/include LIBS = -lnotes -lm -lnsl -lpthread -lc -lresolv -ldl DEFINES = -DUNIX -DLINUX -DHANDLE_IS_32BITS

Deploying DX Applications

Windows:

Copy the resulting executable (.exe) and the associated Program Debug Database (.pdb) to the Notes Executable directory on the server or workstation where you want to run the Add-In or command processor.

Linux:

Copy the resulting executable () to the Notes Executable directory where you want to run the Add-In or command processor. According to your local security policies and Domino install you may need to have an administrator copy the executable and possibly change ownership of the executable. Note that the application name is folded to lower case if it is to be used on a server as certain interfaces coerce the name to lower case.

The default ownership and attributes indicated by the Notes API documentation are as follows.

chown server [application name] chgrp notes [application name] chmod 2555 [application name]

Deploying DX Databases

Any application supplied as a standard DX Tool that uses a database distributes the database as a "Virtual Template", these are Notes Database designs that are delivered via the internet in DXL source format.
The installation of the control database is done from a “Virtual Template” that is available on the internet, this section assumes that you have available and installed the Remote Database Create (Windows:
RDBCreate.exe and RDBCreate.pdb Linux: rdbcreate) tool. If you do not have this tool then download the DXTool source for RDBCreate and build it. Refer to the “Using RDBCreate” manual.

From a command window go to the Notes Executable directory where RDBCreate exists enter the following command.

  RDBCreate [server name] [database name] [templateURL] -V

Where:

[server name] is the abbreviated name of the server on which you want to install the control database.
[database name] is the name of the control database relative to the notes data directory.
[templateURL] is the URL for the Virtual Template you wish to install.

For example the QCopy Control Database, uses the following template URL:
http://hmnl.nl/HMNL/DX/VTTDepot.nsf/Payloads/qcopy22.manifest/$File/manifest.xml

LINKS

Information	Source Packages	Documentation	Articles
Background DX Reference Environments DX Development Environments DX Support DX Services Frequently Asked Questions License	DX Common Code QCopy QMove QACLMorph RDBCreate DXIPA DXTell SPZap	DX Application Design Guide DX Kernel API Reference DX Component Architecture DX Class Catalogue Using QCopy Using QMove Using QACLMorph Using RDBCreate Using DXIPA Using DXTell Using SPZap	Heavy Lift Computing Autonomic throughput optimisation

• Comments [0]