| $Id$ |
| |
| 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! |