COID - First Steps

LINUX

Installation

get the latest Linux (!) version of coid from http://coid.sourceforge.net/

untar it to a fitting directory, e.g. /usr/local (but not /usr/local/bin, because the executable coid is placed there)

go to the directory you have chosen and run make

You probably have to install the library 'curses' first. With SuSE just install the standard curses-devel package using YAST. Afterwards you have to make a static link on libncurses
ln -s libncurses.a /usr/lib/libcurses.a

run 'make install'

Directory structure

The following directories are created:
/usr/local/bin                    contains the executables coid, coidgen, coidc
/usr/local/lib/coid               contains libcoidserver.so
/usr/local/lib/coid/device        contains the .dev files
/etc/coid/                        contains assert.log

Creating the server-side files

Let's assume you already have a header file (example.h), containing the class you want to export (to export means to make it available as a service on a coid server). It's important that this file contains only one decorated (= meant to be exported) class. More about the decoration of the header file with keywords in the example document.
It's recommended that you place your header file in /coid_directory/apps/projectname/.

At first you have to run coidgen. In case you want to compile your server and client on different machines, just run coidgen once (on one machine!) and distribute the generated files afterwards.
coidgen example.h

This generates the whole communication layer for the client and server from information found in that header, without modifying the class.
The output of coidgen is a set of files for the client (the directory 'client' is created for it) and for the server (is placed in the same directory as the service header). In our example it would generate example_dispatch.h, Makefile, client/example_client.cpp and client/example_client.h.

The server source file is postfixed with _dispatch. To generate a file (device) that the server can load (.dev), you have to run make. The makefile therefore was also generated by coidgen before.

make will generate the .dev file. It's named [ExportedClass].dev and is being placed in /coid_directory/bin/device/[ExportedClass]/.
That's nearly everything you have to do on the server side. Just copy the [ExportedClass] directory to /usr/local/lib/coid/device. The server looks by default only in this directory for the devices.

The command therefore could look like:

    cp -r /usr/local/coid/bin/device/TestClass/ /usr/local/lib/coid/device

Attention: Do not overwrite a currently used device! (Shut down server first)

Once the coid server has been started and has loaded the device file, the exported class can be called remotely from clients. Communication takes place over network or in case the server and client are on the same machine, coid uses interprocess communication.
For more information about coidgen read http://coid.sourceforge.net/web/gencoid.html.

Creating the client-side files

As written above coidgen creates the client directory and puts a [service header file]_client.cpp and a [service header file]_client.h file in there, e.g. example_client.cpp and example_client.h.

The header file (_client.h) contains the declaration of the exported class. The source file (_client.cpp) implements the methods as calls to the coid server over the network.
In case of the client there is no Makefile generated by coidgen. That's because the client files normally become a part of an existing project.

Let's say there is a client.cpp, which is calling a few methods from the exported class. In this case you would have to compile the client like that:

g++ -Wall -I/usr/local example_client.cpp client.cpp /usr/local/coid/comm/comm.a -lpthread -ldl -o client

So you have to compile these two files:
    example_client.cpp     the generated _client.cpp file
    client.cpp              your client file(s) - a detailed example follows
and include three libraries:
    /usr/local/coid/comm/comm.a   the comm.a library
    -lpthread               the libpthread library
    -ldl                   the libdl library

This generates the executable client. You can run it just like any other program, but the coid server has to run (not necessarily local).

The COID server

To start the coid server you just have to type coid. In this case the server uses by default the port 55099, looks for the device files in /usr/local/lib/coid/device and starts all services found in this files.
If you want to change these defaults, you will have to create a .devconf configuration file.
To start the server using a .devconf file, type coid /devconf_directory/.

The .devconf file can contain these lines:


'port' PORT




'directory' NAME




'default' ('all' | 'none')




'service' NAME ('port' NUM)? ('dir' PATH)?




'!service' NAME

port       That's the server port the client has to connect to.
directory    In this directory (and subdirectories) the server looks for .dev files.
default     all (load all services) / none (just load services listed with service)
!service   do not load service NAME
service     load service NAME, optionally using an additional acceptor port (not coid acceptor port!) and working directory (not device directory!)

Once started, you will see a listing which services have been started. If your service (the name is your exported class) is listed, everything went well and you can start your client.

Automation of the compiling process

Since there are a lot of steps to do to get from the service header file to the device file and from the client source to the executable, it's handy to have a script doing that. It could look like that for example:


#!/bin/bash 




echo "***************************"




echo "****** coid shutdown ******"




echo "***************************"




killall coid





echo "*********************"




echo "****** coidgen ******"




echo "*********************"




cd /usr/local/coid/apps/example/




coidgen ./example.h





echo "***************************"




echo "****** make (server) ******"




echo "***************************"




make





echo "********************"




echo "****** client ******"




echo "********************"





cd /usr/local/coid/apps/example/client




g++ -Wall -I/usr/local example_client.cpp client.cpp /usr/local/coid/comm/comm.a -lpthread -ldl -o client





echo "***********************"




echo "****** copy .dev ******"




echo "***********************"




cp -r /usr/local/coid/bin/device/TestClass/ /usr/local/lib/coid/device





echo ""




echo "--> todo: coid restart"

The directories and filenames have to be modified appropriately.

More services in one device

It is possible to link more than one service in a single device. Therefore just run coidgen for every service header file and then run make. make links all _dispatch.h files to the device.
On the client side just include all _client files.