nasmdoc.src

nasm的全套源代码,有些我做了些修改,以方便您更方便更容易调试成功,方便学习做编译器

Once you've obtained the \i{DOS archive} for NASM, \i\c{nasmXXX.zip}
(where \c{XXX} denotes the version number of NASM contained in the
archive), unpack it into its own directory (for example \c{c:\\nasm}).

The archive will contain four executable files: the NASM executable
files \i\c{nasm.exe} and \i\c{nasmw.exe}, and the NDISASM executable
files \i\c{ndisasm.exe} and \i\c{ndisasmw.exe}. In each case, the
file whose name ends in \c{w} is a \I{Win32}\c{Win32} executable,
designed to run under \I{Windows 95}\c{Windows 95} or \I{Windows NT}
\c{Windows NT} Intel, and the other one is a 16-bit \I{DOS}\c{DOS}
executable.

The only file NASM needs to run is its own executable, so copy
(at least) one of \c{nasm.exe} and \c{nasmw.exe} to a directory on
your PATH, or alternatively edit \i\c{autoexec.bat} to add the
\c{nasm} directory to your \i\c{PATH}. (If you're only installing the
\c{Win32} version, you may wish to rename it to \c{nasm.exe}.)

That's it - NASM is installed. You don't need the nasm directory
to be present to run NASM (unless you've added it to your \c{PATH}),
so you can delete it if you need to save space; however, you may
want to keep the documentation or test programs.

If you've downloaded the \i{DOS source archive}, \i\c{nasmXXXs.zip},
the \c{nasm} directory will also contain the full NASM \i{source
code}, and a selection of \i{Makefiles} you can (hopefully) use to
rebuild your copy of NASM from scratch.

Note that the source files \c{insnsa.c}, \c{insnsd.c}, \c{insnsi.h}
and \c{insnsn.c} are automatically generated from the master
instruction table \c{insns.dat} by a Perl script; the file
\c{macros.c} is generated from \c{standard.mac} by another Perl
script. Although the NASM source distribution includes these generated
files, you will need to rebuild them (and hence, will need a Perl
interpreter) if you change insns.dat, standard.mac or the
documentation. It is possible future source distributions may not
include these files at all. Ports of \i{Perl} for a variety of
platforms, including DOS and Windows, are available from
\W{http://www.cpan.org/ports/}\i{www.cpan.org}.


\S{instdos} Installing NASM under \i{Unix}

Once you've obtained the \i{Unix source archive} for NASM,
\i\c{nasm-X.XX.tar.gz} (where \c{X.XX} denotes the version number of
NASM contained in the archive), unpack it into a directory such
as \c{/usr/local/src}. The archive, when unpacked, will create its
own subdirectory \c{nasm-X.XX}.

NASM is an \I{Autoconf}\I\c{configure}auto-configuring package: once
you've unpacked it, \c{cd} to the directory it's been unpacked into
and type \c{./configure}. This shell script will find the best C
compiler to use for building NASM and set up \i{Makefiles}
accordingly.

Once NASM has auto-configured, you can type \i\c{make} to build the
\c{nasm} and \c{ndisasm} binaries, and then \c{make install} to
install them in \c{/usr/local/bin} and install the \i{man pages}
\i\c{nasm.1} and \i\c{ndisasm.1} in \c{/usr/local/man/man1}.
Alternatively, you can give options such as \c{--prefix} to the
configure script (see the file \i\c{INSTALL} for more details), or
install the programs yourself.

NASM also comes with a set of utilities for handling the \c{RDOFF}
custom object-file format, which are in the \i\c{rdoff} subdirectory
of the NASM archive. You can build these with \c{make rdf} and
install them with \c{make rdf_install}, if you want them.

If NASM fails to auto-configure, you may still be able to make it
compile by using the fall-back Unix makefile \i\c{Makefile.unx}.
Copy or rename that file to \c{Makefile} and try typing \c{make}.
There is also a Makefile.unx file in the \c{rdoff} subdirectory.


\C{running} Running NASM

\H{syntax} NASM \i{Command-Line} Syntax

To assemble a file, you issue a command of the form

\c nasm -f <format> <filename> [-o <output>]

For example,

\c nasm -f elf myfile.asm

will assemble \c{myfile.asm} into an \c{ELF} object file \c{myfile.o}. And

\c nasm -f bin myfile.asm -o myfile.com

will assemble \c{myfile.asm} into a raw binary file \c{myfile.com}.

To produce a listing file, with the hex codes output from NASM
displayed on the left of the original sources, use the \c{-l} option
to give a listing file name, for example:

\c nasm -f coff myfile.asm -l myfile.lst

To get further usage instructions from NASM, try typing

\c nasm -h

As \c{-hf}, this will also list the available output file formats, and what they
are.

If you use Linux but aren't sure whether your system is \c{a.out}
or \c{ELF}, type

\c file nasm

(in the directory in which you put the NASM binary when you
installed it). If it says something like

\c nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1

then your system is \c{ELF}, and you should use the option \c{-f elf}
when you want NASM to produce Linux object files. If it says

\c nasm: Linux/i386 demand-paged executable (QMAGIC)

or something similar, your system is \c{a.out}, and you should use
\c{-f aout} instead (Linux \c{a.out} systems have long been obsolete,
and are rare these days.)

Like Unix compilers and assemblers, NASM is silent unless it
goes wrong: you won't see any output at all, unless it gives error
messages.


\S{opt-o} The \i\c{-o} Option: Specifying the Output File Name

NASM will normally choose the name of your output file for you;
precisely how it does this is dependent on the object file format.
For Microsoft object file formats (\i\c{obj} and \i\c{win32}), it
will remove the \c{.asm} \i{extension} (or whatever extension you
like to use - NASM doesn't care) from your source file name and
substitute \c{.obj}. For Unix object file formats (\i\c{aout},
\i\c{coff}, \i\c{elf} and \i\c{as86}) it will substitute \c{.o}. For
\i\c{rdf}, it will use \c{.rdf}, and for the \i\c{bin} format it
will simply remove the extension, so that \c{myfile.asm} produces
the output file \c{myfile}.

If the output file already exists, NASM will overwrite it, unless it
has the same name as the input file, in which case it will give a
warning and use \i\c{nasm.out} as the output file name instead.

For situations in which this behaviour is unacceptable, NASM
provides the \c{-o} command-line option, which allows you to specify
your desired output file name. You invoke \c{-o} by following it
with the name you wish for the output file, either with or without
an intervening space. For example:

\c nasm -f bin program.asm -o program.com
\c nasm -f bin driver.asm -odriver.sys

Note that this is a small o, and is different from a capital O , which
is used to specify the number of optimisation passes required. See \k{opt-On}.


\S{opt-f} The \i\c{-f} Option: Specifying the \i{Output File Format}

If you do not supply the \c{-f} option to NASM, it will choose an
output file format for you itself. In the distribution versions of
NASM, the default is always \i\c{bin}; if you've compiled your own
copy of NASM, you can redefine \i\c{OF_DEFAULT} at compile time and
choose what you want the default to be.

Like \c{-o}, the intervening space between \c{-f} and the output
file format is optional; so \c{-f elf} and \c{-felf} are both valid.

A complete list of the available output file formats can be given by
issuing the command \i\c{nasm -hf}.


\S{opt-l} The \i\c{-l} Option: Generating a \i{Listing File}

If you supply the \c{-l} option to NASM, followed (with the usual
optional space) by a file name, NASM will generate a
\i{source-listing file} for you, in which addresses and generated
code are listed on the left, and the actual source code, with
expansions of multi-line macros (except those which specifically
request no expansion in source listings: see \k{nolist}) on the
right. For example:

\c nasm -f elf myfile.asm -l myfile.lst

If a list file is selected, you may turn off listing for a 
section of your source with \c{[list -]}, and turn it back on
with \c{[list +]}, (the default, obviously). There is no "user 
form" (without the brackets). This can be used to list only 
sections of interest, avoiding excessively long listings.


\S{opt-M} The \i\c{-M} Option: Generate \i{Makefile Dependencies}.

This option can be used to generate makefile dependencies on stdout.
This can be redirected to a file for further processing. For example:

\c NASM -M myfile.asm > myfile.dep


\S{opt-F} The \i\c{-F} Option: Selecting a \i{Debug Information Format}

This option is used to select the format of the debug information emitted 
into the output file, to be used by a debugger (or \e{will} be). Use
of this switch does \e{not} enable output of the selected debug info format.
Use \c{-g}, see \k{opt-g}, to enable output.

A complete list of the available debug file formats for an output format
can be seen by issuing the command \i\c{nasm -f <format> -y}. (only 
"borland" in "-f obj", as of 0.98.35, but "watch this space") 
See: \k{opt-y}.

This should not be confused with the "-f dbg" output format option which 
is not built into NASM by default. For information on how
to enable it when building from the sources, see \k{dbgfmt}


\S{opt-g} The \i\c{-g} Option: Enabling \i{Debug Information}.

This option can be used to generate debugging information in the specified
format. See: \k{opt-F}. Using \c{-g} without \c{-F} results in emitting 
debug info in the default format, if any, for the selected output format.
If no debug information is currently implemented in the selected output 
format, \c{-g} is \e{silently ignored}.


\S{opt-X} The \i\c{-X} Option: Selecting an \i{Error Reporting Format}

This option can be used to select an error reporting format for any 
error messages that might be produced by NASM.

Currently, two error reporting formats may be selected.  They are
the \c{-Xvc} option and the \c{-Xgnu} option.  The GNU format is 
the default and looks like this:

\c filename.asm:65: error: specific error message 

where \c{filename.asm} is the name of the source file in which the
error was detected, \c{65} is the source file line number on which 
the error was detected, \c{error} is the severity of the error (this
could be \c{warning}), and \c{specific error message} is a more
detailed text message which should help pinpoint the exact problem.

The other format, specified by \c{-Xvc} is the style used by Microsoft
Visual C++ and some other programs.  It looks like this:

\c filename.asm(65) : error: specific error message

where the only difference is that the line number is in parentheses
instead of being delimited by colons.  

See also the \c{Visual C++} output format, \k{win32fmt}.

\S{opt-E} The \i\c{-E} Option: Send Errors to a File

Under \I{DOS}\c{MS-DOS} it can be difficult (though there are ways) to
redirect the standard-error output of a program to a file. Since
NASM usually produces its warning and \i{error messages} on
\i\c{stderr}, this can make it hard to capture the errors if (for
example) you want to load them into an editor.

NASM therefore provides the \c{-E} option, taking a filename argument
which causes errors to be sent to the specified files rather than
standard error. Therefore you can \I{redirecting errors}redirect
the errors into a file by typing

\c nasm -E myfile.err -f obj myfile.asm


\S{opt-s} The \i\c{-s} Option: Send Errors to \i\c{stdout}

The \c{-s} option redirects \i{error messages} to \c{stdout} rather
than \c{stderr}, so it can be redirected under \I{DOS}\c{MS-DOS}. To
assemble the file \c{myfile.asm} and pipe its output to the \c{more}
program, you can type:

\c nasm -s -f obj myfile.asm | more

See also the \c{-E} option, \k{opt-E}.


\S{opt-i} The \i\c{-i}\I\c{-I} Option: Include File Search Directories

When NASM sees the \i\c{%include} or \i\c{incbin} directive in 
a source file (see \k{include} or \k{incbin}), 
it will search for the given file not only in the
current directory, but also in any directories specified on the
command line by the use of the \c{-i} option. Therefore you can
include files from a \i{macro library}, for example, by typing

\c nasm -ic:\macrolib\ -f obj myfile.asm

(As usual, a space between \c{-i} and the path name is allowed, and
optional).

NASM, in the interests of complete source-code portability, does not
understand the file naming conventions of the OS it is running on;
the string you provide as an argument to the \c{-i} option will be
prepended exactly as written to the name of the include file.
Therefore the trailing backslash in the above example is necessary.
Under Unix, a trailing forward slash is similarly necessary.

(You can use this to your advantage, if you're really \i{perverse},
by noting that the option \c{-ifoo} will cause \c{%include "bar.i"}
to search for the file \c{foobar.i}...)

If you want to define a \e{standard} \i{include search path},
similar to \c{/usr/include} on Unix systems, you should place one or
more \c{-i} directives in the \c{NASMENV} environment variable (see
\k{nasmenv}).

For Makefile compatibility with many C compilers, this option can also
be specified as \c{-I}.