Project Management at Robot Control Software Ltd.

This chapter discusses all topics related to C/C++ project management at Robot Control Software Ltd. including revision control, how to compile and link libraries and applications, and how the source files are stored and backed up.

How to Compile and Link Projects

Platform independent make files are provided with all projects to generate the executable files and the libraries. The make files are generated from *.rpr files by the MakeMake utility. The make files are made platform independent by using macros at all platform dependent places.

Make Files

Make files are provided to build all applications and libraries. Every application and library has its own make file (*.mak) generated from the project (*.rpr) file and a 'makefile' is provided to build all applications.

For example in rMPL/smpl there are several programs like sLog.cpp, sDebug.cpp, sNewDel.cpp. All source files have its appropriate project files: sLog.rpr, sDebug.rpr, sNewDel.rpr. The MakeMake utility creates the following make files from these project files: sLog.mak, sDebug.mak, sNewDel.mak.

A common make file called "makefile" is provided to build all example programs. This file looks like this:

all: sLog sDebug sNewDel

sLog: sLog.mak sLog.cpp
	gmake -f sLog.mak
sDebug: sDebug.mak sDebug.cpp
	gmake -f sDebug.mak
sNewDel: sNewDel.mak sNewDel.cpp
	gmake -f sNewDel.mak

sLog.mak: sLog.rpr
	MakeMake sLog.rpr sLog.mak
sDebug.mak: sDebug.rpr
	MakeMake sDebug.rpr sDebug.mak
sNewDel.mak: sNewDel.rpr
	MakeMake sNewDel.rpr sNewDel.mak

Please note, that the executable file names are written according to the UNIX conventions and path names and some macros are eliminated for better understanding. See makefile in rMPL/smpl for a real example.

The gmake command compiles all applications, but you can compile only one application by typing

gmake rDebug

gmake -f rDebug.mak

The first is better, because it generates rDebug.mak if the project file (rDebug.rpr) is changed.

Project (*.rpr) Files

Project files are simple text files collecting all information for the MakeMake utility. One project file belongs to one application or library. If you have several applications you need to make several project files.

Project files contains the list of files required by the application. The application gets its name fron the *.rpr file. For example sDebug.rpr makes a program called sDebug.exe or sDebug depending the target platform conventions.

The project files also contains the paths where MakeMake will find files for the dependency lists. These paths are not the same as the include path given to the compiler, because of you may not want the system headers to be added to the dependency list.

Lines started with << characters are simply copied to the beginning of the make file, while lines started with >> characters are copied to the end of the make file. This is useful for defining macros or adding compiler and linker options.

Lines started with # are comments. Note, that lines started with <<# are copied to the make file, but these lines will be comments in the make file.

This description is written for giving a short overview. You can find the details in the documentation of MakeMake utility.

Macros and Environment Variables

Some environment variables must be defined before envoking gmake. These variables defines the selected compiler and platform. You can define them in your autoexec.bat or .profile files or you can use a bacth file or script where these variables are defined before calling gmake. These batch files and scripts are defined as d, m, and mm.

Environment variables:

RHOME_DIR and RPRJ_ROOT: Root directory, where all others project directory is placed (for example /prj_root). See Directory Structure for details. RHOME_DIR should be replaced with RPRJ_ROOT.
RPL: Name of the platform the project is made to. More exactly this is the name of directory in rMPL/src/_p and rMPL/inc/_p containing the platform specific source, header and make files.
RCMPLR: Name of the compiler the project is compiled with. More exactly this is the name of directory in rMPL/src/_c and rMPL/inc/_c containing the compiler specific source, header and make files.
DEBUG: Compile the project for debugging. Debug info and rDebug library are added to the project. Note, that the value of this variable is not used just its existance.

Directory names:

