readme.dev

打魔兽战网的都知道他是什么

		    PVPGN (wannabe) DEVELOPERS GUIDE

           Please read this file before asking any questions !

0. About this document
=======================

This document is intended to be read by all of you out there wanting to do
development or testing for/on PvPGN.

ChangeLog:
29-07-2003: dizzy : Initial version
28-08-2004: dizzy : Run-time debugging : Appendix A
30-08-2004: dizzy : Updated (fdwatch, xalloc, goto, gdb)

1. Why ?
=========

You want to start coding for PvPGN ? Why ? What do you expect to get from it ?
Answer yourself this questions and then go to the next paragraph.

2. History
===========

PvPGN has started as a game server emulation project, taking the excelent's
bnetd project source and working on it. While initially it has started as
a War3 emulation patch over bnetd it become a lot more than that (lots of
new features, lots of code changes organizing). Because of the code roots
you will notice a lot of things still carrying the "bnetd" word (most notable
examples are the main servers program file called "bnetd" or the main server
configuration file called bnetd.conf). We considered that as a sign of respect
from us to the bnetd coders we keep their names on the code they written (but
on the new code of course we may name them different).

3. Objective
=============

PvPGN's main objective is to support all Battle.Net clients (games) but are
considering in the near future to extend it to support other game protocols
as well.

4. Layout of files
===================

Note: Starting here on you may find lots of terms and wors which may sound
"strange" to you and for this reason we have included a glossary of terms
in the end of this file.

The PvPGN project consists of a main server (called "bnetd") and various
other programs and (little) servers (ex. bnchat, d2cs, d2dbs etc...).

PvPGN follows the bnetd's layout of files:
./bin			-> used to store binaries (after compilation)
./conf			-> configuration files (many of them templates)
./files			-> various files needed for clients connecting
./man			-> outdated man pages :(
./sbin			-> same as ./bin
./scripts		-> various scripts for testing/managing pvpgn
./src			-> the source main directory
./src/bnetd		-> source files used only by the main server
./src/common		-> source files used in common by different programs
./src/compat		-> source files concerning portability of code
...

The build process takes place in the "src" dir.

5. Coding Style
================

a. General

PvPGN is mainly developed on and for UNIX/Linux. The reasons are because we
as coders work on this systems and because our users (at least the big ones)
use UNIX/Linux more than ex. Windows. But, even so we try to code in a portable
fashion and any release PvPGN had we made sure it compiles on win32 too (we
even release win32 binaries). We will never refuse a good win32 coder but we
prefer UNIX ones ;)

One thing which is overlooked by newbie coders is the "esthetical" side of the
code. It may not be so important to many people (which code on the idea "if it
works then its good") but for us, coding on PvPGN is VERY important. When you
are coding for PvPGN PLEASE try to make your code look similar to already 
written code (this includes identing, identificator names, etc...). Keeping
the code look "the same" makes its reading a lot more easier so, finding
bugs easier so coding better.

One way to make sure your code sticks with the PvPGN coding style is to use 
"indent" code indenting formating tool (http://www.gnu.org/software/indent/). 
To use indent to get your code acording to PvPGN coding style use something 
like this (it will format properly the file clan.c and save the new file to 
clan.c.new):
$ indent -kr -bl -bli0 -l0 -br -ce -cli4 clan.c -o clan.c.new

Other overlooked aspect for newbie coders is code replication. Please DONT
copy and paste code arround !!! If you need to copy common functionality from
some place, think about making some API of that functionalilty, put it in
some functions and use it from both places. I repeat, DONT replicate code.

When allocating memory inside a function always free it in the same function
before its exit (exceptions: the function returns the allocated memory in
which case the calling function should take care of the allocated memory;
or the allocated memory is cached/stored somewhere to be used later, in which
case you must make sure it will be free()d when not needed anymore).

In the startup code of any "external" function (function which may be called
from other modules then the one containing it) please check ALL the input
parameters (you will notice how PvPGN already does that in such functions).
Traditionally this has been done with contructs like:
if (var==NULL) { eventlog(error); return <error-code>; }
We have recently changed our policy because of increasing code size and lots 
of redundant checks, we now usually prefer using assert() for this type of 
checks (check the manual page for assert). 

A new addition is the xalloc memory allocation wrappers (for malloc, 
calloc, realloc, strdup and free). We now do NOT allow memory allocation to 
take place without this wrappers. They make the code smaller and easier to 
read because they never fail so they eliminate the need for failure checks 
and eventlogs in such cases.

Another thing recently adopted in the team is the usage of "goto" keyword. 
Many people have argued (and continue to) that goto are inherently _evil_ and 
they produce "spaghetti code". But that is true for pointers and lots of other 
powerfull C features. We consider the programmer to be the cause of bad 
written codes and not some keywords. So we are moving into using "goto" 
mainly in the "error exit paths" cases. Let's say you have a function which 
needs to allocate some stuff (in 3 variables), checks for each allocation, 
exits with error for each specific failure (also free()ing the already 
allocated space). You can do it the PvPGN traditional way like:

------- CODE ----------
a = malloc(X);
if (!a) {
    eventlog(bla);
    return -1;
}

b = malloc(Y);
if (!b) {
    eventlog(bla);
    free(a);
    return -1;
}

c = malloc(Z);
if (!c) {
    eventlog(bla);
    free(b);
    free(a);
    return -1;
}
<do stuff>

return 0;
------ CODE -----------

Or you can do it the new, "goto" way:
--------- CODE --------------
a = malloc(X);
if (!a) {
    eventlog(bla);
    goto err_a;
}

b = malloc(Y);
if (!b) {
    eventlog(bla);
    goto err_b;
}

c = malloc(Z);
if (!c) {
    eventlog(bla);
    goto err_c;
}
<do stuff>
return 0;

err_c:
    free(c);
err_b:
    free(b);
err_a:
    return -1;
-------- CODE ------------

The last version is a lot easier to read/debug. Because the reader is usually