EXAMPLE (DESCRIPTION)

This section demonstrates the possibilities of makefiles customization on an advanced example. Similar to the previous example, this consists of two subprojects: Client and Server.

In addition, the project includes a server-stub subproject (ServerDummy) that implements the communication protocol exactly as in the server, but has a stub instead of functional behaviour.

• Client consists of a main module Client.cpp, and uses functions from the TEClient.cpp module in the TCPEngine common directory.
  
  
• Server consists of a main module Server.cpp, communications protocol module Protocol.cpp, and operations module Operations.cpp. Similar to Client, Server uses functions from the TEServer.cpp module in the common directory TCPEngine.
  
  
• Server-stub should as closely as possible use files from the Server subroject, except for Server.cpp and Operations.cpp

All subprojects have maintenance unit tests.

CREATION OF BASE PROJECT MAKEFILES

The project directory tree is shown in the figure below:

In order to create makefiles as shown in the figure, commands should be run as described in the previous section:

$ me-create -conf
$ me-create -project
$ me-create -subproj src/Server
$ me-create -subproj src/Server/ServerDummy
$ me-create -subproj src/Client

These commands interactively ask which makefile template should be used. In all cases the console application template should be used, i.e. case # 1 should be chosen.

Next, it is necessary to specify a list of base project subprojects in the project makefile. Since ServerDummy is intended for debug stage only, it isn't included in the list of base subprojects:

base_subprojs_dirs := src/Client src/Server

SETUP OF CLIENT SUBPROJECT

Configuration of Client subprojects is concluded by inclusion of external source directory src/TCPEngine to the build:

Client_source_dirs += src/Client src/TCPEngine

In this way unit tests for included directories will be included into the test build automatically. If a file with a main() function exists among unit tests, then it should be excluded from the tests build:

Client_exclude_files += src/TCPEngine/Tests/TestMain.cpp

Unit test libraries, such as CppUnit and WppUnit, are compatible with Make-Effect in this regard and will not break tests build.

SETUP OF SERVER SUBPROJECT

Configuration of Server subprojects (similar to Client subprojects) is completed by inclusion of external source directory src/TCPEngine, but the directory should be included without unit tests support. To complete this part of the configuration the subproject configuration file should be modified as follows:

Server_notests_source_dirs += src/TCPEngine

The exact way in which external directories are included is left up to the developer.

SETUP OF SERVERDUMMY SUBPROJECT

The configuration of the ServerDummy subproject is also relies on the setup of external directories:

ServerDummy_source_dirs += src/Server/DummyServer src/Server
ServerDummy_notests_source_dirs += src/TCPEngine
ServerDummy_exclude_files += src/Server/Server.cpp src/Server/Operations.cpp

The tag _exclude_files prevents inclusion of unwanted files from external directories.

CREATION OF CLIENT DEBUG SESSION

Shown below is the configuration of a session for debugging of the Client subproject, in the case where the subproject Server has not been implemented yet. In order to maintain project settings, a special debug session should be created:

$ me-create -debug Debug_client

Before performing a build it is necessary to check the parameter session in the .me-session file:

session=Debug_client

Subproject Server should be replaced by DummyServer within the debug session, as shown below:

session_subprojs_dirs = src/Server/ServerDummy
exclude_subproj_dirs = src/Server

SETUP OF RELEASE BUILD SESSION

In this section a release session will be configured in such a way that a release build process will not require Make-Effect to be installed. This is suitable when a software product is delivered with the source code.

A release session is created automatically upon project creation. However, if no release session exists it can be created by issuing a command from the root project directory as follows:

me-create -release <session name>

Similar to a debug session, the file Makefile.in will be created in the directory named with the session name.

In some cases, it is more appropriate to save a build session configuration file in the root project directory. Make-Effect allows the movement of a session configuration file as long as a specific naming convention is followed: in the project root directory these files have to be named similar to mk-<session name>.in:

$ mv Release/Makefile.in mk-Release.in

By default, a release build session uses partial compilation that relies on the output of the me-autodep utility from the Make-Effect package. In order to disable partial compilation it is necessary to change settings in the file mk-Release.in:

depend = no
default: clean build

If the release session name is not Release, then the default session name parameter should be adjusted in the project makefile appropriately. The value of the session parameter should be specified according to the name used.

If all the necessary steps have been performed, then the make command will build the project.

PREPARATION OF INSTALLATION SCRIPT

Make-Effect provides a template for the creation of tar.gz installation packages, that are extracted by the QNX utility command install -u.

In order to enable command make pack (make it able to create installation package) the following parameters in the project makefile should be specified: project - project name, version - project version, installation_dir - installation directory.

The packaging procedure should be implemented in the pack.sh file. For the current example the packaging procedure can be specified as follows:

pax -ws ,$session/bin,$installation_directory, -f $output_tar_file $session/bin

If the packaging procedure has been specified correctly then the following commands will be available: make pack and make install (installation of the project).

CONVERSION OF TCPENGINE TO A STATIC LIBRARY

Converting TCPEngine to a static library will solve a problem with the unit test of the src/TCPEngine directory that causes it to only function with unit tests of the Client subproject only.

In order to create a static library subproject, it is necessary to run the following command from the root directory of the project:

$ me-create -subproj src/TCPEngine

and choose case #3 - static library template.

All changes in parameters <project name>_source_dirs, <project name>_notests_source_dirs and <project name>_exclude_files should be set to initial values:

file ./src/Client/Makefile.in :
Client_source_dirs += src/Client
Client_exclude_files +=

file ./src/Server/DummyServer/Makefile.in :
ServerDummy_notests_source_dirs +=

file ./src/Server/Makefile.in :
Server_notests_source_dirs +=

But parameters <project name>_ldflags should be specified as follows:

file ./src/Client/Makefile.in :
Client_ldflags += -L $(session)/bin -l TCPEngine.lib

file ./src/Server/DummyServer/Makefile.in :
Server_ldflags += -L $(session)/bin -l TCPEngine.lib

file ./src/Server/Makefile.in :
ServerDummy_ldflags += -L $(session)/bin -l TCPEngine.lib

In order to automatically rebuild subprojects when the library changes, the following strings should be added to the subproject makefiles of Client and Server:

file ./src/Client/Makefile.in :
$(Client_out_dir)/Client: $(session)/bin/TCPEngine.lib

file ./src/Server/Makefile.in :
$(Server_out_dir)/Server: $(session)/bin/TCPEngine.lib

The new subproject should be included in the list of base subprojects of the project makefile:

base_subprojs_dirs := TCPEngine Client Server

Since building is performed in the same order as projects are defined in the list, the library should be placed at the head of the list.