GreedMud Release 0.99.8
Tuesday, 20th February 2001
Zen <greedmud@egroups.com>
This is *heavily* based on MERC 2.2 documentation written by Furey.
-----------------------------------------------------------------------------
=== 'I'm running a Mud so I can learn C programming!'
Yeah, right.
The purpose of this document is to record some of our knowledge, experience and
philosophy. No matter what your level, we hope that this document will help
you become a better software engineer.
Remember that engineering is work, and NO document will substitute for your
own thinking, learning and experimentation.
=== How to Learn in the First Place
(1) Play with something.
(2) Read the documentation on it.
(3) Play with it some more.
(4) Read documentation again.
(5) Play with it some more.
(6) Read documentation again.
(7) Play with it some more.
(8) Read documentation again.
(9) Get the idea?
The idea is that your mind can accept only so much 'new data' in a single
session. Playing with something doesn't introduce very much new data, but it
does transform data in your head from the 'new' category to the 'familiar'
category. Reading documentation doesn't make anything 'familiar', but it
refills your 'new' hopper.
Most people, if they even read documentation in the first place, never return
to it. They come to a certain minimum level of proficiency and then never
learn any more. But modern operating systems, languages, networks, and even
applications simply cannot be learned in a single session. You have to work
through the two-step learning cycle MANY times to master it.
=== The Environment
Computer: the big or little box that you're using to run Greed. Computers come
from a _manufacturer_ and have a _model_ name. Here is a list of common
manufacturers and models that you're likely to encounter:
Manufacturer Model
------------ -----
Sun Enterprise Server
Compaq Alpha
IBM RS/6000
HP HP 9000
White Box (?) x86 based PC running Linux/BSD
As far as hardware goes, Greed will run on any 32-bit hardware.
Operating system: the lowest level program running on your computer. Most
common computers run Unix or some variant of it, such as SunOS, Ultrix,
AIX, Mach, Dynix, BSD or Linux. Notice that many of these variants end
in 'IX'.
The two major 'families' of Unix are Berkeley Unix (developed at the
illustrious University of California, Berkeley) and System V Unix
(developed by Bell Laboratories, the progenitors of Unix).
Most modern unix'es are a mix of both. They usually aim for POSIX and/or
X/OPEN standards compliance.
The most common non-Unix operating system is VMS (a proprietary operating
system from DEC for their VAX computers). In the personal computer world,
you'll find Linux, BSD, BeOS, OS/2, WIN32 based Microsoft OS'es like
Windows NT/2000/XP or Windows 95/98 for IBM PC's and compatibles, and
MacOS for Apple Macintosh'es.
GET THIS STRAIGHT: 'VAX' IS NOT AN OPERATING SYSTEM. It's the name of a
family of computers from DEC. There are plenty of Vax'es running VMS, and
there are even more Vax'es running Berkeley Unix or Ultrix. The Vax'es
running Unix have a lot more in common with other machines running
Unix than they have with Vax'es running VMS.
As far as operating systems go, Greed will run on Unix or Unix variants with
TCP/IP networking compatible with Berkeley Unix. With a reasonable amount
of work, Greed can be ported to any operating system that provides TCP
service for telnet connections.
Languages: Greed is written in C. ANSI (the American National Standards
Institute) has a specification for the C language, and Greed is written in
Ansi Standard C. We have converted Greed to be ANSI C++ compliant recently.
The most popular compiler for Ansi Standard C is the GNU 'gcc' compiler
produced by the Free Software Foundation. It's available by anonymous
ftp from prep.ai.mit.edu. Greed compiles just fine with GCC 2.72, so
you can probably use 2.72 and skip the much larger 2.9X versions.
You don't have to use gcc. IBM RS/6000's running the AIX operating system
come with an Ansi C compiler already. So do NeXT machines (the standard
'cc' on NeXT happens to be the GNU C compiler). Any Ansi compiler will
work.
Unfortunately, there are still many machines out there without an Ansi
standard C compiler. (Sun is the worst offender in this regard).
If you don't know what the manufacturer and model of your computer is, as well
as its operating system, and whether the C compiler is Ansi or non-Ansi, then
you need to find out.
=== Basic Unix Tools
'man' -- gives you online manual pages
'grep' -- stands for 'global regular expression print'
'more'
'less' -- these are filters for paging through text one screenful at a time.
'vi'
'emacs'
'joe'
'pico' -- use whatever editor floats your boat
but learn the hell out of it
you should know EVERY command in your editor
'ctags' -- makes 'tags' for your vi editor
allows you to goto functions by name in any source file
'etags' -- makes 'tags' for your emacs editor
allows you to goto functions by name in any source file
'>'
'>>'
'<'
'<<'
'|' -- input and output redirection
get someone to show you, or dig it out of 'man csh'
These are the basic day-in day-out development tools. Developing without
knowing how to use ALL of these well is like driving a car without knowing how
to change gears.
=== Unix X Tools
'nedit' -- The greatest of X editors in my view, easy to use, small & fast.
'ddd' -- A X interface for gdb, useful if you don't know the zillion options
in gdb and want a more user friendly interface.
These are some X development tools. XEmacs is also nice, but slow and bloated
and not nearly as user-friendly. You do not need these but they are much easier
to use than most command line tools. However, you don't always have X
available...
=== Debugging: Theory
Debugging is a science. You formulate a hypothesis, make predictions based on
the hypothesis, run the program and provide it experimental input, observe its
behavior, and confirm or refute the hypothesis.
A good hypothesis is one which makes surprising predictions which then come
true; predictions that other hypotheses don't make.
The first step in debugging is not to write bugs in the first place. This
sounds obvious, but sadly, is all too often ignored.
If you build a program, and you get ANY errors or ANY warnings, you should fix
them before continuing. C was designed so that many buggy ways of writing code
are legal, but will draw warnings from a suitably smart compiler (such as 'gcc'
with the '-Wall' flag enabled). It takes only minutes to check your warnings
and to fix the code that generates them, but it takes hours to find bugs
otherwise.
'Desk checking' (proof reading) is almost a lost art in 1993. Too bad. You
should desk check your code before even compiling it, and desk-check it again
periodically to keep it fresh in mind and find new errors. If you have someone
in your group whose ONLY job it is to desk-check other people's code, that
person will find and fix more bugs than everyone else combined.
One can desk-check several hundred lines of code per hour. A top-flight
software engineer will write, roughly, 99% accurate code on the first pass,
which still means one bug per hundred lines. And you are not top flight.
So ... you will find several bugs per hour by desk checking. This is a very
rapid bug fixing technique. Compare that to all the hours you spend screwing
around with broken programs trying to find ONE bug at a time.
The next technique beyond desk-checking is the time-honored technique of
inserting 'print' statements into the code, and then watching the logged
values. Within Greed code, you can call 'printf' or 'fprintf' to dump
interesting values at interesting times. Where and when to dump these values
is an art, which you will learn only with practice.
If you don't already know how to redirect output in your operating system, now
is the time to learn. On Unix, type the command 'man csh', and read the part
about the '>' operator. You should also learn the difference between
'standard output' (e.g. output from 'printf') and 'error output' (e.g. output
from 'fprintf').
Ultimately, you cannot fix a program unless you understand how it's operating
in the first place. Powerful debugging tools will help you collect data, but
they can't interpret it, and they can't fix the underlying problems. Only you
can do that.
When you find a bug ... your first impulse will be to change the code, kill the
manifestation of the bug, and declare it fixed. Not so fast! The bug you
observe is often just the symptom of a deeper bug. You should keep pursuing
the bug, all the way down. You should grok the bug and cherish it in fullness
before causing its discorporation.
Also, when finding a bug, ask yourself two questions: 'what design and
programming habits led to the introduction of the bug in the first place?'
And: 'what habits would systematically prevent the introduction of bugs like
this?'
=== Debugging: Tools
When a Unix process accesses an invalid memory location, or (more rarely)
executes an illegal instruction, or (even more rarely) something else goes
wrong, the Unix operating system takes control. The process is incapable of
further execution and must be killed. Before killing the process, however, the
operating system does something for you: it opens a file named 'core' and
writes the entire data space of the process into it.
Thus, 'dumping core' is not a cause of problems, or even an effect of problems.
It's something the operating system does to help you find fatal problems which
have rendered your process unable to continue.
One reads a 'core' file with a debugger. The most popular debugger on
Linux is 'gdb'. You can start gdb like this: 'gdb envy core', or 'gdb envy'.
The first thing, and often the only thing, you need to do inside the debugger
is take a stack trace. In gdb, the command is 'backtrace'. The stack trace
will tell you what function your program was in when it crashed, and what
functions were calling it. The debugger will also list the arguments to these
functions. Interpreting these arguments, and using more advanced debugger
features, requires a fair amount of knowledge about assembly language
programming.
=== Debugging: Basic GDB Commands
First of all don't forget to compile with the '-g' flag to have debugging
information available. That means changing the makefile and recompiling.
'run' -- run executable
'backtrace' -- prints stack trace
'up'
'down' -- walk up and down the stack trace
'list' -- list program source code
'print' -- print value of an expression
'help' -- gives you online help
=== Debugging: Programs to Debug Memory Problems
If you have access to a program named 'Purify' ... learn how to use it.
If you don't have 'Purify' you more than likely can get the Electric Fence
malloc() debugger for your Unix flavour. If you have X and GNOME installed you
can try memprof.
=== Profiling
Here is how to profile a program:
(1) Remove all the .o files and the 'envy' executable:
make clean
(2) Edit your makefile, and change the PROF= line:
PROF = -pg
(3) Remake envy:
make
(4) Run envy as usual. Shutdown the game with shutdown when you have run long
enough to get a good profiling base. If you crash the game, or kill the
process externally, you won't get profiling information (In C lingo the
program must return an exit value of 0).
(5) Run the 'prof' command:
gprof envy > prof.out
(6) Read prof.out. Run 'man gprof' to understand the format of the output.
This form of profiling gives you a report which lists exactly how many times
any function calls any other function. This information is valuable for
debugging as well as performance analysis.
==== Index to Free Software Resources
<http://www.freshmeat.net>
=== Books for Serious Programmers
Out of all the thousands of books out there, three stand out:
Kernighan and Plaugher, _The Elements of Programming Style_.
Kernighan and Ritchie, _The C Programming Language 2nd Edition_.
Brooks, _The Mythical Man Month_