Defining Project Tags

All project tags must be defined in src\build-system\project_tags.txt prior to use. Tag names should be easily recognizable and classifiable, like ‘proj[_subproj]’, e.g. “pubchem” or “pubchem_openeye”.

Once defined in project_tags.txt, project tags can then be associated with any number of projects by using the PROJ_TAG macro in the Makefile.in or Makefile.*.{app|lib} for the selected projects. Project tag definitions apply recursively to subprojects and subdirectories (similar to a REQUIRES definition), thereby removing the need to define tags in all makefiles in a subtree. Subprojects may define additional tags, or undefine inherited tags by prefixing a hyphen '-' to the tag.

The syntax for defining (or undefining) a project tag is:

PROJ_TAG = [-]mytag1 [[-]mytag2...]

For example, if Makefile.in has this line:

PROJ_TAG = foo bar

and a project beneath it in the tree hierarchy (say Makefile.*.app) has this line:

PROJ_TAG = xyz -bar

then the latter project's effective tag definition is:

PROJ_TAG = foo xyz

Filtering with Project Tags

A tag filter can be constructed from one or more project tags – either as a single tag or as a Boolean expression of tags. Boolean expressions of tags can include grouping (parentheses) and the '&&' (AND), '||" (OR), and '!' (NOT) operators, for example: (core || web) && !test

Note: An asterisk '*' or an empty string can be used in place of a tag filter in the "Allowed project tags" field on the Configuration tab of the configuration GUI. These values are not filters, but simply indicate that all projects in the build scope will be passed to the configuration process without filtering.

The following places are searched in the order given for the tag filter to use (if any) in the configuration process:

1.

The "Allowed project tags" field in the configuration GUI (if the configuration GUI is being used).

2.

A tag filter definition line in a project list file (if one is being used).

a.

To use a project list file for configuration, either specify the project list file in the "Subtree, or LST file" field on the Configuration tab of the configuration GUI or use the --with-projects=FILE argument for the configure script.

b.

When one project list file includes another, only the original will be scanned for a filter. This applies to both interactive (i.e. with the configuration GUI) and non-interactive configuring.

c.

The syntax for the tag filter definition line in a project list file is: #define TAGS [ tag_filter ]

3.

For MSVC, the -projtag option of the PTB_FLAGS macro in the compilers\msvc{900|1000}_prj\static\build\UtilityProjects\configure._ file for non-interactive configuring, or the same option in the configure_dialog._ file for interactive configuring.

If a significant tag filter (i.e. something besides an asterisk or empty field) is found in one of the above places, then that tag filter will be supplied to the configuration process. Otherwise, there will be no filtering of the projects.

Starting the configuration GUI

To launch the configuration GUI:

• From the command-line: ./configure --with-configure-dialog

• From the MSVS IDE: build the -CONFIGURE-DIALOG- project

• From the Xcode IDE: build the CONFIGURE-DIALOG target

