X-Git-Url: http://developer.intra2net.com/git/?p=libt2n;a=blobdiff_plain;f=codegen%2Fmain.cpp;h=f61d8098eab14898d940035bcfe1651bf03ff020;hp=fb57155a516537067cdbdda0e909cd25f3b8f83b;hb=d2f31d1e1c7da2d84c5cbd2b716a4a0158db1655;hpb=3907d211b0856140709b2376739bc462c4d37ba0

diff --git a/codegen/main.cpp b/codegen/main.cpp
index fb57155..f61d809 100644
--- a/codegen/main.cpp
+++ b/codegen/main.cpp
@@ -1,3 +1,116 @@
+/*
+    Copyright (C) 2006                                                    
+    intra2net.com                                                         
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+*/
+
+/*! \mainpage libt2n - (talk to neighbor)
+ \section intro_sec Introduction
+ 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 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
+ - boost <http://www.boost.org/> (serialization <http://www.boost.org/libs/serialization/doc/>)
+ - 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 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 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:
+ \verbinclude libt2n-example1/server.cpp
+
+ \par Using autoconf and automake to build a example server program and a client library.
+ In the configure.in(.ac) we put a check for libt2n:
+ \verbinclude libt2n-example1/configure.in
+ 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 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
+
+ 
+*/
+
+/*!
+ \example t2nexample.cpp
+ example input for libt2n-codegen
+*/
+
 #include <libxml++/libxml++.h>
 #include <cassert>
 #include <iostream>
@@ -10,6 +123,13 @@
 #include "config.h"
 #endif
 
+
+//! map group to class name
+std::string
+groupClass(const std::string &group) {
+    return std::string("cmd_group_")+group;
+}
+
 //! convert string to upper case
 std::string
 toupper(std::string s) {
@@ -294,7 +414,7 @@ protected:
 };
 
 void output_common_hpp(std::ostream &o, const std::string &group, const std::list<t2n_procedure> &procs) {
-    o << "class cmd_group_" << group << " : public libt2n::command\n"
+    o << "class " << groupClass(group) << " : public libt2n::command\n"
       << "{\n"
       << "private:\n"
       << "	friend class boost::serialization::access;\n"
@@ -322,7 +442,7 @@ void output_common_hpp(std::ostream &o, const std::string &group, const std::lis
 	  << "};\n";
     }
     for (std::list<t2n_procedure>::const_iterator it=procs.begin();it!=procs.end();++it) {
-	o << "class " << it->cmd_classname() << " : public " << "cmd_group_" << group << "\n"
+	o << "class " << it->cmd_classname() << " : public " << groupClass(group) << "\n"
 	  << "{\n"
 	  << "private:\n";
 	for (t2n_procedure::Args::const_iterator ait=it->args.begin();ait!=it->args.end();++ait) {
@@ -332,7 +452,7 @@ void output_common_hpp(std::ostream &o, const std::string &group, const std::lis
 	  << "	template<class Archive>\n"
 	  << "	void serialize(Archive & ar, const unsigned int /* version */)\n"
 	  << "	{\n"
-	  << "		ar & BOOST_SERIALIZATION_BASE_OBJECT_NVP(cmd_group_" << group << ");\n";
+	  << "		ar & BOOST_SERIALIZATION_BASE_OBJECT_NVP(" << groupClass(group) << ");\n";
 	for (t2n_procedure::Args::const_iterator ait=it->args.begin();ait!=it->args.end();++ait) {
 	    o << "		ar & BOOST_SERIALIZATION_NVP(" << ait->first << ");\n";
 	}
@@ -365,7 +485,7 @@ void output_common_cpp(std::ostream &o, const std::string &group, const std::lis
        << "#include <boost/serialization/export.hpp>\n"
        << "\n"
        << "/* register types with boost serialization */\n";
-     o << "BOOST_CLASS_EXPORT(cmd_group_" << group << ")\n";
+     o << "BOOST_CLASS_EXPORT(" << groupClass(group) << ")\n";
      for (std::list<t2n_procedure>::const_iterator it=procs.begin();it!=procs.end();++it) {
 	  o << "BOOST_CLASS_EXPORT("<<it->ret_classname()<<")\n"
 	    << "BOOST_CLASS_EXPORT("<<it->cmd_classname()<<")\n";
@@ -375,10 +495,10 @@ void output_common_cpp(std::ostream &o, const std::string &group, const std::lis
 void output_client_hpp(std::ostream &o, const std::string &group, const std::list<t2n_procedure> &procs) {
      o << "#include <command_client.hxx>\n";
 
-     o << "class cmd_group_" << group << "_client : public libt2n::command_client\n"
+     o << "class " << groupClass(group) << "_client : public libt2n::command_client\n"
        << "{\n"
        << "public:\n"
-       << "cmd_group_" << group << "_client(libt2n::client_connection &_c,\n"
+       << groupClass(group) << "_client(libt2n::client_connection &_c,\n"
        << "	long long _command_timeout_usec=command_timeout_usec_default,\n"
        << "	long long _hello_timeout_usec=hello_timeout_usec_default)\n"
        << "	: libt2n::command_client(_c,_command_timeout_usec,_hello_timeout_usec)\n"
@@ -398,7 +518,7 @@ void output_client_cpp(std::ostream &o, const std::string &group, const std::lis
      }
 
      for (std::list<t2n_procedure>::const_iterator pit=procs.begin();pit!=procs.end();++pit) {
-	 o << pit->ret_type << " cmd_group_" << group << "_client::" << pit->name << "(" << pit->args << ")\n"
+	 o << pit->ret_type << " " << groupClass(group) << "_client::" << pit->name << "(" << pit->args << ")\n"
 	   << "{\n"
 	   << "	libt2n::result_container rc;\n"
 	   << "	send_command(new " << pit->cmd_classname() << "(";