A convention for module implementations

To make life manageable we should agree in some rules for the names of the modules and their directories & files. In Pieter's paper about the software architecture the modules are given long names which are not practical for use in programs. For the implementation of the message system I use the following abbreviations:

The header, client and server files are described in the following sections. (The sonar module used to be called the acoustics module, therefore the acc abbreviation.)

For the modules which I must implement, I use a naming convention based on these abbreviations. Maybe we all can use these rules, because it will be easier to understand the programs of the other team members.

Each module consists of two distinct parts: the client and the server. The client handles the communication between an application and the server. The client is an object file (or an object library) which must be linked with the application. The server is a process (or process-thread) which is handling the requests coming from the application through the client. Only one copy of each server may be active, but more applications may use this single server. The client and server communicate by means of the Message System.

The module's client is built from a header file and a C file. The header file contains prototypes for the functions supplied by the module and any required typedefs, struct definitions, #defines etc. This header file is used by the application to access the interface functions of the client. The C file implements the communication between the application and the server by means of the Message System. As a convention the header file for module xyz is called Xyz.h and the C file XyzWrapper.h.

The server may be split in as many files as you like. I suggest using at least two: a header file and a C file. The header file, conventionally called XyzP.h, contains the layout of the messages between the server and the client. Both the client C file and the server C file(s) use this file, so they all use the same message layout. Applications do not need access to XyzP.h, they shouldn't send messages directly. The main (or only) C file for the server should be called XyzModule.c, and after compilation/linking this should end in a XyzModule executable.

A module should also include a Makefile, to ease generating the binaries. This Makefile should have at least the entries "wrapper", "module", "install" and "clean", which may be empty when no commands should be executed. The "wrapper" entry must copy the client header file to the ../include directory and insert the client object file in ../lib/libwrappers.a, where other modules can find them. By definition the client will only need the msg module. The "module" entry must build the server executable. This can require client files from other modules, but these are available now. The "install" entry must give the commands which should be executed by root, e.g. to give special priviledges to an executable, or to modify system directories. The "clean" entry must remove all files generated by the Makefile.