| $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 deisgn 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 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 (1.5 or newer) |
| * autoconf (2.5 or newer preferred, 2.13 will still work) |
| * m4 |
| * gettext |
| * make (GNU preferred) |
| * flex |
| * 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-dev". 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. |
