granicus.if.org Git - yasm/blob - HACKING

   1 If you are contributing code to the YASM project or trying to compile YASM
   2 from a CVS checkout, please read this first.
   3
   4
   5 ======================
   6 HACKER'S GUIDE TO YASM
   7 ======================
   8
   9 Table of Contents
  10
  11   * What to Read
  12   * Building From a Working (Subversion) Copy -- On UNIX
  13
  14
  15 What to Read
  16 ============
  17
  18 Before you can contribute code, you'll need to familiarize yourself with the
  19 existing codebase, design, and internal interfaces.
  20
  21 Check out a copy of YASM from CVS (or grab a development tarball) so you can
  22 look at the codebase.
  23
  24 Look at the design document (the online web version is probably the easiest to
  25 read, because the design doc is written in DocBook and most people don't have
  26 the SGML tools installed to process it).  This is the overall design document,
  27 which gives you a high-level view of the assembler modular structure and how
  28 the various components interface.  It also covers coding standards.
  29
  30 Within the libyasm/ directory, there's a bunch of header files with huge
  31 comments.  If you read through these, you'll have a pretty good understanding
  32 of the implementation details.  Or alternatively, read the online doxygen
  33 generated documentation, which is autogenerated from the comments in these
  34 files.
  35
  36   * the core data structures: bytecode.h, section.h, expr.h, symrec.h
  37   * the module interfaces: preproc.h, parser.h, objfmt.h, optimizer.h, etc.
  38   * the error/warning system: errwarn.h
  39
  40 The frontends/ directory contains the programs that users will actually run.
  41 Right now, this is only "yasm", but others may be added someday.
  42
  43 The modules/ directory contains all the loadable module source code, organized
  44 by module type (preproc, parser, etc.).
  45
  46 YASM is written in ANSI/ISO C89 for maximum portability.  See the design
  47 document for more details on portability considerations.  Several C files and
  48 util.h provide functions that are standard on some machines but not available
  49 on others.  The function and header checks are performed using GNU configure.
  50
  51
  52 Building From a Working (Subversion) Copy -- On UNIX
  53 ====================================================
  54
  55 Unlike a packaged distribution, the YASM Subversion tree doesn't contain a
  56 configure script nor any of the other generated files normally used in
  57 configuration and building.  You have to regenerate these files in your local
  58 copy before running configure.
  59
  60 Building in this fashion requires many more programs than YASM normally
  61 requires in a packaged distribution.  Programs required:
  62   * automake (1.5 or newer)
  63   * autoconf (2.5 or newer)
  64   * m4
  65   * gettext
  66   * make (GNU preferred)
  67   * Python
  68   * gcc
  69
  70 To rebuild the manpages from the DocBook XML files, the program "xmlto" and
  71 all of its dependencies are required.
  72
  73 To prepare your working copy for building, run:
  74   % ./autogen.sh
  75
  76 The autogen.sh script runs gettextize, aclocal, autoconf, autoheader, automake,
  77 and finally runs "./configure --enable-maintainer-mode".  If an error occurs
  78 during this process, something is wrong in your build configuration (such as
  79 required tools missing or misconfigured).  After autogen.sh completes
  80 successfully, use make to build YASM.  We recommend you use GNU make because
  81 gettext seems to play better with it than with other make tools.  Use the
  82 distcheck target of make to build a package.  If this doesn't complete
  83 successfully, something is wrong in the source tree.  If you caused the
  84 breakage, fix it or ask someone to help you fix it.  If you didn't cause it (it
  85 happens with a new checkout), notify the developers!