The Netwide Assembler: NASM

Next Chapter | Previous Chapter | Contents | Index

Chapter 2: Running NASM

2.1 NASM Command-Line Syntax

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

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

For example, 

nasm -f elf myfile.asm

will assemble myfile.asm into an ELF object file myfile.o. And 

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

will assemble myfile.asm into a raw binary file myfile.com.

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

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

To get further usage instructions from NASM, try typing 

nasm -h

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 a.out or ELF, type 

file nasm

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

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

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

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

or something similar, your system is a.out, and you should use -f aout instead (Linux a.out systems are considered 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.

2.1.1 The -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 (obj and win32), it will remove the .asm extension (or whatever extension you like to use - NASM doesn't care) from your source file name and substitute .obj. For Unix object file formatsdesigned to be a back end to gcc, which always feeds it correct code. So its error checking is minimal. Also, its syntax is horrible, from the point of view of anyone trying to actually write anything in it. Plus you can't write 16-bit code in it (properly).

  • as86 is Linux-specific, and (my version at least) doesn't seem to have much (or any) documentation.
  • MASM isn't very good, and it's expensive, and it runs only under DOS.
  • TASM is better, but still strives for MASM compatibility, which means millions of directives and tons of red tape. And its syntax is essentially MASM's, with the contradictions and quirks that entails (although it sorts out some of those by means of Ideal mode). It's expensive too. And it's DOS-only.

    So here, for your coding pleasure, is NASM. At present it's still in prototype stage - we don't promise that it can outperform any of these assemblers. But please, please send us bug reports, fixes, helpful information, and anything else you can get your hands on (and thanks to the many people who've done this already! You all know who you are), and we'll improve it out of all recognition. Again.

    1.1.2 Licence Conditions

    Please see the file Licence, supplied as part of any NASM distribution archive, for the licence conditions under which you may use NASM.

    1.2 Contact Information

    The current version of NASM (since about 0.98.08) are maintained by a team of developers, accessible through the nasm-devel mailing list (see below for the link). If you want to report a bug, please read section 10.2 first.

    NASM has a WWW page at http://www.web-sites.co.uk/nasm.

    The original authors are e-mailable as jules@dsf.org.uk and anakin@pobox.com. The latter is no longer involved in the development team.

    New releases of NASM are uploaded to the official site http://www.web-sites.co.uk/nasm, and to ftp.kernel.org and ibiblio.org.

    Announcements are posted to comp.lang.asm.x86, alt.lang.asm and comp.os.linux.announce

    If you want information about NASM beta releases, and the current development status, please subscribe to the nasm-devel email lists by registering at http://groups.yahoo.com/group/nasm-devel and http://www.pairlist.net/mailman/listinfo/nasm-devel

    1.3 Installation

    1.3.1 Installing NASM under MS-DOS or Windows

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

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

    The only file NASM needs to run is its own executable, so copy (at least) one of nasm.exe and nasmw.exe to a directory on your PATH, or alternatively edit autoexec.bat to add the nasm directory to your PATH. (If you're only installing the Win32 version, you may wish to rename it to 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 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 DOS source archive, nasmXXXs.zip, the nasm directory will also contain the full NASM source code, and a selection of Makefiles you can (hopefully) use to rebuild your copy of NASM from scratch.

    Note that the source files insnsa.c, insnsd.c, insnsi.h and insnsn.c are automatically generated from the master instruction table insns.dat by a Perl script; the file macros.c is generated from standard.mac by another Perl script. Although the NASM 0.98 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 Perl for a variety of platforms, including DOS and Windows, are available from www.cpan.org.

    1.3.2 Installing NASM under Unix

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

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

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

    NASM also comes with a set of utilities for handling the RDOFF custom object-file format, which are in the rdoff subdirectory of the NASM archive. You can build these with make rdf and install them with 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 Makefile.unx. Copy or rename that file to Makefile and try typing make. There is also a Makefile.unx file in the rdoff subdirectory.

    Next Chapter | Contents | Index ./usr/share/doc/nasm/html/nasmdoc2.html0100644000000000000000000006756310165036653016716 0ustar rootrootNASM Manual

    The Netwide Assembler: NASM

    Next Chapter | Previous Chapter | Contents | Index

    Chapter 2: Running NASM

    2.1 NASM Command-Line Syntax

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

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

    For example, 

    nasm -f elf myfile.asm

    will assemble myfile.asm into an ELF object file myfile.o. And 

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

    will assemble myfile.asm into a raw binary file myfile.com.

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

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

    To get further usage instructions from NASM, try typing 

    nasm -h

    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 a.out or ELF, type 

    file nasm

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

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

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

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

    or something similar, your system is a.out, and you should use -f aout instead (Linux a.out systems are considered 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.

    2.1.1 The -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 (obj and win32), it will remove the .asm extension (or whatever extension you like to use - NASM doesn't care) from your source file name and substitute .obj. For Unix object file formatsdesigned to be a back end to gcc, which always feeds it correct code. So its error checking is minimal. Also, its syntax is horrible, from the point of view of anyone trying to actually write anything in it. Plus you can't write 16-bit code in it (properly).

  • as86 is Linux-specific, and (my version at least) doesn't seem to have much (or any) documentation.
  • MASM isn't very good, and it's expensive, and it runs only under DOS.
  • TASM is better, but still strives for MASM compatibility, which means millions of directives and tons of red tape. And its syntax is essentially MASM's, with the contradictions and quirks that entails (although it sorts out some of those by means of Ideal mode). It's expensive too. And it's DOS-only.

    So here, for your coding pleasure, is NASM. At present it's still in prototype stage - we don't promise that it can outperform any of these assemblers. But please, please send us bug reports, fixes, helpful information, and anything else you can get your hands on (and thanks to the many people who've done this already! You all know who you are), and we'll improve it out of all recognition. Again.

    1.1.2 Licence Conditions

    Please see the file Licence, supplied as part of any NASM distribution archive, for the licence conditions under which you may use NASM.

    1.2 Contact Information

    The current version of NASM (since about 0.98.08) are maintained by a team of developers, accessible through the nasm-devel mailing list (see below for the link). If you want to report a bug, please read section 10.2 first.

    NASM has a WWW page at http://www.web-sites.co.uk/nasm.

    The original authors are e-mailable as jules@dsf.org.uk and anakin@pobox.com. The latter is no longer involved in the development team.

    New releases of NASM are uploaded to the official site http://www.web-sites.co.uk/nasm, and to ftp.kernel.org and ibiblio.org.

    Announcements are posted to comp.lang.asm.x86, alt.lang.asm and comp.os.linux.announce

    If you want information about NASM beta releases, and the current development status, please subscribe to the nasm-devel email lists by registering at http://groups.yahoo.com/group/nasm-devel and http://www.pairlist.net/mailman/listinfo/nasm-devel

    1.3 Installation

    1.3.1 Installing NASM under MS-DOS or Windows

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

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

    The only file NASM needs to run is its own executable, so copy (at least) one of nasm.exe and nasmw.exe to a directory on your PATH, or alternatively edit autoexec.bat to add the nasm directory to your PATH. (If you're only installing the Win32 version, you may wish to rename it to 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 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 DOS source archive, nasmXXXs.zip, the nasm directory will also contain the full NASM source code, and a selection of Makefiles you can (hopefully) use to rebuild your copy of NASM from scratch.

    Note that the source files insnsa.c, insnsd.c, insnsi.h and insnsn.c are automatically generated from the master instruction table insns.dat by a Perl script; the file macros.c is generated from standard.mac by another Perl script. Although the NASM 0.98 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 Perl for a variety of platforms, including DOS and Windows, are available from www.cpan.org.

    1.3.2 Installing NASM under Unix

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

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

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

    NASM also comes with a set of utilities for handling the RDOFF custom object-file format, which are in the rdoff subdirectory of the NASM archive. You can build these with make rdf and install them with 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 Makefile.unx. Copy or rename that file to Makefile and try typing make. There is also a Makefile.unx file in the rdoff subdirectory.

    Next Chapter | Contents | Index ./usr/share/doc/nasm/html/nasmdoc2.html0100644000000000000000000006756310165036653016716 0ustar rootrootNASM Manual

    The Netwide Assembler: NASM

    Next Chapter | Previous Chapter | Contents | Index

    Chapter 2: Running NASM

    2.1 NASM Command-Line Syntax

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

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

    For example, 

    nasm -f elf myfile.asm

    will assemble myfile.asm into an ELF object file myfile.o. And 

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

    will assemble myfile.asm into a raw binary file myfile.com.

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

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

    To get further usage instructions from NASM, try typing 

    nasm -h

    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 a.out or ELF, type 

    file nasm

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

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

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

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

    or something similar, your system is a.out, and you should use -f aout instead (Linux a.out systems are considered 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.

    2.1.1 The -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 (obj and win32), it will remove the .asm extension (or whatever extension you like to use - NASM doesn't care) from your source file name and substitute .obj. For Unix object file formatsdesigned to be a back end to gcc, which always feeds it correct code. So its error checking is minimal. Also, its syntax is horrible, from the point of view of anyone trying to actually write anything in it. Plus you can't write 16-bit code in it (properly).

  • as86 is Linux-specific, and (my version at least) doesn't seem to have much (or any) documentation.
  • MASM isn't very good, and it's expensive, and it runs only under DOS.
  • TASM is better, but still strives for MASM compatibility, which means millions of directives and tons of red tape. And its syntax is essentially MASM's, with the contradictions and quirks that entails (although it sorts out some of those by means of Ideal mode). It's expensive too. And it's DOS-only.

    So here, for your coding pleasure, is NASM. At present it's still in prototype stage - we don't promise that it can outperform any of these assemblers. But please, please send us bug reports, fixes, helpful info