RPRJ_DIR: Directory of the project currently compiled (for example /prj_root/rMPL).
REXE_DIR: Directory to store the project's executable files (for example /home/_bin). You can define it as an environment variable, but if it is not defined, the make file will define it to $(RPRJ_DIR)/_bin/$(RPL)/$(RCMPLR).
RLIB_DIR: Directory to store the project's library files (for example /home/_lib). You can define it as an environment variable, but if it is not defined, the make file will define it to $(RPRJ_DIR)/_lib/$(RPL)/$(RCMPLR).
ROBJ_DIR: Directory to store temporary files of the project (for example /home/_obj). You can define it as an environment variable, but if it is not defined, the make file will define it to $(RPRJ_DIR)/_obj/$(RPL)/$(RCMPLR). Temporary files are files generated while making the projects, but they are not required for running the application and they are not part of the final product. Object files (*.obj *.o) is a good example.

File names and extensions:

REXE_EXT: File extension of executable files (.exe or nothing).
ROBJ_EXT: File extension of object files (.obj or .o).
RLIB_EXT: File extension of library files (.lib or .a).

Macros for the compiler:

RCC: Name of the compiler program.
RC_OUT_FLAG: Compiler option for name of output file.
RC_FLAGS: Compiler options. Use "RC_FLAGS += " to add more options. (-= would be nice to remove options, but it is not supported by gmake.)
RINC_DIR: List of include directories. Use "RC_FLAGS += " to add directories of the current project.

Macros for linking executables:

RLD: Name of the linker program.
RL_OUT_FLAG: Option for name of output file.
RL_FLAGS: Linker options. Use "RL_FLAGS += " to add more options.
RLIB_SEARCH_DIR: Path to search for library files while linking.

Macros for linking libraries:

RLL: Name of the linker program.
RLL_OUT_FLAG: Option for name of output file.
RLL_FLAGS: Linker options. Use "RLL_FLAGS += " to add more options.
RLL_DIR: ???????
RLL_OBJ_PREFIX: Prefix of object files in the linker's command line. Some linkers use the form of "o1.obj + o2.obj".

RDEL: Command name for deleting files. The name of the file to delete is given using UNIX conventions on all platforms, i.e. separated by '/' in make files.
RRUN: Command name for running executable files. The name of the file to execute is given with full using UNIX conventions on all platforms, i.e. separated by '/'. This macro is empty on all UNIX platforms, but contains the uexec, a utility program in rTools on Microsoft Windows and DOS.

Revision Control

None of the well known Revision Control Systems (RCS, CVS) is used. Our applications are small enough to manage them by hand. We prefer to maintain the source files by its author instead of the Revision Control System. We are keeping all software up to date and we avoid making branches in revisions of libraries.

All source codes are stored on a Linux server and the programmers can access the source files through the local Ethernet network. The latest release of all projects are stored in the project directory and the latest release of RCS's home page is stored in another directory. Both directory has a working or development version used only internally by programmers. The released version is available at http:/www.rcs.hu address.

The development versions must be good enough to compile, link and run applications uses them. You can think about the development version as the latest beta release of the products. Therefore, when someone works on a library frequently used by others s/he should make a local copy of that project, make the modifications locally and copy the beta release back to the development directory. In case of small projects, when only one programmer uses the code, it may be developed under the development directory without making local copies.

File Ownership and Access Rights

Every source files has an owner called Author, who is the programmer responsible for the given part of the project. Authors are software developers of RCS Ltd. They have their own user account on the server and they are members of the developer's group, while user's of libraries, the customers, are members of the user's group. The ownership of source files are set to the author's user account and the group is set to give reading access to files for developers or users depending of the status of the given source file. Public or opened files (headers, documentation, test and example programs, and some source files) are readable for all (owner, group and others) while other files are readable by the owner and group only. Only the owner has right to write any files.

These settings of access rights guaranties that only the author of a file can change the file. If someone else needs to change a file, s/he has to make a local copy, change it, and then send (by e-mail) or give the new file to the Author. The Author can check if the modifications are proper, has not done by someone else sooner on different way, and he can add it to the current version.

Directory Structure

This chapter describe how the files of projects are organized and explains the background.

Let's collect the points we need to keep in mind when the directory structure is created:

Source, interface (or header), documentation, example and test programs must be clearly separated.
Keep primary (source, header, and doc files), temporary files (object, etc.), library and executable files under different directories.
Keep files of one project under one directory.
Keep all projects under one directory.

