$Id: HACKING 2058 2008-04-12 01:16:04Z peter $

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 (Subversion) Copy -- On UNIX


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 design 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 libyasm/ 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.  Or alternatively, read the online doxygen
generated documentation, which is autogenerated from the comments in these
files.

  * 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

The frontends/ directory contains the programs that users will actually run.
Right now, this is only "yasm", but others may be added someday.

The modules/ directory contains all the loadable module source code, organized
by module type (preproc, parser, etc.).

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 (Subversion) Copy -- On UNIX
====================================================

Unlike a packaged distribution, the YASM Subversion 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.  Programs required:
  * automake (1.5 or newer)
  * autoconf (2.5 or newer)
  * m4
  * gettext
  * make (GNU preferred)
  * Python
  * gcc

To rebuild the manpages from the DocBook XML files, the program "xmlto" and
all of its dependencies are required.

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-maintainer-mode".  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!