path: root/README

yChat++; Homepage: www.yChat.org; Version 0.6 
Copyright (C) 2003 Paul C. Buetow, Volker Richter
-----------------------------------------------------------------

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.

-----------------------------------------------------------------

0.0.0 YCHAT++ TABLE OF CONTENTS 
1.0.0 REQUIREMENTS
1.1.0 TESTED PLATFORMS
1.2.0 IMPORTANT NOTES
1.3.0 HOW TO OBTAIN YCHAT++ 
1.3.1 INSTALLATION
1.4.0 HOW TO USE SCREEN WITH YCHAT++
1.5.0 CUSTOMIZATION
1.6.0 FILES
1.8.0 CONTACT

1.0.0 REQUIREMENTS: 

- gcc 3.2
  The GNU C++ compiler.

- mysql-client 4.x ( 3.x may do too )
  Includes libmysqlclient and the mysql.h header files.

- ncurses 5.x   
  Includes libncurses and the ncurses.h header files.

- screen
  Only needed if yChat should run in background with
  ncurses enabled.

1.1.0 TESTED PLATFORMS:

The following platforms have been tested with success:

- Linux with GCC 3.2.0, GNU make 3.79.1
- FreeBSD 5.1-RELEASE-p2, GCC 3.2.2, GNU make 3.80 ( standard make does not seem work on FreeBSD ). 

1.2.0 IMPORTANT NOTES:

Before you compile the source you have to be sure to use at least GCC
version 3.x with pthreads enabled. ( Type gcc -v to check it ).
GCC 2.95 did not work while testing on linux and WON'T BE SUPPORTED!
If you like to support yChat++, please write us an email and tell what 
you can/like/would help ;-]. Please also take a look at the yChat++
homepage which is located at http://www.yChat.org.

1.3.0 HOW TO OBTAIN YCHAT++:

yChat can be downloaded as a source package or through CVS. 

The packages are located at http://www.yChat.org -> Sourcecode -> 
Packages or go to http://programming.buetow.org/CPP-yChat .

For CVS download type:

cvs -d:pserver:anonymous@cvs.ychat.berlios.de:/cvsroot/ychat login
( You will be asked for a password. Use "just enter" ).

cvs -z3 -d:pserver:anonymous@cvs.ychat.berlios.de:/cvsroot/ychat co \
 ychat
( The sources will be copied into your local folder. However, if you 
  want to obtain the yChat++ Basic sources then replace "ychat"
  "ychat-basic" ).

cvs -d:pserver:anonymous@cvs.ychat.berlios.de:/cvsroot/ychat logout
( Logs your CVS session out ).

Now you may continue with the installation.

1.3.1 INSTALLATION:

If you dont want to use yChat's ncurses based administration interface 
you may remove the #define NCURSES line in the glob.h and enable
#define SERVMSG and #define VERBOSE instead.

Now invoke "./configure" and afterwards "make", edit the conf.txt ( be 
sure to enter a valid mysql account ) host.

Now we want to compile all the dynamic loadable modules of ychat.
Invoke "cd mods && ./compile.sh && cd -". All modules should get
compiled.

Now its time to run the server with ./ychat.
Then point your webbrowser to http://yourip:port/index.html ( ignoring
the index.html on the end of the url will not work! ). 
... have fun :-).


1.4.0 HOW TO USE SCREEN WITH YCHAT++:

If you are running yChat in ncurses mode you might want to install
the tool which is called "screen". This will enable you putting the
ncurses interface into the background, closing the terminal session
and reusing the interface later through another terminal. 

Just do:
 
 screen -S ychat ./ychat ( creates a new session and starts ychat in it )
 strg+d+a ( will detach the ychat session )
 ( closing the terminal )
 ( opening a new terminal )
 screen -r ychat ( will return you to the ychat process )

Screen will terminate automaticaly if all processes in its sessions are 
terminated.

For a closer look read the screen manual page ( man screen ). 

1.5.0 CUSTOMIZATION:

If you like to customize the design/layout/language of yChat, you will have 
to edit msgs.h and glob.h before you compile the sources. Afterwards you can
change the html-template files which are placed in the html/ subdirectory and
the language-template files which are placed in the lang/ subdirectory.
Dynamic loadable modules can be found in the mods/ subdirectory. ( chat 
commands are realized through modules too ).

