$IdPath$

If you are contributing code to the YASM project or trying to compile YASM
from a CVS checkout, please read this first.


======================
HACKER'S GUIDE TO YASM
======================

Table of Contents

  * What to Read
  * Building From a Working (CVS) Copy -- On UNIX
  * Generating ChangeLogs


What to Read
============

Before you can contribute code, you'll need to familiarize yourself with the
existing codebase, design, and internal interfaces.

Check out a copy of YASM from CVS (or grab a development tarball) so you can
look at the codebase.

Look at doc/design/ (you'll probably want to look at the online version,
because the design doc is written in DocBook and most people don't have the
SGML tools installed to process it).  This is the overall design document,
which gives you a high-level view of the assembler modular structure and how
the various components interface.  It also covers coding standards.

Within the src/ directory, there's a bunch of header files with huge comments.
If you read through these, you'll have a pretty good understanding of the
implementation details.

  * the core data structures: bytecode.h, section.h, expr.h, symrec.h
  * the module interfaces: preproc.h, parser.h, objfmt.h, optimizer.h, etc.
  * the error/warning system: errwarn.h

YASM is written in ANSI/ISO C89 for maximum portability.  See the design
document for more details on portability considerations.  Several C files and
util.h provide functions that are standard on some machines but not available
on others.  The function and header checks are performed using GNU configure.


Building From a Working (CVS) Copy -- On UNIX
=============================================

Unlike a packaged distribution, the YASM CVS tree doesn't contain a configure
script nor any of the other generated files normally used in configuration and
building.  You have to regenerate these files in your local copy before
running configure.

Building in this fashion requires many more programs than YASM normally
requires in a packaged distribution.  All of the following are GNU programs,
which are fairly portable in their own right:
  * automake
  * autoconf
  * m4
  * gettext
  * make
  * flex
  * bison
  * gcc
  * groff
  * perl

To prepare your working copy for building, run:
  % aclocal
  % gettextize
  % autoreconf
  % configure --enable-dev

(TODO: explain --enable-docbook and its required packages)

(TODO: explain --disable-check)

After running configure, use make to build YASM.  We recommend you use GNU
make because automake generates better dependency checking when it's used.
Use the distcheck target of make to build a package.  If this doesn't complete
successfully, something is wrong in the source tree.  If you caused the
breakage, fix it or ask someone to help you fix it.  If you didn't cause it
(it happens with a new checkout), notify the developers!

Generating ChangeLogs
=====================

YASM does not keep ChangeLog files, because they're redundant with the CVS log
entries.  But ChangeLog is an easier format to browse, so it's often handy to
generate a ChangeLog from the CVS log data.  You can do so with the script
cvs2cl.pl, from:

  http://www.red-bean.com/cvs2cl/

If you've never used it before, try invoking it like this:

  cvs2cl.pl -r -f Changes

Caution: don't use the default output filename (ChangeLog) in the top-level.
It's all too easy to check it into CVS by accident.  Someday we may fix this.