First version of HACKING, only for Unix and not nearly complete.

Also makes reference to incomplete (and not in CVS) design document.

svn path=/trunk/yasm/; revision=222

diff --git a/HACKING b/HACKING
new file mode 100644 (file)
index 0000000..4b3ddec
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,101 @@
+$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.