10. Lesson 1: Create the DOS Application

In this chapter you learn basic procedures for using the Integrated Development and Debugging Environment (IDDE) while building a DOS version of the TML Reader. This lesson teaches you to:

• Start the IDDE and load a project
• Edit source code
• Build and run the application
• Create a debugging workspace
• Run the application in debugging mode

Most of the code for the application has already been written; during the lesson you will add a few final lines. At the end of the lesson, you will have a DOS executable that can read and display TML files.

Starting the IDDE and Loading a Project

To start the IDDE:

First, start the IDDE. If you haven't yet installed Digital Mars C++, please see the Getting Started Guide for installation instructions.

1. Double-click on the Digital Mars C++ 16-bit group icon in the Windows Program Manager. (If the Digital Mars C++ 16-bit group is already open, you may omit this step.)
2. Double-click on the Digital Mars C++ icon. The IDDE main window opens at the top of the screen (see Figure 10-1).

   

   [Figure 10-1 The IDDE main window and Workspace toolbox]

The IDDE main window contains a title bar and a menu bar. Below the main window is the Workspace toolbox, used to switch between workspaces (described later in this chapter). The Workspace toolbox is currently docked under the IDDE menu bars. Additional IDDE windows open below the main window and Workspace toolbox. You can open other IDDE windows by selecting their names from the Goto View submenu of the Window menu; close any window by clicking the Close button in its upper-left corner.

Next, you must load the DOS TML Reader project. (A project is a collection of source and other support files from which an executable is generated.) To open the project:

1. Choose Open from the IDDE's Project menu.
2. Use the Open Project dialog box to find samples\tutorial\lesson1\start\tmldos.prj, located under the directory in which you installed Digital Mars C++.
3. Click OK.

You can view the project's source file list in the Project window. If the Project window is not already open, choose Project from the Goto View submenu of the Window menu.

In the next section you edit one of the source files.

Editing Source Code

The DOS TML Reader's source code needs a minor addition before compilation. To add the missing lines, you must edit the source code in a Source window.

1. In the Project window, double-click on display.c. A Source window opens, showing the contents of the source file (see Figure 10-2).

   

   [Figure 10-2 Source window]

2. Choose Function from the Source window's Goto menu. The Goto Function dialog box opens.
3. Select Display from the Function Name listbox, then click OK. The editor moves to the start of Display().
4. Choose Find from the Edit menu. The Find dialog box opens.
5. In the Pattern textbox, type LESSON 1.
6. Click on Next.
7. You should see the following line in the source code:

   	/* INSERT CODE FOR LESSON 1 HERE! */ 
   	

   Just after this comment, but before the procedure's closing brace, insert the following two lines of code:

   	disp_move(disp_numrows - 1, 0);
   	disp_eeol(); 
   	

8. Choose Save from the File menu.

The DOS TML Reader is now ready to be compiled. In the next section you learn to build and run the project, and you look at a sample document.

Building and Running the Application

To build and run the DOS TML Reader:

1. From the IDDE's Project menu, choose Rebuild All.

   The Output window opens automatically. This window informs you of build progress and displays any warning or error messages. If no errors exist, you see the message "Successful build." (You can still work in the IDDE while the build is in progress, because the process of building is multitasked. The Output window can be behind other IDDE windows, even when messages are being written to it.)

2. From the IDDE's Project menu, choose Arguments. The Run Arguments dialog box opens.
3. Type sample.tml into the textbox and click OK.
4. From the Project menu, choose Execute Program.

The TML Reader opens in full-screen mode, showing the formatted contents of sample.tml (see Figure 10-3). You can use Page Up, Page Down, and the arrow keys to scroll through the file. To execute a hyperlink, position the cursor over text shown in reverse video and press Enter. Press Escape to exit the program and return to the IDDE.

[Figure 10-3 The DOS TML Reader]

The DOS TML Reader is believed to be without any significant bugs. However, most applications have bugs during at least some of their development phase. To help you locate and correct incorrect code as quickly as possible, the IDDE has powerful debugging features.

The following sections show you how to set up a workspace for debugging and debug your source code.

Setting Up a Workspace for Debugging

A workspace is an arrangement of windows on the screen. You can set up several useful configurations of IDDE windows, then switch between them by clicking on workspace names in the Workspace toolbox.

The IDDE predefines a workspace named Debugging, which contains a configuration of windows useful for typical debugging sessions. Here, however, we define a new workspace specific to this lesson, to show you how this is done and to avoid disturbing any customizations you may have already made to the Debugging workspace.

To create a workspace for debugging:

1. Choose New from the Workspace submenu of the IDDE's Environment menu.
2. When prompted for a workspace name, type Lesson1.
3. Click OK.

The IDDE creates a new workspace and adds the workspace name to the Workspace toolbox. Initially the new workspace is empty, with the exception of a few toolboxes that are not needed here. To close the toolboxes, click the Close buttons in the upper-left corners.

