$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 the deisgn document (the online web version is probably the easiest to
read, 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 (1.5 or newer)
  * autoconf (2.5 or newer preferred, 2.13 will still work)
  * m4
  * gettext
  * make (GNU preferred)
  * flex
  * bison
  * gcc
  * groff
  * perl (5.003 or newer)

To prepare your working copy for building, run:
  % ./autogen.sh

The autogen.sh script runs gettextize, aclocal, autoconf, autoheader, automake,
and finally runs "./configure --enable-dev".  If an error occurs during this
process, something is wrong in your build configuration (such as required tools
missing or misconfigured).  After autogen.sh completes successfully, use make
to build YASM.  We recommend you use GNU make because gettext seems to play
better with it than with other make tools.  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.