Using OpenWatcom C with ELKS

ELKS supports using the OpenWatcom C toolchain for creating and executing programs in small, medium, compact and large models. When compact or large models are built, ELKS supports the loading of multiple code and data segments, with a current adjustable default limit of five segments, allowing programs of 320k+ size to run.

In order to build programs using Watcom C you need to:

• first either install OpenWatcom C v2 or binary snapshot, both you can download from https://github.com/open-watcom/open-watcom-v2/releases. Next possibility is clone the repo from https://github.com/open-watcom/open-watcom-v2 and build OpenWatcom from this repo.
• build an OpenWatcom version of the ELKS C library

If you have already installed OpenWatcom or use prebuild OpenWatcom installer or binary snapshot then you can skip next sections about OpenWatcom build.

Build OpenWatcom

The following are instructions to build OpenWatcom on macOS or Linux.

Configure OpenWatcom build system

• copy the setvars.sh file from root of OpenWatcom repo under a new name (by example myow.sh), preferably outside the OpenWatcom source tree
• in your copy of this file, adjust following variables

Variable	Action
OWROOT	set the value according to your actual location of the OpenWatcom source tree, by example export OWROOT=/home/user1/ow2
OWTOOLS	change if necessary to identify your toolchain used by build process (by default it is GCC)
OWGUINOBUILD	uncoment line # export OWGUINOBUILD=1 (remove # character from front of line)

Build OpenWatcom from sources

Before you start OpenWatcom build run your configuration script . ./myow.sh which setup OpenWatcom build environment.

Running ./build.sh rel built the entire system, which then is copied into OWROOT/rel.

Build the ELKS C Library

Before you build ELKS C library, you need to configure OpenWatcom depending on your installation.

Configure for OpenWatcom

The WATCOM and PATH variables must be set correctly in the libc/wcenv.sh file.

#!/usr/bin/env bash
#
# Set up Watcom build environment
#
# Usage: . ./wcenv.sh

# change to OpenWatcom installation root it is full path to OpenWatcom location
# if you use your own OpenWatcom build than it is located in rel subdirectory
export WATCOM=/Users/greg/net/open-watcom-v2/rel

add_path () {
        if [[ ":$PATH:" != *":$1:"* ]]; then
                export PATH="$1:$PATH"
        fi
}

#add_path "$WATCOM/binl"    # for Linux-32 (Intel CPU)
#add_path "$WATCOM/binl64"  # for Linux-64 (Intel CPU)
add_path "$WATCOM/bino64"   # for macOS    (Intel CPU)
#add_path "$WATCOM/armo64"  # for macOS    (ARM CPU)

echo PATH set to $PATH

• If you use the OpenWatcom installer or binary snapshot, set WATCOM=<installation location path>.
• If you are building OpenWatcom from sources, then the OpenWatcom build is located in the rel subdirectory, set WATCOM=<OpenWatcom source location path>/rel.

Next set the PATH for your host system by uncommenting the appropriate line in this file.

Building the C Library using OpenWatcom

Make sure that the ELKS tools directory is in your path, as the next step requires the ELKS TOPDIR environment variable to be set. If you haven't already setup ELKS. This can be done by:

cd {ELKS top-level directory}
. ./env.sh    # sets TOPDIR and adds $TOPDIR/elks/tools/bin to path

After that, the ELKS C library needs to be built using OpenWatcom. The default compilation model is large, but can be changed by editing the file elks/libc/watcom.model:

cd $TOPDIR            # ELKS top-level directory
cd libc
make -f watcom.mk     # creates elks/libc/libc.lib, used by ewlink

Building an example program using OpenWatcom

ELKS provides two scripts to more easily compile and link programs with OpenWatcom C. These are ewcc and ewlink - simple scripts to compile a single .c file for each file in a project, and then link them into a final executable. The executable format created is technically an OS/2 v1.x 16-bit binary; ELKS has the ability to natively load and execute these binaries. For the time being, the extension of OS/2-formatted binaries is ".os2".

The source for these scripts is in elks/tools/objtools/ewcc and ewlink.

For a tested example, the following will build ELKS basic from scratch using OpenWatcom:

. ./wcenv.sh
cd $TOPDIR/libc
make -f watcom.mk clean
make -f watcom.mk            # produces $TOPDIR/libc/libc.lib, required for ewlink
cd $TOPDIR/elkscmd/basic
ewcc basic.c
ewcc host.c
ewcc host-stubs.c
ewlink basic.obj host.obj host-stubs.obj    # creates basic.os2
# optionally convert to ELKS a.out format (no longer needed)
#os2toelks -f elks -o basic basic.os2
cp basic.os2 $TOPDIR/elkscmd/rootfs_template/root

... then, in ELKS:

# ./basic.os2

Of course, the .os2 extension may be renamed or removed if desired, but is currently left on to differentiate OS/2 and ELKS a.out binaries. The file command can also be used to determine the type of executable, if desired.