1.6.0 FILES: ( This list is not complete )

conf.txt - The yChat configuration file. ( read by conf.cpp ).

base.cpp - Encapsulates vector fields of room's or user ( may be later
           hash_maps ) and provides methods for manipulating data
           objects.

hmap.cpp - The hash map implementation which is a very fast data
           structure. is needed for saving users, rooms and so on.

main.cpp - This includes the required manager headers for starting 
           the server and finally regulates the correct starting.

modl.cpp - The module loader. Stores pointers of all dynamic loaded
           yChat modules in a hash map object and loads new modules
           if desired or returns their pointers.

pool.cpp - The implementation of the thread pool. all threads are stored 
           in a queue. Each thread will be reused if the assigned job is 
           finished.

reqp.cpp - This class implements the http request parser. If a client
           starts a request to the server the reqp class will be
           invoked.

room.cpp - Specifies a chat room. For each chat room an instance of
           this class exists.

thrd.cpp - This class is needed by sock.cpp while creating a POSIX thread.
           All data which a thread needs to do its tasks are stored in a
           thrd object and then a pointer to it will be passed to the
           POSIX thread function.

user.cpp - Specifies a chat user. For each chat user an instance of
           this class exists.

Abstract classes:

cont.cpp - All classes which need to store "key - value" data sets
           inherit from this class. ( cont for content ). 

name.cpp - All classes which own a private member string name inherit
           from this class. It also provides public get_name and 
           set_name methods.

As described ( main.cpp ), there are so called managers. Managers are 
accessible through their assigned wrapper classes and may be 
instanciated only once.       

chat.cpp - The chat manager. Is responsible for managing the internal
           data structure of the system and also covers a lot of
           important methods of the system.

conf.cpp - The config manager. Parses the config file specified in
           glob.h and stores all the values of it in a map.

html.cpp - The html-template manager. Reads the requested html-template
           files, stores them in an internal cache ( averts reading 
           template-files from hd twice or more ) and parses the 
           partivular template in order to substituate dynamic values
           of it.

mutx.cpp - The mutex manager. Contains all global mutex handlers for
           synchronizing POSIX thread shared data. until now only the
           stdout is synchronized by mutx.cpp because most of objects
           use their own mutex'.

sock.cpp - The socket manager. Manages the socket connections. There 
           are multiplexed sockets. For each requests a new POSIX thread
           will be created.

Files with a leading s_ contain static C++ classes

s_chat.cpp - Static wrapper for the dynamic chat class. holds one global 
           reachable instance of chat until the program shuts down. 

s_conf.cpp - Static wrapper for the dynamic conf class. holds one global 
           reachable instance of conf until the program shuts down. 

s_html.cpp - Static wrapper for the dynamic html class. holds one global 
           reachable instance of conf until the program shuts down. 

s_mutx.cpp - Static wrapper for the dynamic mutx class. holds one global 
           reachable instance of conf until the program shuts down. 

s_sock.cpp - Static wrapper for the dynamic sock class. holds one global 
           reachable instance of conf until the program shuts down. 

s_tool.cpp - Static class which includes some usefull global reachable
           methods which are not integraded in independent classes.

Special header files ( all other header files which are not listed here
belong to their respective .cpp files ):

glob.h   - Defines global variables which are known by compilation 
           time. 

incl.h   - This file is included from every other header file and
           includes a set of headers which every class should be able
           to use.

msgs.h  -  Defines console output messages for verbosity level 0 ( see
           glob.h for setting up verbosity levels ). and also defines
           all the system messages. you may edit this file for translating
           the system user language.

The basic class structure:

 base<room> base<user>
    |           |   name 
    |           |  /    \
    |           | /      \
  chat         room      user

    cont
   /    \
  /      \
conf     html

1.8 CONTACT:

You may contact us through the following addresses:

- Homepage
  The yChat homepage is located at http://www.yChat.org

- E-Mail
  Paul C. Buetow: Snooper@yChat.org ( core developer )
  Volker Richter: Rover@yChat.org ( core developer )
  Mail@yChat.org ( reaches everybody of yChat )
 
- ICQ
  Paul C. Buetow: 11655527

- IRC
  #ychat at irc.german-elite.net