The configuration GUI has a "Wizard" style design – selections are made in a sequence of steps, followed by clicking the Next button. After each step additional tabs may be enabled, depending on the specific data. It opens with initial values set by the invoking program (the configure script for command-line invocation or the project_tree_builder program for IDE's).

Configuration tab

The Configuration tab looks like:

The Configuration tab allows you to:

• Choose between static and dynamically-linked libraries.

• Specify the subset of the Toolkit that you want to build, using either a path for a subtree (e.g. src\) or a project list file (*.lst) for specific projects. Clicking on the "..." button opens a file selection dialog, which can be used to navigate to the desired subtree or to select a project list file.

• Specify one or more project tags (which will restrict the scope of the build to the specified projects). Clicking on the "..." button simply displays the valid choices for project tags (it isn't used for selecting tags). More than one project tag can be combined in a Boolean expression, for example:
  (code || web) && !test

• Load a configuration from a file. This requires having previously saved a configuration, from the Done tab. If you load a configuration from a file, the file path is shown in the "Originally loaded from" text field and the Reset button becomes enabled. Clicking the Reset button resets all configuration settings to the values that were used to invoke the configuration GUI.

Advanced tab

The Advanced tab looks like:

The Advanced tab allows you to:

• View the current version of the IDE (currently only applicable to Windows / Microsoft Visual Studio).

• View the current architecture (currently only applicable to Windows / Microsoft Visual Studio).

• Specify the name of a solution file to generate. You can use this to create different solution files for different configurations.

• Specify where to look for missing libraries. This can be used to change the build – for example, from cxx.current to cxx.potluck.

In addition, by clicking "more" you will see:

These additional options generally don't need to be changed, but they allow you to:

• Exclude the "Build PTB" step from the configure process. This should be selected if the PTB (project tree builder) source is not available. Even if the PTB source is available, it usually makes sense to exclude building the PTB because building it will take longer and generally won't have a benefit.

• Prevent whole-tree scanning for missing project dependencies. A project dependency may be missing if, for example, import_project was used and the configuration was changed to something other than simply Debug or Release (e.g. DebugMT).

• Use external libraries instead of missing in-tree ones.

• Select a different project tree builder. In most cases this won't be needed, but it could be useful for tasks such as debugging the build system.

• Select a different location to use as the root of the source tree.

Third party libraries tab

The Third party libraries tab looks like:

The Third party libraries tab allows you to:

• Select a different location for third-party libraries.

• Select a different location for the NCBI C Toolkit.

• Add VTune configurations. If selected, new VTune configurations will be added to the list of available configurations – for example, VTune_DebugDLL.

Projects tab

The Projects tab looks like:

The Projects tab allows you to select exactly which applications and libraries will be built. If an item is not selected, but at least one selected item depends on it, then it will also be built. This provides a convenient way for developers to simply pick the top-level items to build.

The "-all" and "+all" buttons uncheck or check all the items in a column.

The Tags column allows you to quickly select all items having the selected project tag(s). Also, selecting items in the other columns will update the selection status of the tags column.

Done tab

The Done tab looks like:

The Done tab:

• Reports whether the project was generated successfully.

• Shows the path for the generated solution file.

• Gives the option to save the configuration parameters. Once saved, the same parameters can be loaded again from the Configuration tab.

• Gives the option to start over and create a new set of configuration parameters.

• Gives the option to close the tool, via the Finish button. Closing the tool will return you to the configuration process, which will continue based on the parameters set in the configuration GUI.

Configuration Script configure

Different build setups compile C++ (and even C!) code differently; they may vary in the OS standard and 3^rd-party libraries and header files, completeness of the C++ implementation, and in compiler bugs. There are also different versions of make and other tools and different file naming conventions on different platforms.

Thus, configuration is needed to use the platform- and compiler-specific features. For this purpose, we are using a script produced by the GNU autoconf utility to automatically generate the build-specific header file ncbiconf.h and makefiles that would work for the given platform.

The user performs configuration by merely running platform-independent (sh, bash) shell script configure (which we pre-generate in-house from the template configure.ac using autoconf).

During the configuration process, many compiler features are tested, and the results of this testing are recorded in the configuration header ncbiconf.h by the means of C preprocessor variables. For example, the preprocessor variable NO_INCLASS_TMPL indicates whether the compiler supports template class methods. Also contained in the ncbiconf.h file are preprocessor variables used to define sized integer and BigScalar types.

The configure script will create a build tree, a hierarchy of directories where object modules, libraries, and executables are to be built. It will also configure all *.in template files located in the NCBI C++ source tree (src/) and deploy the resultant configured files in the relevant places of the build tree. This way, all platform- and compiler-specific tools and flags will be "frozen" inside the configured makefiles in the build tree. The ncbiconf.h (described above, also configured for the given compiler) will be put to the inc/ sub-directory of the resultant build tree.

You can create as many build trees as needed. All build trees refer to the same source tree, but contain their own platform/compiler-specific ncbiconf.h header and/or different set of compilation/linking flags and tools ("frozen" in the makefiles, particularly in Makefile.mk). This allows building libraries and executables using different compilers and/or flags, yet from the same source, and in a uniform way.

A configuration tool with a Java-based GUI is also available and can be launched from the command-line:

./configure --with-configure-dialog

Additional parameters can also be passed to configure, just as without the configuration GUI.

For more information on using the configuration GUI, see the general section on configuring.

Structure of the Build Tree Produced by configure

Each configuration process results in a new build tree. The top-level directories in the tree are:

inc/ - contains the ncbiconf.h configuration header generated by the configure script.

build/ - contains a hierarchy of directories that correspond to those in the src/ (in NCBI C++ original sources). These directories will contain makefiles (Makefile.*) generated by the configure script from the makefile templates (Makefile.*.in) of the corresponding project located in the source tree. The resultant scripts and makefiles will keep references to the original NCBI C++ source directories. There is a "very special" file, Makefile.mk, that contains all configured tools, flags, and local paths. This file is usually included by other makefiles. All build results (object modules, libraries, and executables, as well as any auxiliary files and directories created during the build) will go exclusively into the build tree and not to the original NCBI C++ source directories. This allows for several build trees to use the same source code while compiling and linking with different flags and/or compilers.

lib/ - contains the libraries built by the build/-located projects.

bin/ - contains the executables built by the build/-located projects.

status/ - contains:

• config.cache, a cache file;

• config.log, a log file;

• config.status, a secondary configuration script produced by configure;

• *.enabled files, with package and feature availability; and

• .*.dep files, with timestamps of the built Toolkit libraries.

Options for Fine-Tuning the configure Script

The configure script is highly customizable. The following sections describe some of the configuration options:

• Getting a Synopsis of Available Configuration Options

• Debug vs. Release Configuration

• Multi-Thread Safe Compilation and Linking with MT Libraries

• Building Shared Libraries (DLLs)

• Finer-grained Control of Projects: --with-projects

• Building in the 64-bit mode

• Localization for the System and Third-Party Packages

• Naming the Build Tree

• Hard-Coding Run-Time DLL Path into Executables and DLLs

• Automatic Generation of Dependencies (for GNU make Only)

• After-Configure User Callback Script

• Tools and Flags

• Prohibiting the Use of Some of the System and Third-party Packages

• Optional Projects

• Miscellaneous: --without-exe, --without-execopy, --with-lib-rebuilds(=ask)

corelib$
util
serial
-serial/test
test update-only

#define TAGS [ tag_filter ]

Localization for the System and Third-Party Packages

There is some configuration info that usually cannot be guessed or detected automatically, and thus in most cases it must be specified "manually" for the given local host's working environment. This is done by setting the localization environment variables (see Table 2) in addition to the "generic" ones (CC, CXX, CPP, AR, RANLIB, STRIP, CFLAGS, CXXFLAGS, CPPFLAGS, LDFLAGS, LIBS).

Table

Table 2. User-defined localization variables

On the basis of Table 2, configure will derive the variables shown in Table 3 to use in the generated makefiles.

Table

Table 3. Derived localization variables for makefiles

Note: The file src/build-system/config.site may also be edited to simplify localization of third party libraries, especially for users outside NCBI.

env LD_LIBRARY_PATH="/home/USERNAME/c++/WorkShop6-ReleaseDLL/lib" \

/home/USERNAME/c++/WorkShop6-ReleaseDLL/bin/coretest

configure --with-extra-action="echo foobar {}"

echo foobar /home/user/c++/GCC-Debug

Tools and Flags

There is a predefined set of tools and flags used in the build process. The user can customize these tools and flags by setting the environment variables shown in Table 1 for the configure script. For example, if you intend to debug the Toolkit with Insure++, you should run configure with CC and CXX set to insure.

Table

Table 1. Environment variables that affect the build process

Later, these tools and flags will be engaged in the makefile build rules, such as:

• To compile C sources: $(CC) -c $(CFLAGS) $(CPPFLAGS)....

• To compile C++ sources: $(CXX) -c $(CXXFLAGS) $(CPPFLAGS)....

• To compose a library: $(AR) libXXX.a xxx1.o xxx2.o xxx3.o .....$(RANLIB) libXXX.a

• To link an executable: $(LINK) $(LDFLAGS) ..... $(LIBS)

For more information on these and other variables, see the GNU autoconf documentation. The specified tools and flags will then be "frozen" inside the makefiles of build tree produced by this configure run.

Quick Reconfiguration

Sometimes, you change or add configurables (*.in files, such as Makefile.in meta-makefiles) in the source tree.

For the build tree to pick up these changes, go to the appropriate build directory and run the script reconfigure.sh. It will automatically use just the same command-line arguments that you used for the original configuration of that build tree.

Run reconfigure.sh with argument:

update - if you did not add or remove any configurables in the source tree but only modified some of them.

reconf - if you changed, added, and/or removed any configurables in the source tree.

recheck - if you also suspect that your working environment (compiler features, accessibility of third-party packages, etc.) might have changed since your last (re)configuration of the build tree and, therefore, you do not want to use the cached check results obtained during the last (re)configuration.

without arguments - printout of script usage info.

Example:

cd /home/foobar/c++/GCC-Debug/build 

./reconfigure.sh reconf

Naturally, update is the fastest of these methods, reconf is slower, and recheck (which is an exact equivalent of re-running the configure script with the same command-line arguments as were provided during the original configuration) is the slowest.

General Principles for Building with UNIX

Use this key for the examples in the “Building with UNIX” sections:

The import_project script builds a single project in the working directory while referencing the rest of a pre-built Toolkit for all other Toolkit components. For example, to build only the app/id2_fetch application and have the rest of the pre-built Toolkit available, use these commands:

mkdir $YOUR_WORK_DIR

cd $YOUR_WORK_DIR

import_project app/id2_fetch

cd trunk/c++/src/app/id2_fetch

make

The update_projects script builds a single project and all the components it depends on in the working directory, and does not reference or build any other Toolkit components. For example, to build only the corelib project, use these commands:

mkdir $YOUR_WORK_DIR

cd $YOUR_WORK_DIR

update_projects corelib .

The update_projects script will automatically retrieve updated source code and then prompt you for configuring, compiling, building tests, and running tests.

To run a test suite after building, use this additional command:

make check_r

Building Only Core Libraries and Applications with UNIX

cd $YOUR_WORK_DIR

./configure –without-gui –without-internal $YOUR_CONFIG_OPTIONS

cd GCC401-Debug/build 

make all_r

Building GUI Libraries and Applications with UNIX

cd $YOUR_WORK_DIR

./configure $YOUR_CONFIG_OPTIONS --with-flat-makefile

cd GCC401-Debug/build

make -f Makefile.flat gui/

Building the Genome Workbench with UNIX

cd $YOUR_WORK_DIR

./configure $YOUR_CONFIG_OPTIONS --with-flat-makefile --with-gbench

cd GCC401-Debug/build

make -f Makefile.flat gui/app/

(cd gui/app/gbench_install && make)

Building the Entire Toolkit with UNIX

cd $YOUR_WORK_DIR

./configure $YOUR_CONFIG_OPTIONS 

cd GCC401-Debug/build

make all_r

Modify an Existing Toolkit Application with UNIX

If you want to modify, for example, gi2taxid, use these commands:

cd $YOUR_WORK_DIR

import_project app/gi2taxid

You will be prompted to select a desired stability and configuration and then the script will create the include and src trees necessary to work on the chosen application. It will also create all the necessary makefiles to build the application. The makefiles will be configured to use the latest nightly build of the chosen stability and configuration to resolve all dependencies outside the chosen application.

You can now make the desired edits and then rebuild:

cd trunk/c++/src/app/gi2taxid

# edit the desired file(s)

make all_r

Modify an Existing Toolkit Library with UNIX

If you want to modify, for example, html, use these commands:

cd $YOUR_WORK_DIR

import_project html

You will be prompted to select a desired stability and configuration and then the script will create the include and src trees necessary to work on the chosen library. It will also create all the necessary makefiles to build the library. The makefiles will be configured to use the latest nightly build of the chosen stability and configuration to resolve all dependencies outside the chosen library.

You can now make the desired edits and then rebuild:

cd trunk/c++/src/html

# edit the desired file(s)

make all_r

Site-Specific Build Tree Configuration

File project_tree_builder.ini (see Table 4) describes build and source tree configurations, contains information about the location of 3rd-party libraries and applications, and includes information used to resolve macro definitions found in the UNIX -style makefile templates.

Table

Table 4. Project Tree Builder INI file (Local Site)

Toolkit project makefiles can list (in a pseudo-macro entry called 'REQUIRES') a set of requirements that must be met in order for the project to be built. For example, a project can be built only on UNIX, or only in multi-thread mode, or if a specific external library is available. Depending on which of the requirements are met, the Toolkit configurator may exclude some projects in some (or all) build configurations or define preprocessor and/or makefile macros.

Some of the Toolkit projects can be built differently depending on the availability of non-Toolkit components. For them, there is a list of macros - defined in 'Defines' entry - that define conditional compilation. To establish a link between such a macro and a specific component, the configuration file also has sections with the names of the macro. For each build configuration, project tree builder creates a header file (see 'DefinesPath' entry) and defines these macros there depending on the availability of corresponding components.

Many of the requirements define dependency on components that are 3rd-party packages, such as BerkeleyDB. For each one of these there is a special section (e.g. [BerkeleyDB]) in project_tree_builder.ini that describes the path(s) to the include and library directories of the package, as well as the preprocessor definitions to compile with and the libraries to link against. The Toolkit configurator checks if the package's directories and libraries do exist, and uses this information when generating appropriate MSVS projects.

There are a few indispensable external components that have analogs in the Toolkit. If the external component is not found, the analog in the Toolkit is used. The 'LibChoices' entry identifies such pairs, and 'LibChoiceIncludes' provides additional include paths to the builtin headers.

NOTE: There are some requirements which, when building for MS Visual Studio, are always or never met. These requirements are listed in 'ProvidedRequests', 'StandardFeatures', or 'NotProvidedRequests' of the 'Configure' section.

Fine-Tuning with MSVC Project Files

While default MSVS project settings are defined in the Makefile.mk.in.msvc file, each project can require additional MSVC-specific fine-tuning, such as compiler or linker options, additional source code, etc. These tune-ups can be specified in Makefile.<project_name>.[ lib|app ].msvc file located in the project source directory. All entries in such *.msvc file are optional.

Any section name can have one or several optional suffixes, so it can take the following forms:

• SectionName

• SectionName.CompilerVersion

• SectionName.Platform

• SectionName.[static|dll]

• SectionName.[debug|release]

• SectionName.CompilerVersion.[debug|release]

• SectionName.[static|dll].[debug|release]

• SectionName.[debug|release].ConfigurationName

• SectionName.[static|dll].[debug|release].ConfigurationName

Settings in sections with more detailed names (ones that appear later on this list) override ones in sections with less detailed names (ones that appear earlier).

The following topics discuss further fine-tuning with MSVC project files:

• Excluding a Project From the Build

• Adding Files to a Project

• Excluding Files From a Project

• Adjusting Build Tools Settings

• Specifying Custom Build Rules

DLL Configuration

The Toolkit UNIX-style makefile templates give a choice of building the library as dynamic or static (or both). However, it is often convenient to assemble a "bigger" DLL made of the sources of several static libraries.

In the Toolkit, such compound DLLs are described using a set of special makefiles in the src/dll subdirectory. Each such file – Makefile.*.dll – contains the following entries:

Fine-Tuning with Environment Variables

It is possible to fine-tune the configuration process by using the following environment variables:

• PREBUILT_PTB_EXE

• PTB_PROJECT

When the PREBUILT_PTB_EXE environment variable defines an existing file (e.g. project_tree_builder.exe), this EXE is used. Otherwise, the configuration process builds project_tree_builder using existing sources, and then uses this EXE. At NCBI, even when PREBUILT_PTB_EXE is not defined, the toolkit still tries to use an external project_tree_builder – to speed up the configuration. Normally, this is the most recent successfully built one. To disable such behavior, this variable should be defined and have the value bootstrap:

PREBUILT_PTB_EXE=bootstrap

The PTB_PROJECT environment variable can be used to redefine the default project list. For example, it can be defined as follows:

PTB_PROJECT=scripts\projects\datatool\project.lst

Building a Custom Solution

This section deals with building a custom solution within the C++ Toolkit source tree. To build a custom solution outside the source tree, please see the section on using the new_project script.

There is a template solution, compilers\msvc{900|1000}_prj\user\build\ncbi_user.sln, that should help you build a customized solution. The project list for this solution is in scripts\projects\ncbi_user.lst

Note: Do not use this solution directly. Instead, make a new solution based on the template:

1.

Make copies of the compilers\msvc{900|1000}_prj\user\ subtree and the scripts\projects\ncbi_user.lst file (keep the copies in the same folders as the originals).

2.

Rename the subtree, solution file, and project list file appropriately, for example to compilers\msvc{900|1000}_prj\project_name\, compilers\msvc{900|1000}_prj\project_name\build\project_name.sln, and scripts\projects\project_name.lst.

3.

In the folder compilers\msvc{900|1000}_prj\project_name\build\UtilityProjects\, use a text editor to edit _CONFIGURE_.vcproj, and _CONFIGURE_DIALOG_.vcproj. Change all instances of "ncbi_user" to "project_name".

4.

In the same folder, also edit configure._, and configure_dialog._:

a.

Change all instances of "ncbi_user" to "project_name".

b.

By default, the solution uses static runtime libraries. If you want to use DLL's, also add the '-dll' option to the 'set PTB_FLAGS=' line.

c.

By default, the solution uses a project list file. If you don't want to use a project list file (e.g. if you want to use a project tag filter instead), also change the 'set PTB_PROJECT_REQ=' line to the appropriate subtree, e.g. 'set PTB_PROJECT_REQ=src\cgi\'.

d.

If you want to use a project tag filter, add the '-projtag' option to the 'set PTB_FLAGS=' line, e.g. 'set PTB_FLAGS=-projtag "core && !test"'. See the section on reducing build scope for more information on using project tags.

5.

If your new project will use a project list file, edit scripts\projects\project_name.lst to identify the required project folders.

6.

Your custom solution can now be built. Open the solution file compilers\msvc{900|1000}_prj\project_name\build\project_name.sln, configure, and build.

Note that the project directory, msvc{900|1000}_prj, may be different for your version of Visual C++.

Building External Libraries (Optional)

Some of the NCBI C++ Toolkit projects make use of the NCBI C Toolkit (not to be confused with the NCBI C++ Toolkit) and/or freely distributed 3rd-party packages (such as BerkeleyDB, LibZ, FLTK, etc.).

At NCBI, these libraries are already installed, and their locations are hard coded in the C++ Toolkit configuration files. If you are outside of NCBI, you may need to build and install these libraries before building the C++ Toolkit.

Alternatively, the source code for the NCBI C Toolkit and the 3rd-party packages can be downloaded from the NCBI FTP site and built - ideally, in all available configurations.

If you do not have the external libraries already installed, you can download, build, and install the NCBI C Toolkit and the freely distributed 3rd-party packages. The source code for the NCBI C Toolkit and the freely distributed 3rd-party packages can be downloaded from the NCBI FTP site and built in all available configurations. Refer to the documentation on the specific packages you wish to install for more information.

The Build Results

The built Toolkit applications and libraries will be put, respectively, to:

compilers\msvc{900|1000}_prj\{static|dll}\bin\<config_name>

compilers\msvc{900|1000}_prj\{static|dll}\lib\<config_name>

Note that the project directory, msvc{900|1000}_prj, may be different for your version of Visual C++.

Start a New Project That Uses the Toolkit

To use an already built C++ Toolkit (with all its build settings and configured paths), use the new_project script to create a new project:

new_project <name> <type> [builddir] [flags]

where:

For example, if the Toolkit is built in the U:\cxx folder, then this command:

new_project test app U:\cxx\compilers\msvc{900|1000}_prj

• creates a new local build tree;

• puts the project source files into the \src\name folder;

• puts the header files into name\include\name;

• puts the Visual Studio project file into name\compilers\msvc{900|1000}_prj\static\build\name; and

• puts the solution file into name\compilers\msvc{900|1000}_prj\static\build.

To add new source files or libraries to the project, edit name\src\name\Makefile.name.app makefile template, then rebuild the -CONFIGURE- project of the solution.

Start a New Project in the Toolkit with Visual C++

Follow the regular UNIX-style guidelines for adding a new project to the Toolkit.

Then, build the -CONFIGURE- project and reload the solution.

To start a new project that will become part of the Toolkit, create the makefile template first. For applications it must be named Makefile.< project_name>.app; for libraries - Makefile.<project_name>.lib. If it is a new folder in the source tree, you will also need to create Makefile.in file in the new folder, to specify to the configuration system what should be built in the new folder. Also, the new folder must be listed in the SUB_PROJ section of the parent folder's Makefile.in. Finally, make sure your new project folder is listed in the appropriate project list file in scripts\projects\*.lst. It can be either a subdirectory of an already listed directory, or a new entry in the list.

Modify an Existing Project in the Toolkit with Visual C++

At NCBI, the import_project script can be used to work on just a few projects and avoid retrieving and building the whole source tree. For example, to work on the 'corelib' subtree, run:

import_project corelib

The script will create the build tree, copy (or extract from the repository) relevant files, and create Visual Studio project files and a solution which reference pre-built Toolkit libraries installed elsewhere.

Site-Specific Build Tree Configuration

The build tree configuration can be tailored to your site by modifying the file src/build-system/project_tree_builder.ini (see Table 4). For example, you may need to change the location of 3^rd-party libraries to match your systems. Or you may need to specify conditions under which a certain project is excluded from the build.

project_tree_builder.ini describes build and source tree configurations; contains information about the location of 3rd-party libraries and applications; and includes information used to resolve macro definitions found in the UNIX-style makefile templates.

Toolkit project makefiles can list a set of requirements that must be met in order for the project to be built. These requirements are specified in the pseudo-macro REQUIRES. For example, a project can be built only on UNIX, or only in multi-thread mode, or only if a specific external library is available. Depending on which of the requirements are met, the Toolkit configuration tool may exclude some projects in some (or all) build configurations, preprocessor defines, and/or makefile macros.

Some of the Toolkit projects can be built differently depending on the availability of non-Toolkit components. For those projects, there is a list of macros - defined in the 'Defines' entry - that define conditional compilation. Each of these macros also has its own section in project_tree_builder.ini that links the macro to a specific component. Using the 'Defines' entry and the associated macro sections, a project can be linked to a list of components. For each build configuration, project tree builder creates a header file (see 'DefinesPath' entry) and defines these macros there depending on the availability of the corresponding components.

Many of the requirements define dependencies on 3rd-party packages, such as BerkeleyDB. For each one of these there is a special section (e.g. [BerkeleyDB]) in project_tree_builder.ini that describes the path(s) to the include and library directories of the package, as well as the preprocessor definitions to compile with and the libraries to link against. The Toolkit configurator checks if the package's directories and libraries do exist, and uses this information when generating appropriate projects.

There are a few indispensable external components that have analogs in the Toolkit. If external libraries for these components are not available then the internal analog can be used. The 'LibChoices' entry identifies such pairs, and 'LibChoiceIncludes' provides additional include paths to the built-in headers.

NOTE: There may be some requirements which are always or never met. These requirements are listed in the 'ProvidedRequests', 'StandardFeatures', or 'NotProvidedRequests' entries of the 'Configure' section.

Dynamic Libraries Configuration

The Toolkit UNIX-style makefile templates give a choice of building the library as dynamic or static (or both). However, it is often convenient to assemble "bigger" dynamic libraries made of the sources of several static libraries.

In the Toolkit, such compound libraries are described using a set of special makefiles in src/dll subdirectory. Each such file – Makefile.*.dll – contains the following entries:

• DLL – the name of the compound dynamic library;

• HOSTED_LIBS – the names of the static libraries to be assembled into the compound dynamic library;

• DEPENDENCIES – dependencies on other static or dynamic libraries; and

• CPPFLAGS – additional compiler flags, specific for this dynamic library.

Fine-Tuning Xcode Target Build Settings

While default build settings are defined in the Makefile.mk.in.xcode file, it is possible to redefine some of them in special tune-up files – Makefile.<project_name>.{lib|app}.xcode – located in the project source directory. All entries in the tune-up files are optional.

Section names in the tune-up files can have one or more optional suffixes and can take any of the following forms:

• SectionName

• SectionName.CompilerVersion

• SectionName.Platform

• SectionName.[static|dll]

• SectionName.[debug|release]

• SectionName.CompilerVersion.[debug|release]

• SectionName.[static|dll].[debug|release]

• SectionName.[debug|release].ConfigurationName

• SectionName.[static|dll].[debug|release].ConfigurationName

Here, 'static' or 'dll' means the type of runtime libraries that a particular build uses; 'debug' or 'release' means the type of the build configuration; and 'ConfigurationName' means the name of the build configuration, for example DebugDLL or ReleaseMT.

Settings in sections with more detailed names (ones that appear later on this list) override ones in sections with less detailed names (ones that appear earlier).

Adding Files to Target

This information should be entered in the 'AddToProject' section. The section can have the following entries:

• [AddToProject]

• SourceFiles=

• IncludeDirs=

• LIB=

• HeadersInInclude=

• HeadersInSrc=

The 'SourceFiles' entry lists additional (usually OSX specific) source files for the project. Source file entries should not include file name extensions. The 'IncludeDirs' entry lists additional include directories, and the 'LIB' entry lists additional libraries for the project.

By default, all header files found in the project's include and source directories are added to the Xcode target. If that's not exactly what you need though, then the default set of headers to be added to the target can be altered using the 'HeadersInInclude' and 'HeadersInSrc' entries. Unlike the 'SourceFiles' entry, file names in these entries should include their extension. Use an exclamation mark to exclude files that would otherwise be included. Wildcards are allowed. For example, the following entry

HeadersInInclude = *.h file1.hpp !file2.h

means "add all files with the .h extension, add file1.hpp, and do not add file2.h".

NOTE: A single exclamation mark with no file name means "do not add any header files".

Specifying a Custom Build Script

For a particular target, it is possible to specify a custom build script which will run in addition to the standard build operation. This could be used, for example, to copy application resource files once the build is completed. Xcode will automatically incorporate the custom script into the standard build process.

In the appropriate Makefile.*.xcode customization file, define a section called ‘CustomScript’. It has one mandatory entry – Script, and three optional ones:

• Input – a list of input files;

• Output – a list of output files; and

• Shell – which shell to use (the default is ‘/bin/sh’).

Build 3^rd-Party Libraries (optional)

Some of the NCBI C++ Toolkit projects make use of the NCBI C Toolkit (not to be confused with the NCBI C++ Toolkit) and/or freely distributed 3rd-party packages (such as BerkeleyDB, LibZ, FLTK, etc.).

At NCBI, these libraries are already installed, and their locations are hard coded in the C++ Toolkit configuration files. If you are outside of NCBI, you may need to build and install these libraries before building the C++ Toolkit.

If you do not have the external libraries already installed, you can download, build, and install the NCBI C Toolkit and the freely distributed 3rd-party packages. The source code for the NCBI C Toolkit and the freely distributed 3rd-party packages can be downloaded from the NCBI FTP site and built in all available configurations. Refer to the documentation on the specific packages you wish to install for more information.

Building from a Command-Line with Xcode 3.0 or Later

From the command-line, you can either build exactly as under UNIX, or you can build for Xcode.

To configure for Xcode, first run configure in the Xcode project directory (run configure --help to see available options):

cd compilers/xcode30_prj
./configure

Once you have configured for Xcode, you can either open and work in the Xcode IDE or build from the command-line.

To build from the command-line, run make all_r. Optionally build the testsuite with make check_r.

make all_r
make check_r

The Build Results

Applications and libraries produced by the build will be put, respectively, into:

• compilers/xcode30_prj/{static|dll}/bin/<ConfigurationName>

• compilers/xcode30_prj/{static|dll}/lib/<ConfigurationName>