First Draft - For Discussion




Table of Contents:

[1] What is OpenWatcom?
[2] Where to get OpenWatcom for OS/2 and ECS
[3] Installing OpenWatcom for OS/2 and ECS
[4] What is an IDE?

SECTION [1]: What is OpenWatcom?

Open Watcom is an effort to take the commercial Sybase Watcom
compilers, and
turn them into an Open Source Project. The Open Watcom products are so
far the
first and only proprietary compilers to be Open Sourced.

SECTION [2]: Where to get OpenWatcom for OS/2 and ECS

The OpenWatcom website (http://www.openwatcom.org/) has links to the OS/2
version for download. However, the website updates lag actually
releases by
days and sometimes weeks so it is recommended to download from one of the
following sites:

ftp://ftp.scitechsoft.com/watcom/
http://openwatcom.mirrors.pair.com/watcom/

The latest release version at at this time (January, 2005)
is 1.3 (open-watcom-os2-1.3.exe).

SECTION [3]: Installing OpenWatcom for OS/2 and ECS

[3.1] Prerequisites for OpenWatcom.

While not a required prerequisite, it is highly recommended that the OS/2
Toolkit be installed. The Toolkit files are not needed to use
OpenWatcom, but
the documents installed with the Toolkit contains a great amount of
useful
documentation. The Toolkit can be installed during OS/2 MCP1 / MCP2
installation or at a later time from the Install CDROM. The Toolkit
for ECS
can be installed from CD #2 (ECS 1.2), see the ECS documentation for
further
instructions.

[3.2] Installation Issues / Bugs and Work Arounds

Older OpenWatcom notes contained the following note: Some OpenWatcom
tools
currently do not function properly if installed in a directory with
spaces
in the name e.g. "C:\Program Files\WATCOM". Therefore choose a
directory name
like C:\WATCOM, D:\WATCOM etc. to install the tools in. This issue has
not
been verified to be fixed in release 1.3.

If you are re-installing OpenWatcom to different drive and/or
directory and
the CONFIG.SYS contains old OpenWatcom statements they must be
removed. The
installation program will detect the older install statements and
attempt to
install to the previous drive.

It has also been observed during installation that if the drive is
changed all
OpenWatcom files maybe installed to the root of the drive. To work
around this
bug, select the installation drive and type in the installation directory
name.

SECTION [4]: What is an IDE?

[4.1] Overview

An Integrated Development Environment is a tool for programmers that ties
together various other programming development tools, like a compiler, a
linker, a debugger, a run environment, a make file, etc., and it makes
the
tools easy to use and to switch between. It also stores your switch
settings
for each tool. As well, it keeps track of all the 'pieces' of your
project,
source code, object code, resource files, etc. as to their location and
condition. The IDE uses a 'make' file to do this.

[4.2] Preparation

To keep all your code organized and not mix up the programs between
projects
you can establish a directory structure. Here is one suggestion:

F:\Watcom\
├ BINNT
├ BINP
├ BINW
├ EDDAT
├ H
├ LIB286
├ LIB386
├ NLM
├ OS2TK45
├ Projects
├ SAMPLES
└ SRC

The Projects directory has been added to the base level of a WatCom
install.
Below that you could put a folder for each project, and below that other
levels as necessary.

F:\Watcom\Projects\
├ convert
├ fleas
├ hello
├ ourfunc
└ squart

The OS/2 ToolKit should also be added. It is available several places,
the Merlin Convenience Pack or eComStation or with an earlier OS/2
C compiler, like VisualAge C.

[4.3] Setvars.cmd - When you installed the WatCom compiler package it
offered you a choice of whether or not to update your config.sys file.
Updating config.sys is the way to go if you have no other compiler and
no plans to get one. Think carefully before you install this about
where you want the compiler to be. When the compiler is upgraded the
install routine will honour the entries in your config.sys file and
install the upgrade on top of your present install.
Not updating your config.sys is the way to go if you have more than one
compiler. The entries that would have gone into your config.sys file are
instead put into 'setvars.cmd'. Before each programming session switch
to the Watcom directory and run 'setvars', then start the IDE.

/*SETVARS.CMD */
@ECHO OFF
SET WATCOM=F:\WatCom

SET PATH=%WATCOM%\BINP;%WATCOM%\BINW;%PATH%
SET INCLUDE=%WATCOM%\H;%WATCOM%\H\OS2
SET FINCLUDE=%WATCOM%\SRC\FORTRAN
SET EDPATH=%WATCOM%\EDDAT
SET HELP=%WATCOM%\BINP\HELP;%HELP%
SET BOOKSHELF=%WATCOM%\BINP\HELP;%BOOKSHELF%
SET BEGINLIBPATH=%WATCOM%\BINP\DLL

However setvars.cmd does not allow for the ToolKit or for opening the IDE,
so

[4.4] Definitions

[4.4.1] Project - A 'project' is the overall name for your product, like
'WhizBang'. The IDE will create a .wpj file with that name and store
data
about the project there. (We are not at the source code level yet.)

[4.4.2] Target - A 'target' is a sublevel of a project. A target can
be thought of as all the code necessary to produce an .exe file, or a
.dll file.
For example, each target may have one or more source files and their
associated executable.

[4.5] Starting off.
There seems to be considerable flexibility available in how you organize
your work and where you place it and how you operate the IDE.
What follows is the most simplified starting approach, just to get you
going. You can add complexity later.

1. Open the IDE
Depending on how you installed you may do this either:
by opening the IDE object
or
by opening a command line and executing 'setvars' and then 'ide'.
(You will be back in a GUI at this point.)

2. Start A New Project
File -> New Project
This will open a dialog asking you to
It will suggest the name 'noname.wpj'. I suggest you change that.

3. Type in the full path and name of the .wpj file something like
F:\WatCom\Projects\World\World.wpj
Click the 'Open' button.

3a. If the folder doesn't already exist it will ask you if you want to
create
the folder. Click 'Yes'.

4. A 'New Target' dialog will open with the suggested target name of
World. Accept that. (In your following projects you may want to
use a more meaningful name.)

4a. There are also 'Target Environment' radio buttons.
For this project accept the default of 'OS/2 - 32-bit'.

4b. You also have a choice of 'Image Type'.
For the purposes of Terry Norton's CForeCsandOS2 group lessons
take the default, 'Executable [.exe]'
Programs of this image type will run by naming them at the command line.
There must not be any GUI code in these programs.
With a small modification they will also run in a Full Screen OS/2
session.
Click the 'OK' button.

5. Now the title bar of the main window will have the fully qualified
name of
world.wpj file
F:\WatCom\Projects\World\World.wpj
There will be a sub-window with World.exe in its titlebar.
'Well', you may wonder, 'I haven't created that yet. Where did it come
from?'
It doesn't exist yet. You are going to create it shortly. This
sub-window
holds the list of source files that will be compiled to produce World.exe

6. To make the source file, click on the menu item
Sources -> New Source
A small dialog window named:
Add File(s) to 'World.exe'
will open.

7. Type in
world.cpp
and press <enter>.
(You have only registered the name of the .cpp program.
It is done this way because this compiler makes it possible to include
source
files that have already been written, as well as writing source files
after
this point.)
That dialog window will disappear and you will be back at the small window
showing Source Files for 'World.exe'.
but now in the Source Files list there is a 2 line entry.
The first line says (.cpp) This is a heading for all type .cpp
files.
The second says whizbang.cpp [n/a]
The [n/a] means not available. (Of course not. It hasn't been
written yet.)

8. To write it, double click on
world.cpp [n/a]
A text editor will open.

9. Enter your C code for the 'world' program.

world.cpp -- displays a message

#include <iostream> a Preprocessor directive
using namespace std; make definitions visible

main() function heading
{ start of function body

cout

"Hello, World!\n";
return 0;

}

Using the editor commands save it as 'world.cpp' and close the editor.

10. You will be back at the main IDE window.
Click
Actions -> Make All
This action includes compiling and linking.

11. Open a command line window and navigate to the directory where the
program is. In this example it would be:

F:\WatCom\Projects\World\

You will see approximately 10 files there with extensions
like '.cpp', '.exe', '.map', '.lk1', '.mk', '.mk1', '.tgt', '.wpj'

12. Type in
world
and see the result.

Please see the 'Compatibility Note' on page 20 of our text,
"C Primer Plus", Fourth edition.
It notes there that, depending on your windowing environment you may
need to modify your programs if using the menu item
Actions -> Run ...
If you use this the image type 'Executable [.exe]' will produce a program
that will switch your display to OS/2 Full Screen and the program will
run,
and the window will close. If you want to keep the window open at the end
of your program, as discussed in the text you must add to the end of your
program these TWO lines:

cin.get()
cin.get()

which will keep your program from ending until you press <Enter>.