yasm/HACKING - third_party/yasm - Git at Google

 $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 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 (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)
   * m4
   * gettext
   * make (GNU preferred)
   * 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-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!

 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.
	$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 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 (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)
	* m4
	* gettext
	* make (GNU preferred)
	* 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-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!

	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.