Setting up a new project is trivial if you have perl installed. perl is pretty much standard for all systems except Windows. For Windows, it can be installed by obtaining either the ActiveState ActivePerl distribution, or installing cygwin and including perl. The latter is recommended, since then you get all the standard commands like ls instead of DIR, and the mkdir command will actually work the way it's supposed to. That's just the tip of the iceberg.
To create a new project, open a shell and cd to "UT/bld/project templates". From there, simply execute the following:
perl CreateProject.pl
You will be prompted to select a project type, name, and output name. The name can include spaces, as it is the friendly name. The output name should not include any whitespace. By way of analogy, for the UT GUI library, the name is "UT GUI Library" while the output name is UTgui. A directory with the same name as the output name will be created in the same directory as the UT folder. It will contain the following:
bld Linux Makefile MacOS PROJECT.xcodeproj Windows PROJECT.sln PROJECT.vcproj src ProjectMain.cpp resource Project.rc Project.rc.h
The resources which are created are in the format used by Visual Studio's resource compiler. They do not, however, adhere to Microsoft's model for how resources are structured, and include a significant amount of organizational and meta information in the form of comments. That information is required by the resource compiler/converter for building on other platforms, and by the UT resource editor. Consequently, the resources should NEVER be edited using the Visual Studio resource editor. Doing so will break the cross-platform nature of the resources, and the Resource_t class will not be able to access any resources which do not adhere to its method of resource management. That method is to facilitate resources being available on all target platforms.
Using Windows Visual Studio projects is very intuitive. There really isn't much to be documented other than the above warning not to edit resources with the Visual Studio resource editor. In any case, that editor is only available in the "professional" (not free) versions. As stated in the Windows Environment Setup page, the project is in the format for Visual C++ 2005 Express Edition, which is free.
The UT library contains a generic makefile engine which makes it extremely easy to set up a project. It takes care of the complexity of managing compile and link options, whether the UT library and UT-based libraries are being used as static or shared libraries, C/C++ source build rules, output directory structure, dependencies, and whether the target of your own build is itself an executable or library.
By default, the makefile will build the debug, shared libraries version of the target. That can be done by simply typing "make" at the command line. In the shared libraries form, the UT library and all UT-based libraries will be used in shared form. In the static libraries form, they will be used as static libraries when linking an executable. To specify a different form of build, make is invoked as follows:
make BLD=TYPE
for example:
make BLD=rel_lib
The types of builds which can be specified by TYPE are:
make BLD=dbg_so - builds debug, shared libs make BLD=dbg_lib - builds debug, static libs make BLD=rel_so - builds release, shared libs make BLD=rel_lib - builds release, static libs make BLD=rel_so_profile - builds release, shared libs with profiling make BLD=rel_lib_profile - builds release, static libs with profiling
The main difference between debug and release builds is that debug builds include debug information, are not compiled with optimization, and have asserts enabled. Release builds do not include debug information, are compiled with optimization, and have asserts disabled. The release (asserts enabled) form is effectively a debug build, but does include optimization.
The build output will be created in a directory named bld_TYPE, for example bld_dbg_so.
A typical makefile for a command line application using this engine simply looks like:
override TARGET := PROJECT override TYPE := app
override PROJECT_TO_UT_PATH := ../../../UT
override INC_PATH := -I ../../src override INC_PATH +=
override C_OPTS := override CPP_STRICT_OPTS := override LINK_OPTS := override LINK_LIBS :=
override SRC_FILES := ../../src/PROJECTMain.cpp override SRC_FILES +=
override RESOURCE := ../../src/resource/PROJECT.rc
override UT_BASED_LINK_LIBS :=
include ../../../UT/bld/Linux/makefile_setup.inc include ../../../UT/bld/Linux/makefile_rules.inc
TARGET specifies the name of the application to be built. PROJECT should not include any whitespace.
TYPE specifies whether an application or library is being built (app or lib)
PROJECT_TO_UT_PATH specifies where to find the UT library's root directory.
INC_PATH specifies what paths should be searched for header files when compiling. The second, mostly empty INC_PATH line is merely a reminder to use += rather than := when adding more include search directories.
C_OPTS can be used to specify additional options to be passed to the compiler when building the C and C++ source files for the project.
CPP_STRICT_OPTS can be used to specify additional options to be passed to the compiler when building the C++ source files for the project.
LINK_OPTS can be used to specify additional options to be passed to the linker.
LINK_LIBS can be used to specify additional libraries to be passed to the linker. In some obscure conditions, .o files can also be added to LINK_LIBS. An example of this is the UT library requirement to include budemang.o when linking to demangle symbols when dumping the call stack in the augmented assert implementation.
SRC_FILES specifies the .cpp, .c, and .cxx files to be built. .c and .cpp files will be built by the UT makefile engine automatically. .cxx files are used to designate a special case where the UT makefile engine would be unable to build the file. The project makefile will include a rule to build the file. If that is the case, the rule must be set up to account for the fact that the .o file will end up at one of a number of paths depending on the type of build (static or shared libs, debug or release, etc). See CXX Special Cases for details. The second, mostly empty SRC_FILES line is merely a reminder to use += rather than := when adding more source files.
RESOURCE specifies what resource file is to be used. As a minimum, this contains version information. Whether they are needed or not, there really is no reason to leave out resources, since the UT library will, when generating an assert log, attempt to obtain its own version which is available through resources.
UT_BASED_LINK_LIBS specifies what additional libraries are to be included when linking the application or shared library. This may seem redundant with LINK_LIBS, but this flag actually allows the UT makefile engine to adjust the path of these libraries to account for the fact that the libraries will end up at one of a number of paths depending on the type of build (static or shared libs, debug or release, etc). Entries in this field should be formatted as ../../../LIB/bld/Linux/BLDDIR/LIB, where LIB is the name of the library, while BLDDIR should be used verbatim. BLDDIR will be replaced with an appropriate directory name by makefile_setup.inc. An appropriate .a or .so suffix will be appended by makefile_setup.inc.
Additional rules (typically .cxx build rules or recursive make invocation rules) can be added after the include of makefile_rules.inc, if needed.
A large number of variables will be set up or modified by makefile_setup.inc from their "simple" form specified in the makefile to the "final" form used by makefile_rules.inc. Inbetween the include directives for each, some manipulations are possible. The information is also useful to set up custom build rules after inclusion of makefile_rules.inc. To see all of the variables used by the UT makefile engine, specify DIAG=y at the command line.
Default rules are included to build any .c or .cpp file in the SRC_FILES list. Any files which must be compiled with compiler options other than those used by the default rules should be given the .cxx extension, which allows a specific build rule to be set up for that file. Because the target of such a rule is a .o file, which can exist at a variety of locations, the rule must use the $(OBJDIR) variable, which is set up by makefile_setup.inc. Such a rule should have a comment explaining why it is needed. An example is seen in makefile_UT:
#################################################################################################### # Rule for building special case files ####################################################################################################
# UTLinuxDebugSpecial.cxx: optimization destroys the assert recursion guard /src_UT/Linux/UTLinuxDebugSpecial.o: ../../src_UT/Linux/UTLinuxDebugSpecial.cxx ifeq (,y) @echo '--- make cpp $< to $@ in $(@D) ---' endif @mkdir -p $(@D) gcc -c -o $@ -MMD -MF $(subst .o,.d,$@) $< @sed -i -r -e 's/$(subst .,\.,$(notdir $@))/$(subst /,\/,$@)/' $(subst .o,.d,$@)
That rule looks just like the default C++ rule, but does not include CPP_STRICT_OPTS.
1.6.1