# Open Watcom tools usage

## Introduction

Open Watcom comes with a very efficient native 16-bit compiler supporting DOS and Win16 targets and a 32-bit x86 compiler targetting many different OSes (NT/Win32, OS/2, NetWare, Linux, ...). A major aim for the v2 development is support for x86_64 and ARM architectures. The most obvious "competitors" of Open Watcom would be the GCC-based Mingw-w64 [for 32 Bit and 64 Bit Win32-targets](https://www.mingw-w64.org/), DJGPP [for 32 Bit DOS targets](http://www.delorie.com/djgpp) and the [ia16 port for 16 Bit DOS targets](https://github.com/tkchia/build-ia16).

## Comparisons to other (cross-)compilers

A striking difference compared to the **binutils**-based compilers (**gcc**, **clang**, **pcc**) when used as a cross compiler is that Open watcom only uses a single compiler (one for each target CPU architecture) and the target OS is determined by a compilation flag (see "cross compiling" below). Further, many OS-independent libraries lives in a generic architecture-specific location (**`$WATCOM/lib286`** and **`$WATCOM/lib386`**) and only libraries with OS-specific features are put into OS-specific sub-directories - this is thanks to the Open Watcom C runtime that is distributed together with the compiler. This means that it is very easy to use a single install of Open Watcom as a cross compiler for a wide range of OSes. In contrast, a cross-compile toolchain based on **binutils** typically requires building a target-specific ["trinity" of binutils, compiler and libc](https://wiki.osdev.org/GCC_Cross-Compiler). Another advantage of Open Watcom as a cross compiler is that the resulting binaries and libraries integrate nicely with the target OS. For example, [Python compiled with Open Watcom](http://lightningpython.org/) can load plugins compiled with **Visual_C++**. This is similar to how the different **binutils**-based compilers (often) can use libraries built with another **binutils**-based compiler. At this moment, the resulting binaries are not as optimized as those made by GCC.

## OW tools description

### 16-bit x86 compilers

- **`wcc :`** the 16-bit "compile only" C compiler
- **`wpp :`** the 16-bit "compile only" C++ compiler
- **`wfc :`** the 16-bit "compile only" Fortran compiler
- **`wcl :`** the 16-bit "compile and link" utility for C/C++
- **`wfl :`** the 16-bit "compile and link" utility for Fortran
- **`owcc:`** the POSIX compatible "compile and link" utility. Set **`CC=owcc`** in a project depending on GNU makefiles.

The 16-bit x86 compilers finds its OS-independent libraries in the **`$WATCOM/lib286`** directory and its OS-dependent libraries in **`$WATCOM/lib286/${target_os}`** sub-directory.
Some OSes might need extra library paths, which can be added by the **`LIBPATH`** environment variable.

### 32-bit x86 compilers

- **`wcc386:`** the 32-bit "compile only" C compiler
- **`wpp386:`** the 32-bit "compile only" C++ compiler
- **`wfc386:`** the 32-bit "compile only" Fortran compiler
- **`wcl386:`** the 32-bit "compile and link" utility for C/C++
- **`wfl386:`** the 32-bit "compile and link" utility for Fortran
- **`owcc  :`** the POSIX compatible "compile and link" utility. Set **`CC=owcc`** in a project depending on GNU makefiles.

The 32-bit x86 compilers finds its OS-independent libraries in the **`$WATCOM/lib386`** directory and its OS-dependent libraries in **`$WATCOM/lib386/${target_os}`** sub-directory.
Some OSes might need extra library paths, which can be added by the **`LIBPATH`** environment variable.

## (Cross-)compilation : Common settings

To cross compile, set the correct environment variables and a compile flag telling the compiler which target is intended.
Without compile flags defining target, a native build is assumed.

By default OW is setup for native compilation `"<compilation target> == <host system>"` that for such compilation no extra setup is necessary.
Following environment variables are setup per `<installation>`.
|Variable|Value|Description|
|---|---|:--|
|WATCOM|`<path>`|where OW installation is located `<OW root>`|
|WIPFC|`<path>`|where wipfc compiler supplementaly files are located `<wipfc subdirectory>`|
|EDPATH|`<path>`|where vi editor script files are located `<eddat subdirectory>`|

Following environment variables are setup per `<host system>`.
|Variable|Value|Description|
|---|---|:--|
|PATH|`<path>`|add to PATH where OW host binaries are located, by example `%WATCOM%\binw` for DOS|

For cross compilation following environment variables must be changed per `<target system>`.
|Variable|Value|Description|
|---|---|:--|
|INCLUDE|`<path>`|where target header files are located, by example `%WATCOM%\h` for DOS|

### DOS 16-bit target

|compiler|target option|
|---|:--|
|wcc|-bt=dos|
|wpp|-bt=dos|
|wfc||
|wcl|-bcl=dos|
|wfl|-l=dos or -lr|
|owcc|-bdos|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h`|

### DOS 32-bit target (with DOS 32-bit Extender)

|compiler|target option|DOS Extender|
|---|:--|:--|
|wcc386|-bt=dos|any|
|wpp386|-bt=dos|any|
|wfc386||any|
|wcl386|-bt=dos -l=dos4g|DOS4GW|
|wcl386|-bt=dos -l=causeway|Causeway|
|wcl386|-bt=dos -l=dos32a|DOS32A|
|wcl386|-bt=dos -l=pmodew|PMODE/W|
|wfl386|-l=dos4g|DOS4GW|
|wfl386|-l=causeway|Causeway|
|wfl386|-l=dos32a|DOS32A|
|wfl386|-l=pmodew|PMODE/W|
|owcc|-bdos4g|DOS4GW|
|owcc|-bcauseway|Causeway|
|owcc|-bdos32a|DOS32A|
|owcc|-bpmodew|PMODE/W|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h`|

### Windows WIN16 16-bit or 32-bit targets

16-bit target
|compiler|target option|
|---|:--|
|wcc|-bt=windows|
|wpp|-bt=windows|
|wfc||
|wcl|-bcl=windows|
|wfl|-l=windows|
|owcc|-bwindows|

32-bit target (with OW 32-bit WIN386 Extender)
|compiler|target option|
|---|:--|
|wcc386|-bt=windows|
|wpp386|-bt=windows|
|wfc386||
|wcl386|-bt=windows -l=win386|
|wfl386|-l=win386|
|owcc|-bwin386|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/h/win`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\h\win`|

### Windows WIN32 target (32-bit) Console Application

|compiler|target option|
|---|:--|
|wcc386|-bt=nt -bc|
|wpp386|-bt=nt -bc|
|wfc386||
|wcl386|-bcl=nt -bc|
|wfl386|-l=nt|
|owcc|-bnt -mconsole|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/h/nt`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\h\nt`|

### Windows WIN32 target (32-bit) Windowed Application

|compiler|target option|
|---|:--|
|wcc386|-bt=nt -bg|
|wpp386|-bt=nt -bg|
|wfc386||
|wcl386|-bt=nt -l=nt_win -bg|
|wfl386|-l=nt|
|owcc|-bnt_win -mwindows|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/h/nt`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\h\nt`|

### Linux target (32-bit only)

|compiler|target option|
|---|:--|
|wcc386|-bt=linux|
|wpp386|-bt=linux|
|wfc386||
|wcl386|-bcl=linux|
|wfl386|-l=linux|
|owcc|-blinux|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/lh`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\lh`|

### OS/2 16-bit target

|compiler|target option|
|---|:--|
|wcc|-bt=os2|
|wpp|-bt=os2|
|wfc||
|wcl|-bcl=os2|
|wfl|-l=os2 or -lp|
|owcc|-bos2|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/h/os21x`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\h\os21x`|

### OS/2 32-bit target

|compiler|target option|
|---|:--|
|wcc386|-bt=os2|
|wpp386|-bt=os2|
|wfc386||
|wcl386|-bt=os2 -l=os2v2|
|wfl386|-l=os2v2|
|owcc|-bos2v2|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/h/os2`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\h\os2`|

### Netware target (32-bit)

|compiler|target option|
|---|:--|
|wcc386|-bt=netware|
|wpp386|-bt=netware|
|wfc386||
|wcl386|-bcl=netware|
|wfl386|-l=netware|
|owcc|-bnetware|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/h:$WATCOM/novh`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\h;%WATCOM%\novh`|

Some packages may need a [proprietary set of libraries and headers from Novell](https://archive.today/2014.10.17-203728/http://www.novell.com/coolsolutions/trench/411.html).

### RDOS target (32-bit)

|compiler|target option|
|---|:--|
|wcc386|-bt=rdos|
|wpp386|-bt=rdos|
|wfc386||
|wcl386|-bcl=rdos|
|wfl386|-l=rdos|
|owcc|-brdos|

|Variable|host OS|Value|
|---|---|:--|
|INCLUDE|Linux, macOS|`$WATCOM/rh`|
|INCLUDE|DOS, Windows, OS/2, ...|`%WATCOM%\rh`|
