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.

        JWasm is distributed in several packages. Besides the source package
        there are some containing precompiled binaries for Windows and DOS.
        For other OSes the binary 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).

        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

        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 should do). Long filenames (LFN) are supported. JWasmD won't
          run on 64-bit Windows.

        - JWasmR.exe is a DOS real-mode program which runs on any x86 cpu.
          Similar to JWasmD 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 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, describes bugfixes and changes of all JWasm versions.
        - License.txt, that's 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
        ---------------------------------------------------------------
        OWWin32.mak  Open Watcom v1.8-v2.0         Win32 [, DOS (32-bit)]
        OWDOS32.mak  Open Watcom v2.0              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++ 2003-2019                Win32 [, DOS (32-bit)]
        Msvc64.mak   VC++ 2019                     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, Linux/FreeBSD            Linux, FreeBSD
        CLUnix.mak   CLang, Linux                  Linux
        CLWin.mak    CLang, Win32                  Win32
        ---------------------------------------------------------------
        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