As it is mentioned above all projects are stored in project directory called 'Project Root'. Every project has its own directory here, e.g. rMPL, rLib, rTools, and sub-projects are stored under their own sub-directory. For example rLib has sub-projects like rCntnr - containers, rProp - property library, rBinStrm - binary streams, etc.

From the other hand, source files, header files containing external definitions, documentation, example and test programs are all stored their separate sub-directory: src, inc, doc, smpl and test respectively. The temporary files, generally object files are stored under _obj, the libraries in the _lib, and the executable of the applications in the _bin directory. This solution makes easy to provide different parts of the project to programmers, customers, and "guests" who would like to review the project without getting it in any (source, object, executable) format.

These requirements are difficult to be satisfied at the same time.

The project has its own hierarchy:

/prj_root/
   rMPL/
   rLib/
      rCntnr/
      rProp/
      rBinStrm/

From the other hand we would like to collect files into the following sub-directories:

/
   _bin/
   _lib/
   _obj/
   inc/
   doc/
   src/
   smpl/
   test/

These two directory structure could be merged together on any level:

/prj_root/
   rMPL/
      _bin/
      ...
      test/
   rLib/
      rCntnr/
         _bin/
         ...
         test/
      rProp/
         _bin/
         ...
         test/
      rBinStrm/
         _bin/
         ...
         test/

or:

/prj_root/
   _bin/
      rMPL/
      rLib/
         rCntnr/
         rProp/
         rBinStrm/
   ...
   src/
      rMPL/
      rLib/
         rCntnr/
         rProp/
         rBinStrm/
   ...
   test/
      rMPL/
      rLib/
         rCntnr/
         rProp/
         rBinStrm/

Let's think about when we really need to separate projects from each others and when we need to separate include files from the source. Both are happen when a release version of the project is done, or the project is backed up, or moved to another computer, etc. Consequently most of the time we want to work with one project only. All projects sometimes backed up together, but this can be done regardless of the underlying directory structure.

From the other hand sub-projects never sold alone. They are always handled with the project itself. If you need to do so, you should think about making the sub-project to a separated main project.

These are the reasons of using the following directory structure at RCS Ltd.:

/prj_root/
   rMPL/
      _bin/
      _lib/
      _obj/
      inc/
         _c/
         _p/
      doc/
      src/
         _c/
         _p/
      smpl/
      test/
   rLib/
      _bin/
      _lib/
      _obj/
      inc/
         rCntnr/
         rProp/
         rBinStrm/
      doc/
         rCntnr/
         rProp/
         rBinStrm/
      src/
         rCntnr/
         rProp/
         rBinStrm/
      smpl/
         rCntnr/
         rProp/
         rBinStrm/
      test/
         rCntnr/
         rProp/
         rBinStrm/

You should note, that rMPL (rIDE's Multi Platform Library) and rLib (rIDE's Library) are two projects of RCS Ltd.

Backup Rules

Generating Release Versions

The release version is made by simple copying the development version, when it is ready for the next release. To avoid making mistakes a script is written. It removes temporary files (*.bak, dustbin/*, etc.), compiles and links a release version with no debug info, and makes a backup of the release. When a project or sub-project is ready, the Author runs this script to make the new release version. This chapter describes how to use this script and how it works.

The script has one argument, the name of the project, i.e. the name of directory (for example rMPL). It can work only on main projects, projects under the project root.

To update sub-projects a different script may be written doing the same tasks, but on all directories where the sub-project has files: doc, inc, src, smpl, test.

The script executes the following steps.

Defines two variables for /prj_root and /prj_root_devel. These variables are used everywhere in the script in the place of the source, the development library and the destination, the release library, but for better understanding the /prj_root_devel and /prj_root is used below in this description.
If previous copy exists, delete *.prev in /prj_root.
Rename the project's directory to *.prev in /prj_root.
Copy the project directory from /prj_root_devel to /prj_root.
Delete temporary files: dustbin/* or Dustbin/*, *.bak, vc*.pdb.
Change access rights.
Remove executable mode given by MS Windows from source files.
Sending e-mails to users needs to be notified about the project update.
Making a backup.

Robot Control Software Ltd. Úrbéres u. 62/A., Budapest, 1028 Hungary; Tel:+36-1 398-0200 Fax:+36-1 398-0202