# Porting OpenWatcom

<details><summary>Table of Contents</summary>

* [1 What we have](#what-we-have)
* [2 Port existing Projects to use OpenWatcom](#port-existing-projects-to-use-openWatcom)
* [3 Port existing Projects to use OpenWatcom as cross compiler](#port-existing-projects-to-use-openWatcom-as-cross-compiler)
* [4 Porting OpenWatcom to run on a known OS and cross compile for a known Architecture](#porting-openwatcom-to-run-on-a-known-os-and-cross-compile-for-a-known-architecture)
* [5 Porting OpenWatcom to cross compile for a different OS with a known Architecture](#porting-openwatcom-to-cross-compile-for-a-different-os-with-a-known-architecture)
* [6 Porting OpenWatcom to [cross] compile for a known OS with a new Architecture](#porting-openwatcom-to-cross-compile-for-a-known-os-with-a-new-architecture)
* [7 Suggestions to port OpenWatcom to a new Platform](#suggestions-to-port-openwatcom-to-a-new-platform)
</details>

OpenWatcom has a long History. The commandline options differ from other compiler toolchains.<br>
In addition, the supported language standards are old.

## What we have
* Building OpenWatcom is only supported on:
  * x86: DOS (with a 32 bit DOS Extender)
  * x86 and x86_64: Windows
  * x86 and x86_64: Linux
  * x86: OS/2


* OpenWatcom runs on various Architecture / OS combinations and can<br>
  compile / cross compile for all supported Architecture / OS combinations:
  * DOS (with a 32 bit DOS Extender)
  * Windows (32 bit x86 and 64 bit x86_64)
  * Linux (32 bit x86 and 64 bit x86_64)
  * OS/2 (32 bit x86)
  * RDOS (32 bit x86)

* OpenWatcom supports various Languages:
  * Assembler (Support for newer Processor instruction set extensions unknown)
  * C ([`C99 support`](https://github.com/open-watcom/open-watcom-v2/wiki/C99-Compliance) incomplete)
  * [`C++`](https://github.com/open-watcom/open-watcom-v2/wiki/C++-Project) (C++98: Language and Library incomplete)
  * Fortran (F77 status unknown)

* OpenWatcom can build Programs/libraries for various Processor Architectures:
  * 16 bit x86 Family (8088, 80286)
  * 32 bit x86 Family (i386, i486, i586, i686)
  * 32 bit Alpha/AXP
  * 32 bit Mips (R3000)
  * 32 bit PowerPC

* OpenWatcom can compile / cross compile for various Architecture / OS combinations:
  * 16 bit DOS
  * 16 bit Windows (x86)
  * 16 bit OS/2 (x86)
  * 32 bit DOS
  * 32 bit Windows (x86)
  * 32 bit Linux (x86)
  * 32 bit OS/2 (x86)
  * 32 bit RDOS (x86)
  * 32 bit Netware (x86) (Needs Netware SDK)

* OpenWatcom should be able to cross compile for more Architecture / OS combinations,<br>
  but the needed libraries are not build by default and they are incomplete.
  * 32 bit Windows NT (Alpha)
  * 32 bit Windows NT (Mips)
  * 32 bit Windows NT (PowerPC)
  * 32 bit Linux (Alpha)
  * 32 bit Linux (Mips)
  * 32 bit Linux (PowerPC)

* OpenWatcom has code for more Architecture / OS combinations,<br>
  but support is incomplete. Needed includes/libraries are incomplete or missing.
  * Read the source in `bld/`<br>
   (Hints: _HAIKU, _BSD / _NETBSD / _FREEBSD , _OSX / _APPLE, _QNX, _SOLARIS / _SUN)<br>

---
## Port existing Projects to use OpenWatcom

The POSIX style command line driver `owcc` works for simple tasks.<br>
In addition to set the compiler, it is sometimes useful to use the flag `-v` for `owcc` 
(print commandline parameter for the subtasks).<br>
Many OpenWatcom programs support an environment variable for additional parameter (Read the docs).

Example for a C Autotools Project.
```
CC=owcc CFLAGS="-v" configure
                    make
```
Example for a C++ Autotools Project.
```
CXX=owcc CXXFLAGS="-v" configure
                       make
```
You probably also want to use `-std=c99` for `owcc` to activate the incomplete [`C99 support`](https://github.com/open-watcom/open-watcom-v2/wiki/C99-Compliance) in OpenWatcom.

Or force all C compiler to activate the incomplete `C99` support:
```
export WCC=" -zastd=c99 "
export WCC386=" -zastd=c99 "
export WCCMPS=" -zastd=c99 "
export WCCPPC=" -zastd=c99 "
export WCCAXP=" -zastd=c99 "
```
`-aa` activates an additional C99 feature


### Things, which needs attention
* OpenWatcom uses different commandline parameter <br>
  - Projects activate Multithreading support with `-pthread` (or -Wpthread)<br>
    `owcc` need `-mthreads` here
  - Projects activate additional warnings with `-Wextra` (or the old variant: `-W`)<br>
    Not supported by `owcc`
  - Projects activate extensive warnings with `-pedantic`<br>
    Not supported by `owcc`: Remove this option
  - Projects activate a specific memory model for DOS targets (ia16-gcc) with `-mcmodel`<br>
   `owcc` supports `-mcmodel`, but with different arguments

* OpenWatcom has different Predefined Macros (but you can use the `-D` commandline option)
  -  Projects expect `__unix__` or `__linux__` (or the variants with fewer underscore).<br>
     OpenWatcom defines `__UNIX__` and `__LINUX__`
  -  Projects expect `__i386__` or `__i686__`  (or the variants with fewer underscore).<br>
     OpenWatcom defines `__386__` and `_M_IX86` (and others)
  -  Projects expect `_REENTRANT`, when multithreading is activated with `-pthread`.<br>
     OpenWatcom defines `_MT`, when multithreading is activated with `-mthreads`

---
## Port existing Projects to use OpenWatcom as cross compiler

Autotools projects do not detect `owcc` as cross compiler.<br>
Some simple shell scripts can help:

i686-win32-owcc
```
#!/bin/sh
owcc -march=i386 -mtune=i686 -bwin32 -I$WATCOM/h -I$WATCOM/h/nt  ${1+"$@"}
```

i686-linux-owcc
```
#!/bin/sh
owcc -march=i386 -mtune=i686 -blinux -I$WATCOM/lh  ${1+"$@"}
```

---
## Porting OpenWatcom to run on a known OS and cross compile for a known Architecture
* Run on x86_64 Windows (Supported, completation status unknown)
* Run on x86_64 Linux (Supported, GUI-Tools are missing, completation status unknown)
* Cross compile for Windows NT/Mips (Some patches committed recently)
* Cross compile for Linux/Mips (started)
* Cross compile for Linux/PPC (started)
* Run on PPC Linux (started)

---
## Porting OpenWatcom to cross compile for a different OS with a known Architecture
* cross compile for BSD running on x86
* cross compile for BSD running on PowerPC or Mips
* MacOS on PowerPC (MacOS no longer uses PowerPC)
* MacOS on x86 (MacOS no longer uses x86)

---
## Porting OpenWatcom to [cross] compile for a known OS with a new Architecture
These are the hardest ports, affecting all projects in `bld/`
* Compile for x86_64 on Linux, Windows NT (x86_64 on MacOS was replaced by aarch64)
* Compile for aarch64 on Linux, Windows NT (or MacOS)
* Compile for arm / thumb on Linux, Windows CE
* Compile for RISCV 32Bit on Linux (RV32I has only 47 assembler commands)
* Compile for RISCV 64Bit on Linux

---
## Suggestions to port OpenWatcom to a new Platform
You might find it easier to start with these steps, before working on the collection from the Mailing List
* Port wdump (handles executables/libraries/object files without ORL)
* Port the ORL
* Port tools based on ORL

Collected from the OpenWatcom Mailing list: https://narkive.com/gGQXWm2h.22
* Write the disassembler
* Port the debugger
* Port the assembler
* Port the C front end
* Now comes the really hard part, the codegen
* Port the clib
* Port the linker
* Run (and pass) tests
* Optionally continue with the C++ and perhaps F77 compiler and other tools

---
