Using Watcom C/C++ 11.0c on OS/2

By Michal Necasek

After an unexpectedly long wait, the OpenWatcom team (it would be probably useful to note that I'm a member) finally released the first step on the road to the OpenWatcom compiler, the Watcom 11.0c binary "patch". Both C/C++ and FORTRAN files are available, but as I don't speak FORTRAN (and most of you probably neither), I will concentrate solely on the C/C++ compilers (and sometimes refer to them simply as "Watcom" to save me some typing and you some reading). The Watcom C/C++ and FORTRAN compilers have a lot in common however and many details I will discuss here are applicable to both.

If you have never used Watcom C/C++ and don't know about this compiler, I should explain what makes it different from most other compilers: Watcom is a cross-compiler. First some useful terminology:

• Host platform - platform the development tools run on
• Target platform - platform the developed program runs on

The host and target platforms are often identical but need not be. Currently supported target platforms are 16-bit and 32-bit DOS, 16-bit and 32-bit OS/2, 16-bit and 32-bit Windows and Novell NetWare. With some limitations, it is possible to develop for any target platform on any host platform, in practice the best host platforms are OS/2 and Win32. It is perhaps useful to note that on each host platform there is only a single compiler/linker binary that can create programs for any target platform (actually, there are several compiler binaries but they all support all targets). This clearly makes Watcom an excellent choice if you develop for multiple platforms.

Watcom C/C++ gained lot of popularity in mid-1990's as the compiler used for most games - major hits like DOOM or Warcraft II were built with Watcom. The easiest way to tell if a game or program was developed with Watcom compiler is to see if it uses the DOS/4GW extender - the W stands for Watcom and this very popular extender only works with Watcom compilers and in fact was included in Watcom with royalty-free license.

For OS/2 developers Watcom has one "unique" property - it can generate 16-bit code and hence can be used for device driver development. The only other choice seems to be ancient Microsoft C 6.0A from the DDK which is completely unsupported. All other OS/2 compilers are 32-bit only.

But back to Watcom 11.0c. It is labelled as "patch" which is a bit misleading. It is a patch in the sense that to obtain full capabilities of previous versions, you need to apply 11.0c over an existing Watcom installation. On the other hand, depending on your needs, previous Watcom installation may not be required. The reason for this complication is that Watcom compilers used to be shipped with various third-party files - headers, libraries, and tools - that the OpenWatcom team has no legal right to distribute. I will now discuss the various target platforms and what is missing in 11.0c.

• 16-bit DOS - no 3rd party files required.
• 32-bit DOS - a DOS extender is required. There are several freely available ones, the best choice is probably [CauseWay]. It is however easiest to use DOS/4GW (just DOS4GW.EXE is needed) from your old version of Watcom.
• 16-bit OS/2 - headers, libraries and tools are required. For device driver development, everything necessary is on the DDK. I doubt there is much demand for 16-bit OS/2 apps.
• 32-bit OS/2 - headers, libraries and tools are required. Watcom C/C++ 11.0c works well with the IBM OS/2 Toolkit version 4.0 and 4.5. Many Watcom users installed separate Toolkit anyway because Watcom came with an ancient Toolkit version 2.1.
• 16-bit Windows - headers, libraries and tools are required. No longer supported by Microsoft so this might be a problem. Probably not much demand either.
• 32-bit Windows - headers, libraries and tools are required. This is the toughest case because the Microsoft Platform SDKs only work with Microsoft's own compiler and need some modifications to work with anything else.

Watcom 11.0c fixes several long-standing OS/2 issues from previous versions, such as the debugger crashing on startup on newer OS/2 kernels (not technically a bug in Watcom) or the linker incorrectly generating fixups for 16-bit API calls from 32-bit code.

OK, now let's get down to the details. I will provide a brief guide on installing Watcom C/C++ 11.0c on OS/2. There are two basic possibilities:

• You have an existing installation of Watcom C/C++ on your machine. In this case you simply overwrite the old files and no further steps are required, everything is already set up.
• You for any reason do not wish to install over an existing version. I will attempt to help you with that.

From now on I will only talk about the second choice - performing a "clean" Watcom 11.0c installation. I will also only discuss what is needed for 32-bit OS/2 development. The necessary steps are:

1. Download the Watcom 11.0c files from openwatcom.org. The 11.0c patch is provided in two forms, there is a single self-installing executable or a number of smaller ZIP files. The self-installer is a Win32 EXE file that seems to work well under Odin. If you have a fat connection you will probably want to get that. The ZIP files are on the OpenWatcom FTP site and you can only download the files you need. There is a readme file in the FTP directory that gives a brief description of the files - it should be self-explanatory. If you are only interested in OS/2 development, get the files labelled 'all' and 'os2' and simply unzip them into a directory (X:\WATCOM would be a good choice).
2. Install the OS/2 Toolkit. The latest version (4.5) is available on the MCP or eCS CDs or from the IBM Developer Toolbox (subscribers only). Older versions should work too.
3. After the Watcom files have been installed, you will need to set up a few environment variables. You can put them in your CONFIG.SYS if Watcom is the only compiler you use - but if you're like me and use 3-4 different compilers, you'll need a separate CMD file. There is a sample CMD file in c_readme.txt on the OpenWatcom FTP but I will present a slightly different version here intended for stand-alone 11.0c installation:
   @ECHO OFF
   SET WATCOM=C:\WATCOM
   SET TOOLKIT=C:\TOOLKIT
   SET PATH=%WATCOM%\BINP;%WATCOM%\BINW;%PATH%
   SET INCLUDE=%WATCOM%\H;%TOOLKIT%\H
   SET ED_PATH=%WATCOM%\EDDAT
   SET HELP=%WATCOM%\BINP\HELP;%HELP%
   SET BOOKSHELF=%WATCOM%\BINP\HELP;%BOOKSHELF%
   SET BEGINLIBPATH=%WATCOM%\BINP\DLL
   SET LIB=%TOOLKIT%\LIB;%WATCOM%\LIB386\OS2;%WATCOM%\LIB386;
   You can name and place this CMD file whatever and wherever you wish. If you installed Watcom 11.0c and/or the OS/2 Toolkit to a different directory, you will naturally have to adjust the CMD file accordingly. It is assumed that you let the Toolkit installation update your CONFIG.SYS - if not, you will need to add the TOOLKIT\BIN directory to the PATH so that tools like the resource compiler (RC) can be run.
4. If you run the above CMD file, you should verify that the Watcom tools run correctly. If you for instance run wcc386, you should see the compiler banner and a list of options. If this doesn't work, you need to back-track a bit - most likely the PATH or (BEGIN)LIBPATH is not set up correctly.
5. If you can run the compiler, you should verify that the rest of the environment is set up correctly by building simple sample programs. Here's one, called hello.c:
   #include <stdio.h>
   
   void main(void)
   {
   printf("Watcom 11.0c says Hi!\n");
   }
   Now build this program by running
   wcl386 hello.c
   You should see the following output:
   Watcom C/C++32 Compile and Link Utility Version 11.0c
   Copyright by Sybase, Inc., and its subsidiaries, 1988, 2000.
   All rights reserved. Watcom is a trademark of Sybase, Inc.
   wcc386 hello.c
   Watcom C32 Optimizing Compiler Version 11.0c
   Copyright by Sybase, Inc., and its subsidiaries, 1984, 2000.
   All rights reserved. Watcom is a trademark of Sybase, Inc.
   hello.c: 6 lines, included 477, 0 warnings, 0 errors
   Code size: 24
   
   WATCOM Linker Version 11.0c
   Copyright by Sybase, Inc., and its subsidiaries, 1985, 2000.
   All rights reserved. Watcom is a trademark of Sybase, Inc.
   loading object files
   searching libraries
   creating an OS/2 32-bit executable
   and files hello.obj and hello.exe should have been created. If you run the hello program, you should see the greeting message on the console. If you did, you probably have most of the environment set up correctly. If not, check especially the INCLUDE and LIB variables, depending on what exactly failed.
6. Now try something a bit more complicated - a simple PM program to verify that the Toolkit is set up properly too. For this, several files are required - available here. You should unzip them into a separate directory and run wmake (the Watcom make utility) from there. You should see messages from wmake, wcc386, wlink and rc (lots of them). When you run pmhello, you should see a simple PM window. If not, again the things to check are the INCLUDE and LIB environment variables as well as PATH if the resource compiler doesn't run correctly (Note: older versions of RC have a bug that prevents them from working if the PATH environment variable is too long). This is not intended as a comprehensive PM sample program but you can hack at it to your heart's content.

If you got this far, congratulations, you're all set! You will probably want to test the debugger (wd or wdw) and you may want to use the Watcom IDE (started with ide command) if you prefer IDEs to command line. If you know the vi editor, you might want to use the version that comes with Watcom (aptly named vi). And of course you should read the online documentation - the most important online books are CGUIDE, PGUIDE, CLIB, CLR and LGUIDE (you can run view cguide etc. from the command line). Also worth reading is C_README although it is not 100% applicable to 11.0c - it does contain an introduction to using the Watcom IDE. All these INF files are located in X:\WATCOM\BINP\HELP.

I have just scratched the surface of all that is included in Watcom 11.0c. Besides the obvious C and C++ compilers, linker, make tool, debugger and IDE that I already mentioned there's a librarian (wlib) assembler (wasm), disassembler (wdis), C++ class browser (wbrw) and profiler (wprof). Exploration is the key - and reading the online documentation too.

The OpenWatcom web site contains further Watcom-related resources, such as FAQs or links to support newsgroups. It is a good place to start if you're looking for more information and support. Have fun and be sure to develop the next OS/2 killer app with Watcom C/C++ 11.0c!