Readme

   1 This is a distribution of NASM, the Netwide Assembler. NASM is a
   2 prototype general-purpose x86 assembler. It will currently output
   3 flat-form binary files, a.out, COFF and ELF Unix object files,
   4 Microsoft Win32 and 16-bit DOS object files, OS/2 object files, the
   5 as86 object format, and a home-grown format called RDF.
   6
   7 Also included is NDISASM, a prototype x86 binary-file disassembler
   8 which uses the same instruction table as NASM.
   9
  10 To install NASM on Linux, type `make', and then when it has finished
  11 copy the file `nasm' (and maybe `ndisasm') to a directory on your
  12 search path (maybe /usr/local/bin, or ~/bin if you don't have root
  13 access). You may also want to copy the man page `nasm.1' (and maybe
  14 `ndisasm.1') to somewhere sensible.
  15
  16 To install under DOS, if you don't need to rebuild from the sources,
  17 you can just copy nasm.exe and ndisasm.exe (16-bit DOS executables),
  18 or nasmw.exe and ndisasmw.exe (Win32 console applications - less
  19 likely to run out of memory), to somewhere on your PATH.
  20
  21 To rebuild the DOS sources, various makefiles are provided:
  22
  23 - Makefile.dos, the one I build the standard 16-bit releases from,
  24   designed for a hybrid system using Microsoft C and Borland Make
  25   (don't ask why :-)
  26 - Makefile.vc, for Microsoft Visual C++ compiling to a Win32
  27   command-line application. This is the one I build the standard
  28   Win32 release binaries from.
  29
  30 - Makefile.bor, for Borland C.
  31 - Makefile.bc2, also for Borland C, contributed by Fox Cutter.
  32   Reported to work better than Makefile.bor on some systems.
  33
  34 - Makefile.sc, for Symantec C++, compiling to a 32-bit extended DOS
  35   executable.. Contributed by Mark Junker.
  36 - Makefile.scw, also for Symantec C++, compiling to a Win32 command-
  37   line application. Also contributed by Mark Junker.
  38
  39 - Makefile.wc, for Watcom C, compiling to a 32-bit extended DOS
  40   executable. Contributed by Dominik Behr.
  41 - Makefile.wcw, also for Watcom C, compiling to a Win32 command-
  42   line application. Also contributed by Dominik Behr.
  43
  44 - Makefile.dj, for DJGPP, compiling to a 32-bit extended DOS
  45   executable. Contributed by Dominik Behr.
  46
  47 - Makefile.lcc, for lcc-win32, compiling to a Win32 command line
  48   application. (The lcc-win32 compiler and tools are available from
  49   http://www.remcomp.com/lcc-win32/)
  50
  51 I can't guarantee that all of those makefiles work, because I don't
  52 have all of those compilers. However, Makefile.dos and Makefile.vc
  53 work on my system, and so do Makefile.bor and Makefile.bc2.
  54
  55 Be careful with Borland C: there have been various conflicting
  56 reports about how reliable the Huge memory model is. If you try to
  57 compile NASM in Large model, you may get DGROUP overflows due to the
  58 vast quantity of data in the instruction tables. I've had reports
  59 from some people that Huge model doesn't work at all (and also
  60 reports from others that it works fine), so if you don't want to try
  61 moving to Huge, you could try adding the option `-dc' to the
  62 compiler command line instead, which causes string literals to be
  63 moved from DGROUP to the code segments and might make Large model
  64 start working. (Either solution works for me.)
  65
  66 Dominik Behr has also contributed the file misc/pmw.bat, which is a
  67 batch file to turn the output from Makefile.wc (NASM.EXE and
  68 NDISASM.EXE) into standalone executables incorporating Tran's
  69 PMODE/W DOS extender, rather than depending on an external extender
  70 program.
  71
  72 Some of the Windows makefiles produce executables called nasmw.exe
  73 and ndisasmw.exe, and some don't. Be prepared for either...
  74
  75 If you're trying to unpack the DOS (.ZIP format) archive under Unix
  76 instead of using the .tar.gz version, you can save some time by
  77 doing `unzip -aL', which will convert the DOS-format text files to
  78 Unix and also convert all names to lower case.
  79
  80 If you want to build a restricted version of NASM containing only
  81 some of the object file formats, you can achieve this by adding
  82 #defines to `outform.h' (see the file itself for documentation), or
  83 equivalently by adding compiler command line options in the
  84 Makefile.
  85
  86 There is a machine description file for the `LCC' retargetable C
  87 compiler (version 3.6), in the directory `lcc', along with
  88 instructions for its use. This means that NASM can now be used as
  89 the code-generator back end for a useful C compiler.
  90
  91 Michael `Wuschel' Tippach has ported his DOS extender `WDOSX' to
  92 enable it to work with the 32-bit binary files NASM can output: the
  93 original extender and his port `WDOSX/N' are available from his web
  94 page, http://www.geocities.com/SiliconValley/Park/4493.
  95
  96 Matt Mastracci has written a document explaining how to write
  97 assembly language modules in DJGPP programs using NASM: it's on his
  98 web site at http://www.ucalgary.ca/~mmastrac/djgppasm.doc.
  99
 100 The `misc' directory contains `nasm.sl', a NASM editing mode for the
 101 JED programmers' editor (see http://space.mit.edu/~davis/jed.html
 102 for details about JED). The comment at the start of the file gives
 103 instructions on how to install the mode. This directory also
 104 contains a file (`magic') containing lines to add to /etc/magic on
 105 Unix systems to allow the `file' command to recognise RDF files, and
 106 a zip file (`exasm.zip') containing the necessary files for syntax
 107 highlighting in the Aurora DOS editor. (The Aurora files were
 108 contributed by <U993847220@aol.com>; I haven't tested them as I
 109 don't have Aurora.)
 110
 111 The `rdoff' directory contains sources for a linker and loader for
 112 the RDF object file format, to run under Linux, and also
 113 documentation on the internal structure of RDF files.
 114
 115 For information about how you can distribute and use NASM, see the
 116 file Licence. We were tempted to put NASM under the GPL, but decided
 117 that in many ways it was too restrictive for developers.
 118
 119 For information about how to use NASM, see the various forms of
 120 documentation in the `doc' directory: documentation is provided in
 121 HTML, PostScript, plain text, Texinfo, and Windows Help formats. For
 122 information about how to use NDISASM, see `ndisasm.doc'. For
 123 information about the internal structure of NASM, see
 124 `internal.doc'. (In particular, _please_ read `internal.doc' before
 125 writing any code for us...)
 126
 127 The NASM web page is at http://www.cryogen.com/Nasm/
 128
 129 Bug reports (and patches if you can) should be sent to
 130 <jules@earthcorp.com> or <anakin@pobox.com>.