Getting Started with the Openwatcom Integrated Development Environment By Michael Greene and Gordon Snider (This is not intended to be a full tutorial of the Integrated Development Environment (IDE). It is only to get you started by showing you the simplest way to compile the programs of the book using the default settings.) 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? [5] IDE Basics [6] Let's Go ============================================================================== SECTION [1]: What is OpenWatcom? OpenWatcom (OW) is an effort to take the commercial Sybase Watcom compilers, and turn them into an Open Source Project. The OpenWatcom products are the first, and so far the 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 actual 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 this time (January, 2005) is 1.3 (open-watcom-os2-1.3.exe). ============================================================================== SECTION [3]: Installing OpenWatcom for OS/2 and ECS [3.1] 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 a 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. [3.2] Additional Tools for OS/2 Programming. While not required for the C++ course, it is highly recommended that the OS/2 Toolkit be installed. The Toolkit files are not needed to use OW, but the documents installed with the Toolkit contain a great amount of useful information. The Toolkit will be needed if you go on to OS/2 programming. 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.3] SETVARS.CMD - When you install the OW compiler package it will offer 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. If you choose to have your CONFIG.SYS file updated now, at the initial compiler install time, and later upgrade the compiler, the install routine will honour the entries in your CONFIG.SYS file and install the upgrade on top of your present installation. Not updating your CONFIG.SYS is the way to go if you have more than one compiler, or more than one version of OW. The entries that would have gone into your CONFIG.SYS file are instead put into 'SETVARS.CMD', which is placed in the Watcom base directory. SETVARS.CMD must be run at the beginning of each programming session. I will assume you choose this method. @ECHO OFF SET WATCOM=?:\WatCom (? is your drive letter) 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 ide.exe (you can add this last line to start the IDE) However setvars.cmd does not allow for the ToolKit so if you have it you will have to add entries to SETVARS.CMD for it. ============================================================================== SECTION [4]: What is an Integrated Development Environment? [4.1] Overview An Integrated Development Environment (IDE) is a tool for programmers that ties together various other programming development tools, like an editor, 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, so that if you change one piece of source code the IDE will be able to figure out which pieces of your project need to be recompiled and relinked. This can save you time. The IDE uses a 'make' file, and other files, to do this. [4.2] Preparation To keep all your code organized and not mix up the programs between projects you should establish a directory structure. Here is one suggestion: F:\Watcom\ BINNT BINP BINW EDDAT H LIB286 LIB386 NLM OS2TK45 (OS/2 Toolkit in here) Projects (Your programming in here) SAMPLES SRC The Projects directory has been added to the base level of an OW install. A directory for your code, e.g. Projects, DOES NOT have to be in the Watcom base directory, but you should have one somewhere and not mix your code with the compiler code, or mix your products together. Below that you could put a folder for each project, and below that other levels, as necessary. F:\Watcom\Projects\ convert (project) fleas (project) hello (project) ============================================================================== [5] IDE Basics Here are some definitions of terms used by OW. While you may think of your programming in terms of 'source code' and 'executable code' OW works with Projects and Targets. This is how it organizes your work. As a general note, you should name files using the 8.3 naming system when naming products and targets. [5.1] The IDE does not specifically do compiles and links. Instead it 'makes targets'. This includes compiling and linking of .exe and .dll files. [5.2] Project - A 'project' is the overall name for your product. Your project may be as simple as a source file and an .exe file, or complex, with many source, .exe, .dll, and .inf or .hlp files. An .exe or .dll file may include many .cpp source files. Whatever its complexity the OW IDE will create a .wpj file to manage it. You might want to have a 2nd-level folder, (within the Projects folder), for each project, named to remind you of the project name. The .wpj file will go there. [5.3] Target - A 'target' is a sublevel of a project. A target is an executable file. It can be an .exe file, or a .dll file, or a .hlp file, or an .inf file. The IDE will create a .tgt file to manage each target. Each target will have one or more source files. For Terry Norton's C++ course OW uses C++ source files that end in .cpp [5.4] Tool Bar Buttons (TBBs) In the IDE's main window there is a tool bar with 12 buttons on it. If you put the mouse pointer on a button its name (function) will appear in the information window at the bottom left. The buttons are named: 1. Create a new project 2. Open existing project 3. Save current project 4. Edit the selected source file 5. Make the selected source file 6. Make the current target 7. Run the current target 8. Debug the current target 9. Browse the current target 10. Run and sample the current target 11. Profile the current target 12. Make all targets in the project We will be working with some of these buttons, plus the INSERT key. We will not to go into the menus for simple work. [5.5] Navigating Directory Trees Several OW dialogs contain the standard OS/2 windows for navigating a directory tree. When you are to use these I'll just say "Navigate to ..." When it comes time to create a .wpj file navigate to the directory you want. If you need to create a new level of directory you can add one level of directory ahead of your new file, e.g. if you are in the Projects directory and you start a new project, WhizBang, in its own directory and you don't already have a WhizBang directory in the Projects directory you can add it directly when creating the WhizBang.wpj file, i.e. WhizBang\WhizBang.wpj [5.6] Compatibility Note On page 20 of the text book there is a 'Compatibility Note', which says; "Some windowing environments run the program in a separate window and then automatically close the window when the program finishes." To get the window to stay open so you can see the results of your coding add the following 2 lines of code to each program before the return statement in the main() function cin.get(); cin.get(); These lines will cause the program to wait for a keystroke before closing the 'run' window in the IDE. (Some programs in the book require 2 lines, some only one. I haven't figured out why this is, yet. Start with 2 and cut back to one if that is all you need.) Assuming that your program will be run in a command line window, when your program is fully developed and debugged, just before the last compile remove this line (or these lines) to result in normal operation. ============================================================================== [6] Lets Go 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. The following instructions make use of the tool button bar, the INSERT key, the F5 key in the GUI. We will now develop the 'Hello World' product, start to finish. 1. Open the IDE Open a command line window and change directory (CD) to the OW drive and directory. Execute 'SETVARS', which should have IDE.EXE as its last line. This should put you into the IDE GUI at this point. 2. Start A New Project Click on the Tool Bar Button 'Create a new project' This will open a dialog asking you to 'Enter Project Filename' Use the Drive and Directory sub-windows to navigate to your Projects directory. Change the 'Open filename' line from noname.wpj to world\world.wpj and press 2a. Because the 'world' folder doesn't already exist it will ask you if you want to create the folder. Click 'Yes'. 3. A 'New Target' dialog will open with the suggested target name of world. We are going to change it. We want to tell the IDE we want to create an 'OS/2 - 32 bit executable [.exe]' named hello.exe Here's how we do that. Overtype the suggested target name world with the target name hello 3a. Use the 'Target Environment' radio buttons. For this target accept the default of 'OS/2 - 32-bit'. 3b. You also have a choice of 'Image Type'. For the purposes of this target take the default, 'Executable [.exe]' Programs of this image type will run by naming them at the command line. or in a Full Screen OS/2 session. Click the 'OK' button. 4. Now the title bar of the main window will have the fully qualified name of world.wpj file for the project \Projects\World\World.wpj There will be a target sub-window with hello.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 hello.exe Now we have to tell the IDE the source file name. 5. To create the source file, press the INSERT key A small dialog window named: Add File(s) to 'hello.exe' will open. 6. Type in hello.cpp and press . (You have only registered the name of the .cpp program.) That dialog window will close and you will be back at the hello.exe target window, but now under 'Source files:' there will be a section showing Source Files for 'hello.exe'. There is a 2 line entry. The first line says (.cpp) This is a heading for all type .cpp files for this target. The second line says hello.cpp [n/a] The [n/a] means not available. (Of course not. It hasn't been written yet.) 7. To write it, double click on (or use the cursor keys to select, and hit ) hello.cpp [n/a] A text editor will open. (EPM is the default.) 8. Enter your C++ code for the 'hello.cpp' program. (Cut and paste this 10 line program if you want.) // hello.cpp -- displays a message #include // a Preprocessor directive using namespace std; // make definitions visible to compiler main() // function heading { // start of function body cout << "Hello, world!\n"; cin.get(); return 0; } Using the editor commands save it as 'hello.cpp'. 9. Alt+Tab back to the main IDE window. Click the TTB 'Make all targets in the project' This action includes compiling and linking. Check the informational messages at the bottom. Fix any errors. 10. When the compile is clean click the TBB 'Run the current target' and see the result. Hit once or twice to close the window. Done. If you open a command line window and navigate to the project directory you will see approximately 10 files there with extensions like '.cpp', '.exe', '.map', '.lk1', '.mk', '.mk1', '.tgt', '.wpj'