Next, you need to add windows to the workspace. During debugging, the Source window follows program execution, the Function window views a list of functions in a particular program module, the Data/ Object window views program data, and the Call window displays the program call chain.

1. To open the Project window, press Ctrl+Shift+P.
2. In the Project window, double-click on main.c. A Source window opens.
3. To open the Function window, press Ctrl+Shift+F.
4. To open the Data/Object window, press Ctrl+Shift+D.
5. To open the Call window, press Ctrl+Shift+L.

Other debugging windows are available as well; see Chapter 24, Commands Available in Debugging Mode, for more information.

Arrange the windows the way you want them (one example is shown in Figure 10-4), then choose Save Workspace Set from the Workspace submenu of the IDDE's Environment menu.

[Figure 10-4 A possible Lesson 1 workspace]

Now that the workspace is ready, you can begin debugging. The following section shows you how to run the application in debugging mode and how to set a breakpoint on a function, how to view program data, and how to step through code.

Running in Debugging Mode

To execute the application in debugging mode, click in the Source window, then choose Start/Restart Debugging from the IDDE's Debug menu. Several things happen:

1. The IDDE opens a window (the Digital Mars Application Window), in which the application runs. This window may be behind other windows.
2. The application is executed to the start of main.
3. The Source window changes to debugging mode (see Figure 10-5). Arrows indicating execution points within functions, and flags indicating breakpoints are shown in the left margin. You cannot edit the code while in debugging mode.

   

   [Figure 10-5 Source window in debugging mode]

4. The Project window changes to debugging mode (see Figure 10-6). The icons next to the source module names change to indicate their status:
   • A bug symbol indicates that the module contains debugging information.
   • A small "T" indicates that tracing is enabled in the module.
   • A green dot indicates that a breakpoint is set and enabled in the module.

     

     [Figure 10-6 Project window in debugging mode]

5. The Function window is updated to show a list of functions in the program (see Figure 10-6). An arrow next to main indicates that it is in the call chain; a diamond indicates that a breakpoint is set.

   

   [Figure 10-7 Function window]

6. The Call window is updated to show the call chain and execution status (see Figure 10-8).

   

   [Figure 10-8 Call window]

You can now perform the following simple debugging tasks.

Setting and running to breakpoints

To set a breakpoint on a function and execute to it:

1. Click and drag display.c from the Project window to the Source window.
2. Choose Set/Clear Breakpoint from the Bpt menu. A breakpoint is set at the start of ShowScreen.
3. Choose Go Until Breakpoint from the IDDE's Debug menu. The program is executed to the start of ShowScreen.

The Source window shows the line at which execution stopped. The Call window shows functions in the call chain (see Figure 10-9).

[Figure 10-9 Call chain to function ShowScreen]

Viewing data

You can view program data using the following commands:

1. Choose Data from the Show submenu of the Source window's pop-up menu. The Data/Object window is updated to show the local data in ShowScreen (see Figure 10-10).

   

   [Figure 10-10 Data/Object window showing local data]

2. In the Call window, click on main, then choose Data from the Show menu. The Data/Object window is updated to show the local data in main.
3. Choose Local/Global Data from the Data/Object window's View menu. The Data/Object window is updated to display global data accessible in the current module. Choose Local/Global Data again to resume display of local data.

Stepping through code

To step through the source code line-by-line:

1. Choose Step Into from the IDDE's Debug menu (or press F8) seven times. The IDDE executes seven lines of code. The seventh step takes execution into ShowLine; at that point the Call window adds ShowLine to the call chain, and the Data/Object window is updated to display the function's local data.
2. Choose Return from Call from the IDDE's Debug menu to execute the rest of ShowLine and return to the calling function.
3. Choose Step Over from the IDDE's Debug menu (or press F10) several times. The IDDE executes some lines of code in the function, but it does not step into subroutines. ShowScreen is in a loop that writes lines to the screen one-by-one. The results appear in the Digital Mars Application Window.

Running to the end

To execute the rest of the program, ignoring breakpoints, choose Go Until End from the IDDE's Debug menu. Bring the Digital Mars Application Window to the front and test the program as usual. You can press Alt+Ctrl+SysRq to break to the debugger, or let the program terminate before resuming your debugging session. (In the DOS TML Reader, you must press Escape to end the program.)

Ending the debugging session

To exit debugging mode, choose Stop Debugging from the IDDE's Debug menu. You can do this at any time during debugging; you don't have to choose Go Until End first.

In this chapter you have learned how to start the IDDE, load a project, edit source code, build and run the application, and run in debugging mode. These are the fundamental tasks you perform repeatedly as you develop your own applications, whether you are developing in C or C++, for DOS or for Windows. In the following lessons, you learn about the IDDE's more advanced features, many of which are designed specifically for Windows application development in C++.

Home | Compiler & Tools | Runtime Library | STL | Search | Download | Forums | Prev | Next

Copyright © 1999-2018 by Digital Mars ®, All Rights Reserved | Page generated by Ddoc.