Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
-/*! \mainpage libt2n - (talk2neighbor)
+/*! \mainpage libt2n - (talk to neighbor)
\section intro_sec Introduction
- libt2n (talk2neighbor) is a C++ library for inter-process communication (IPC, s.a. http://en.wikipedia.org/wiki/Inter-process_communication)
- with an additional code generator to make remote procedure calls simple. XXX: improve this paragraph: The input for the code generator is standard C++ code (in fact we use gccxml to parse the C++ code and the code generator takes the XML as input) and you mark the procedures you want to expose to other processes.
+ libt2n (talk to neighbor) is a C++ library for inter-process communication (IPC, s.a. http://en.wikipedia.org/wiki/Inter-process_communication)
+ with an additional code generator to make remote procedure calls simple.
+ \par
+ XXX: improve this paragraph: The input for the code generator is standard C++ code (in fact we use gccxml to parse the C++ code and the code generator takes the XML as input) and you mark the procedures you want to expose to other processes.
It then generates the stubs needed.
- The exported procedures can be grouped. For each group the code generator is called which generates 6 outputfiles: group_common.hxx, group_common.cpp, group_client.hxx, group_client.cpp, group_server.hxx, group_server.cpp. The _common files are used by client and server whereas the _client files are used by the client and the _server files by the server.
-
+ The exported procedures can be grouped. For each group the code generator is called and generates 6 output files: group_common.hxx, group_common.cpp, group_client.hxx, group_client.cpp, group_server.hxx, group_server.cpp. The _common files are used by client and server whereas the _client files are used by the client and the _server files by the server only.
+ \par
+ To simplify the build process a Makefile snippet is provided that allows to create a server program and a client library (including a corresponding .pc file) using the autotools easily.
\section install_sec Installation
\subsection requirements Requirements
- gccxml <http://www.gccxml.org>
- libxmlpp <http://libxmlplusplus.sourceforge.net/>
+ \subsection recommended Recommended
+ - pkg-config <http://pkgconfig.freedesktop.org/wiki/>
+ - autotools (automake, autoconf, libtool)
+
+ \subsection Compilation
+ \verbatim
+ ./configure && make install
+ \endverbatim
+
+
\section usage Usage example
- In this example we create two packages:
- - server program and library to connect to the server. The server exports a simple procedure using one group: "t2nexample"
+ In this example we create two packages using the autotools:
+ - server program and client library to connect to the server. The server exports a simple procedure using one group: "t2nexample"
- client program using the library
\subsection server Example server program and client library
\par The procedure to export (input for the code generator - libt2n-codegen): t2nexample.cpp:
\verbinclude libt2n-example1/t2nexample.cpp
- \par Required includes must be put into a seperate group header file: t2nexample.hxx:
+ \par Required includes go into the group header file: t2nexample.hxx:
+ libt2n uses boost for serialization. This means all types involved in a remote procedure call must be boost serializable. In this example we use std::string and boost
+ already provides serialization for std::string in the boost/serialization/string.hpp header file.
\verbinclude libt2n-example1/t2nexample.hxx
\par The server program:
Writing the Makefile.am isn't difficult either:
\verbinclude libt2n-example1/Makefile.am
+ \par Build and install the package
+ \verbatim
+ autoreconf -f -i && ./configure && make install
+ \endverbatim
+
\subsection client Client using the library
Using the library is as simple as using any other library using pkg-config (the pkg-config .pc file is created automatically by the included Makefile snippet)
\par We only have to check that the library is installed
\verbinclude libt2n-example1-client/configure.in
- \par Nothing special
+ \par The Makefile.am needs nothing special
\verbinclude libt2n-example1-client/Makefile.am
\par The client program
\verbinclude libt2n-example1-client/client.cpp
+
+ \par Build and install the package
+ \verbatim
+ autoreconf -f -i && ./configure && make install
+ \endverbatim
+
+ \par Test
+ \verbatim
+$ cd /tmp
+$ file socket
+socket: cannot open `socket' (No such file or directory)
+$ libt2n-example1-server &
+[1] 7711
+$ file socket
+socket: socket
+$ libt2n-example1-client && echo ok
+ok
+$ kill %1
+$ rm socket
+ \endverbatim
+
*/