JWasm Readme
1. About JWasm
JWasm is intended to be a free Masm-compatible assembler. It supports
16-, 32- and 64-bit code generation and instructions up to AVX.
Various output formats are supported:
format option comment
-----------------------------------------------------------------------
OMF -omf (default) object format, 16- and 32-bit supported
BIN -bin plain binary format (boot sector, BIOS, DOS COM)
COFF -coff MS Win32 object format
WIN64 -win64 MS Win64 object format
MZ -mz DOS native binary format (.EXE)
PE -pe Win32/Win64 PE binary format
ELF32 -elf Linux 32-bit object format
ELF64 -elf64 Linux 64-bit object format
DJGPP -djgpp Djgpp's 32-bit COFF variant (optional).
JWasm is distributed in several packages. Besides the source package
there are some which contain precompiled binaries for Windows, DOS and
Linux. Other OSes like OS/2 and FreeBSD are also supported, but no binary
is supplied, it must be created from the sources.
JWasm has its roots in Open Watcom's Wasm. The source is released under
the Sybase Open Watcom Public License (see license.txt for details).
2. Requirements
- JWASM.EXE, a precompiled Win32 binary, should run on any 32- or 64-bit
Windows.
- JWASMD.EXE, a precompiled DOS binary, runs in DOS 32bit protected-mode.
It requires a 80386 cpu and needs a MS-DOS v5 compatible DOS to run
(FreeDOS v1 will do). Long filenames (LFN) are supported. JWASMD.EXE
won't run on 64-bit Windows.
- JWASMR.EXE is a DOS real-mode program which runs on any x86 cpu.
Similar to JWASMD.EXE it needs a MS-DOS v5 compatible DOS. This version
has some restrictions, to limit the amount of memory the binary will need.
Memory requirements depend on the source which is assembled. The source
itself is not kept in memory, but the symbol table is, and this table
can easily grow to several MBs if huge amounts of equates are defined.
That's why JWASMR.EXE might be unable to assemble large sources.
3. Installation
The precompiled binaries are supplied as a compressed file. The simplest
and best approach to "install" JWasm is to create a directory named JWasm,
copy the compressed file ( i.e. jwasm205w.zip ) into this directory and
"unzip" it. If you want to run JWasm without having to type the full path
name, you'll either have to add the JWasm directory to your PATH
environment variable or to copy the JWasm binary to a directory that's
included in your PATH.
If you want to deinstall JWasm, delete the JWasm directory. If you had
added the directory to your PATH environment variable, remove it from
there.
4. Documentation
JWasm's documentation consists of
- Readme.txt (this file)
- a Manual, which describes the differences to Masm. It may be in
HTML (Manual.html) or Windows HTMLHelp (JWasm.ch*) format.
- History.txt, which describes bugfixes and changes of all JWasm versions.
- License.txt, which is a copy of the Sybase Open Watcom Public License.
5. Samples
The binary packages contain samples in subdirectory SAMPLES.
For output formats other than BIN, MZ or PE, JWasm's output has to be
linked to create an executable binary. The following set of linkers
have been verified to cooperate with JWasm:
Format Linker Comment
-------------------------------------------------------------
OMF Wlink contained in Open Watcom, free, open source
OMF ALink by A. Williams, free
OMF ValX by David Lindauer (Ladsoft), free
OMF OptLink from Digital Mars, free
OMF Link16 the old OMF linker (v5.60) from Microsoft
OMF TLink from Borland
COFF Wlink this linker accepts OMF and COFF modules
COFF MS Link will also accept OMF modules
COFF PoLink supplied with PellesC, free
WIN64 MS Link must be version 7.10 or newer
WIN64 Polink must be version 5 or newer
WIN64 JWlink fork of OW Wlink
ELF32 LD the GNU linker
ELF64 LD the GNU linker
ELF64 JWlink fork of OW Wlink
Note that the name of the MS OMF linker binary is LINK.EXE, identical
to the MS COFF linker name.
6. How to Create the JWasm Binaries
JWasm is written in C. It's virtually C89, but 64-bit integers and
structures/unions as unnamed members of structures/unions must be
supported by the compiler.
The following Makefiles are supplied in the source package:
name tool chain used creates binary for
---------------------------------------------------------------
Makefile Open Watcom v1.8-v1.9 Win32 [, DOS (32-bit)]
OWDOS16.MAK Open Watcom v1.8-v1.9 DOS (16-bit)
OWOS2.MAK Open Watcom v1.8-v1.9 OS/2 (32-bit)
OWLinux.MAK Open Watcom v1.8-v1.9 Linux
OWWinDll.MAK Open Watcom v1.8-v1.9 Win32 (JWasm.dll)
Msvc.MAK VC++ TK 2003/VC++ 2008 EE Win32 [, DOS (32-bit)]
Msvc64.MAK VC++ 2010 Win64
MsvcDll.MAK VC++ TK 2003 Win32 (JWasm.dll)
GccWin.MAK GCC, MinGW/Cygwin Win32
GccWin64.MAK GCC, MinGW-w64 Win64
GccDos.MAK GCC, DJGPP DOS (32-bit)
GccUnix.MAK GCC, FreeBSD/Linux FreeBSD [, Linux]
---------------------------------------------------------------
BCC.MAK Borland C++ Cmdline Tools Win32
OC.MAK Orange C Win32
PCC.MAK PCC Win32
PellesC.MAK Pelles C v7 Win32, Win64
TCC.MAK Tiny C Win32
IntelC32.MAK Intel C++ Compiler, MSVC Win32
IntelC64.MAK Intel C++ Compiler, MSVC Win64
The makefiles that use the OW tool chain are supposed to be run
with Open Watcom's WMake, Msvc*.MAK and IntelC*.MAK should be run with
MS NMAKE, PellesC.MAK expects POMAKE and for Gcc*.MAK GNU make is to be
used.
More detailed information may be found in the makefiles themselves!
Please note that only the binaries created with toolchains Open Watcom,
VC++ and GCC are regularily tested to pass the JWasm regression test.
7. Using JWasm with Visual Studio
a) VS 2005/2008
To integrate JWasm into VS, copy file jwasm.rules to directory
<vc_dir>\VC\VCProjectDefaults. After this is done, JWasm can be
selected as assembler inside the VS IDE.
b) VS 2010/2012
- Unzip file VS2010CustomBuildRule.zip. The result are 3 files,
jwasm.props, jwasm.targets and jwasm.xml.
- Copy those files to MSBUILD's build customization directory.
8. Contributors
These people contributed to JWasm ( additions, bugfixes, bug reports):
agner, BlackVortex, dosfan01, drizz, Paul Edwards, filofel, Peter Flass,
James C. Fuller, gfalen, habran, Japheth, Jimg, jj2007, John Hankinson,
Khusraw, Alex Kozlov, Peter Kuznetsov, misca, Michal Necasek, H. Nidudsson,
Nikitakita, Jose Pascoa, Terry Philips, qWord, RotateRight, Ito Toshimitsu,
Vortex.
Japheth