From 6e434d1fbe5c62d36bab14488a58348d0beb3f1a Mon Sep 17 00:00:00 2001 From: Jens Thiele Date: Wed, 20 Dec 2006 16:00:40 +0000 Subject: [PATCH] move usage example into libt2n --- doc/Doxyfile.in | 6 +--- doc/index.doc | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 4 deletions(-) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 72fa7b6..84f6970 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -502,9 +502,7 @@ EXCLUDE_PATTERNS = # directories that contain example code fragments that are included (see # the \include command). -# todo: we can't depend on example package here - -EXAMPLE_PATH = +EXAMPLE_PATH = ../examples-codegen/example1/ ../examples-codegen/example1-client/ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp @@ -1057,7 +1055,7 @@ TAGFILES = # When a file name is specified after GENERATE_TAGFILE, doxygen will create # a tag file that is based on the input files it reads. -GENERATE_TAGFILE = libt2n.tag +# GENERATE_TAGFILE = libt2n.tag # If the ALLEXTERNALS tag is set to YES all external classes will be listed # in the class index. If set to NO only the inherited external classes diff --git a/doc/index.doc b/doc/index.doc index 6a4accb..b1a9b91 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -58,3 +58,67 @@ - \anchor notes6 [6] boost serialization, http://www.boost.org/libs/serialization/doc/ */ + +/*! \page example Usage example + + 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 + + \section server Example server program and client library + + \par The procedure to export (input for the code generator - libt2n-codegen): t2nexample.cpp: + First the procedure to export is defined. In this example the procedure throws an exception if the input string is "throw". The exception is passed back to the client transparently. Otherwise some text is appended and returned. + \include example1/t2nexample.cpp + + \par Required includes go into the group header file: t2nexample.hxx: + All includes required to get the declarations of the types used by the procedures to export go into the group header file. libt2n uses boost for serialization. This means all types involved in a remote procedure call must be boost serializable. In this example we only use std::string provided by and boost already provides serialization for std::string in the boost/serialization/string.hpp header file. + \include example1/t2nexample.hxx + + \par The server program: server.cpp: + We have to provide the main entry point for the server program. In this example we use a local socket and the server program simply waits until a request.is received which then is handled by the generated code directly. + \include example1/server.cpp + + \par Using autoconf and automake to build a example server program and a client library. + In the configure.in(.ac) we check for libt2n using the LIBT2N_CHECK m4 macro provided by libt2n. + \verbinclude example1/configure.in + Writing the Makefile.am isn't difficult either. We have to list the command groups used. For each command group we have to list the C++ source files with the procedures to export. For each group we build a client library by listing the generated client code (group_client.cpp) in a corresponding libtool library target. The .pc file for the library is generated automatically. The sources of the server program must include the generated server code (group_server.cpp), the file with the main entry point and of course the procedure definition. + \verbinclude example1/Makefile.am + + \par Build and install the package + To build and install the package we first have to create the configure script and the other help scripts of the autotools by running autoreconf. + \verbatim + autoreconf -f -i && ./configure && make install + \endverbatim + + \section 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 example1-client/configure.in + \par The Makefile.am needs nothing special + \verbinclude example1-client/Makefile.am + \par The client program: client.cpp: + The example client first connects to the local socket. The connection is passed to the constructor of the generated class. To call the remote procedure the "testfunc" method is called. The example first passes "throw" to the remote procedure which will result in a exception to be thrown which is passed back to the client and thrown on the client side again. In the example the exception is caught and it is checked whether the string returned by what() is correct. If so a second remote procedure call is made and its return value is checked. Only if both tests succeed the program will exit with a status value indicating success. + \include example1-client/client.cpp + + \par Build and install the package + \verbatim + autoreconf -f -i && ./configure && make install + \endverbatim + + \par Test + To test whether it works we first start the server that creates a socket 'socket' in the current working directory. Then we run the client and print "ok" if it exited with a status value indicating success. + \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 +*/ -- 1.7.1