Installing the CS1300 Software

• At the beginning of each lab exercise, you'll need to prepare the PC to use the CS1300 software. There are several ways to do this, depending on your location:

  Option 1: On Engineering Center PCs: Server Method

  On PCs in the Engineering Center, try this method first. If it doesn't work, then try the next method instead.

  1. Start a DOS session by clicking: Start, Programs, Accessories, Command Prompt.
  2. If the DOS session takes up the whole screen, then reduce it to a smaller window by holding down the Alt key and pressing Enter.
  3. From the DOS-session, try this command:   H:\gocs
     If the command doesn't seem to work, then ask your TA whether the H:\ should be changed to something else.

  Or Option 2: On your home PC:

  Directions for permanently installing the CS1300 software on your home machine are at www.cs.colorado.edu/~main/cs1300/README.html.

  Or Option 3: On Most PCs: Download Method

  You can use this method on any machine with a fast internet connection and about 100MB of free disk drive space.

  1. Start a DOS session by clicking: Start, Programs, MS-DOS Prompt.
  2. If the DOS session takes up the whole screen, then reduce it to a smaller window by holding down the Alt key and pressing Enter.
  3. Open a browser (Netscape or IE) and point it at each of these two files, selecting to save them to the top level of a drive (such as D:) when you are prompted.
        www.cs.colorado.edu/~main/cs1300/unzip.exe
   www.cs.colorado.edu/~main/cs1300/cs1300.zip
     The second file is large (about 30MB) and will take nearly a minute to download even with a fast internet connection.
  4. From the DOS-session, given these commands (using the drive letter that you selected in place of D:):
       D:
  cd \
  unzip cs1300.zip
  cs1300\gocs

Create a Working Directory

At the end of the installation step, you should have a DOS window open where you will carry out all your work.

This exercise assumes that you're already familiar with MS Windows and that you can create directories or "folders", and move files from one directory to another. For this exercise, you should start by creating a separate directory for this work. I put my working directory on my D: drive and called it D:\michael. From the DOS command line, the commands to create and move into this directory are:
  D:
  cd \
  mkdir michael
  cd michael

Always put your work in a subdirectory (rather than at the top of the disk drive). There are certain parts of the debugger that won't work correctly at the top of a disk drive.

Copying and Listing Files

Now you'll copy some files into your working directory. Let's assume that the cs1300 tools are on the H: drive, and that you've just completed the four commands in the previous step. You can copy the necessary files to your working directory with these commands from the DOS command line:

        copy H:\lab\*.cxx
        copy H:\lab\*.h

If your cs1300 software is not on H:, then type the correct drive letter rather than H:. After you've done this copying, list the working directory (with the dir command) and you should see at least these files (though the sizes and dates might be slightly different).

    HEATWAVE CXX         2,135  07-19-99  2:30p heatwave.cxx
    INTARRAY CXX         3,018  07-19-99  2:27p intarray.cxx
    SINEWAVE CXX           704  07-19-99  2:27p sinewave.cxx
    INTARRAY H           2,522  07-19-99  2:27p intarray.cxx

• The files that you copied are C++ programs. The last part of the files' names, cxx, indicates that the file is a C++ program. Some files end with .h, indicating that they are special "header" files. The first program that you'll examine is heatwave.cxx, which computes some information about heating a house, but the real purpose of the program is to demonstrate what a program looks like and how to run a program on a machine.

  Later, during your reading assignment, you can look at how this program was written. But for now you will simply see how to run a program such as this one. The first step in running a program is to run the C++ compiler. A compiler does the task of translating from a programming language (such as C++) to the low level instructions that a computer actually runs. Our compiler is Version 2.7 of the Gnu C++ compiler. You can start the compiler from the DOS command line by typing this command:

      g++ -Wall -gstabs heatwave.cxx -o heatwave
  

• Possible errors:

  1. During the compilation, you might get errors. If you are working on your home machine with permanent installation, then check that the lines added to your autoexec.bat file are exactly correct.

  2. Errors indicating "Out of Environment Space": See the directions for fixing this in www.cs.colorado.edu/~main/cs1300/lab/envspace.html .

Anyway, compile the heatwave program now (as shown above), and then list your files again. You should see these files:

    HEATWAVE CXX         2,135  07-19-99  2:30p heatwave.cxx
    INTARRAY CXX         3,018  07-19-99  2:27p intarray.cxx
    SINEWAVE CXX           704  07-19-99  2:27p sinewave.cxx
    INTARRAY H           2,522  07-19-99  2:27p intarray.h
    HEATWAVE EXE       145,448  07-19-99  2:58p heatwave.exe

Running a Program

The important thing now is that heatwave.exe is an executable file, meaning that you can run it by typing its name at the DOS command line. Do this now. Type heatwave, press return, and then interact with the program.

Using GNU emacs

In order to modify any of your files, you'll need to use one of the text editors. Some of your have probably used a text editor before, such as edit, vi, pico, or even emacs. In the past, we have let students use whichever editor they wanted. But this semester I'd like everyone to use an editor that has a good degree of integration with a compiler and other tools. The editor is called GNU emacs (yes, the G in GNU is pronounced!).

You'll first use emacs to edit heatwave.cxx. In order to start emacs and edit the heatwave.cxx file, give this command from the command line:

emacs heatwave.cxx

The editor will open, and display the current contents of your heatwave.cxx file. Spend one minute using the terminal's arrow keys to browse through the file. You can also use the keys to page down or page up. Each line of the file is part of a small C++ program. The lines near the top are comments indicating what the program does. One of these comments says that the program is an exercise for Irving Forbush. Use the backspace key to erase Irving's name and put your name instead.

After you make this change, you may write out the new heatwave.cxx file, by typing Ctrl-x followed by Ctrl-s, and answering y to the prompt at the bottom of the screen.

Six Pieces of C++

The next step of this lab is to browse through heatwave.cxx a bit. Using emacs, open the file heatwave.cxx. You might notice that emacs recognized the program as a C++ program, and put the characters (C++) in the status line at the bottom. Move through the program and find the following aspects:

1. Comments in C++ are indicated by two slashes in a row. The entire line, after the // is a comment.

2. The program has two include directives that include two C++ libraries:

   #include <iostream> // Provides cin, cout
#include <cstdlib> // Provides EXIT_SUCCESS

   These directive will appear in most every C++ program. The library iostream provides standard input and output functions and devices such as the standard input. The library cstdlib provides several other standard items such as a constant named EXIT_SUCCESS that our program uses.

3. After the two include directives, the program declares a double number named PI. But PI is no ordinary variable; it is a constant variable, declared as shown here:

   const double PI = 3.14159;

   A constant declaration, such as this, is a new feature of C and C++. They are like ordinary variable declarations that are given an initial value, but because they are declared as a const, the compiler will prevent you from writing any statements that change the value of this variable. In this class, our programming style requires the names of all constants to be written in capital letters, allowing constants to be easily spotted.

4. Search through the code and find the heading of the main program, which begins with the words "int ". The word int indicates that the main program computes an integer value and returns this value to the Windows operating system. This may be different than your textbook--many programmers simply declare the main program as a void function (which means that it does not give any final value back to the operating system). But we suggest that your main program returns an int value, since this integer can be used to tell the operating system whether the program was successful or not. For our compilers, a main program returns the number 0 to indicate successful termination. For our g++ compiler, this "successful return value" is defined in cstdlib as a constant called EXIT_SUCCESS. Can you find the return statement in heatwave's main program, which indicates successful termination? (Be warned: older compilers on our DEC machines don't define EXIT_SUCCESS. If you are using an older machine some day, you can still compile by adding the string -DEXIT_SUCCESS=0 immediately after the g++).

5. Some output is quite simple in C++. A basic output statement looks like this:

   cout << "How big is your tree?" << endl;

   The name cout is the "console output device"--the screen. The operator << is the output operator. So this statement sends the string "How big is your tree?" to the console output device, and then the special object, endl, is sent to the console output device. The object endl is an end-of-line, and it also serves to "flush" the output (meaning that the output will be written then and there, rather than waiting for some output buffer to fill up).

6. Some input is also quite simple in C++. A basic input statement looks like this:

   cin >> radius;

   The name cin is the "console input device"--the keyboard. The operator >> is the input operator. So this statement inputs a real number into the variable radius. You'll learn a lot more about input/output in other labs, but this will do for now.

Emacs Indenting

When emacs knows that a file is a C++ program, it can help you to make sensible indentation. To demonstrate this ability, go down into the body of heatwave.cxx, and mess up the indentation on a few lines. Get rid of some spaces or add some extra spaces at the start of a line. Just mess it up some way. Then press the Esc key followed by p. The letter p stands for "pretty-print," and the command will nicely indent your entire program. This command is one of the things that I set up in your emacs initialization file.

Here are the indentation items that I have set up in the initialization file:

• The TAB key: When you press TAB, emacs will attempt to correctly indent the current line.

• The RETURN key: When you press the RETURN key, emacs will indent the current line, insert a blank line, and move the cursor to the right spot to start typing. If the first character of the newline is a bracket, then its indentation will be corrected after you type the bracket. If you find that you need to turn off the annoying behavior of the RETURN key, then go into your .emacs file and put three semi-colons at the front of the lines that look like this:

  (local-set-key [13] 'tab-return-tab)

• The Pretty-Printer: When you press the Esc key and then press p, emacs will nicely indent the entire file.

Now that you know about pretty-printing, you can move to the next step.

Compiling from within Emacs

At the moment you are looking at heatwave.cxx from within emacs. You can actually compile heatwave.cxx without stopping the editor. To compile from within the editor, press the escape key once, press x, type the word "compile", and press return. The "mini-window" at the bottom of the screen will change to this message:

Compile command: make -k

Use the backspace key to erase "make -k", and instead type your usual compilation command, so that the mini-window looks like this:

Compile command: g++ -Wall heatwave.cxx -o heatwave

Then press return. When you press return, the screen will split into two pieces. The top piece is still your heatwave program. The bottom piece is a new window that will contain any error messages from the compilation. During the compilation, there will also be a message near the bottom of the screen indicating "Compilation: run Compiling". When the compilation finishes, the message changes to "Compilation: exit[0]". If there were no compilation errors, you can get rid of the compile window by giving the "one window" command (Ctrl-x followed by typing the digit 1).

Finding Compilation Errors

Compiling from within emacs is a big help when there are compilation errors. For example, let's put a compilation error into the heatwave.cxx file. Go down to the input line "cin >> height;" and delete the semicolon at the end of the line. This is certainly an error! Move the cursor away from this error before you proceed to the next paragraph.

Now, type the compile command again (ESCAPE x compile RETURN). Notice that when you press return, the miniwindow still remembers your compilation command, so just press return once more to get the compilation underway. When the new compilation starts, emacs will ask whether you want to save the changes to heatwave.cxx before compiling. You should answer y (otherwise the compilation would compile the old version of heatwave.cxx, which did not have an error). The compilation will find your syntax error pretty quickly, and display some error message such as "heatwave.cxx:42: parse error before `<'".

With the error message in the compilation window, you can ask emacs to move the cursor to the location of the error. The emacs "find error" command is Ctrl-x followed by the "backquote" key. (The backquote key is the single quote mark that seems to go backward.) Give this command now. Emacs will move the error message to the top of the compilation window, and move the cursor in the program to line 42. Line 42 is actually one line after the real error. (Remember that usually you must move backward from the error line to find the location of the actual syntax error.) Go ahead and fix this syntax error now, and save the file before moving to the next step.

• The heatwave program prints its answer in days. In order to show you how to modify a program, we'll add weeks to the answer. At this point you still don't need to understand how the program is working--it is enough to just understand how to modify a program in the way that these steps describe.

  For the first modification, move to the top part of the program and find the lines shown here:

      double height;            // Height of a tree in feet
      double radius;            // Radius of a tree in feet
      double requirement;       // Cubic feet of wood to heat house for a day
      double volume;            // Volume of the tree in cubic feet
      double days;              // Number of days that tree will heat house
  

  These lines tell the program to use memory locations to keep track of various computational values. We'll tell the program to keep track of one more value, the approximate number of weeks that the tree will heat the house. To do this move the cursor to the end of these lines--somewhere after the words " will heat house". You can move the cursor here with the arrow keys, or by moving the mouse to the location and clicking the left button. Once the cursor is here, press return, which will open up a new line. On the new line you should type:

  int weeks;                // Number of whole weeks that tree will heat house
  

  Try to align your new line with the rest of the program, aligning front of each line, and aligning the slashes (which indicate the start of a comment that is meant to be read by a person).

• For the second modification, find these lines:

      // Computations
      volume = height * PI * radius * radius;
      days = volume / requirement;
  
      // Output days
      cout << "That tree will heat a house for " << days << " days." << endl;
  

  Add the two new lines shown here:

      // Computations
      volume = height * PI * radius * radius;
      days = volume / requirement;
      weeks = (int) days / 7;
  
      // Output days
      cout << "That tree will heat a house for " << days << " days." << endl;
      cout << "Which is " << weeks << " whole weeks." << endl;
  

  The first new line calculates the number of whole weeks by dividing the days by 7. The second new line prints this number of whole weeks.

  Now save and recompile the program (from within emacs). After recompilation, you can click on your DOS window and run the program by typing its name. You might be surprised to see that the number of whole weeks was rounded down. This rounding down to a whole integer occurs whenever a value is assigned to an integer variable.

Printing Your Program

You can print your program from within emacs (from the Tools menu), but many of the Engineering PCs aren't correctly set up to do this. An alternative way to print a program such as heatwave.cxx is to give this command from the DOS command line:
    copy heatwave.cxx lpt1
Note that the last word in this command starts with the lowercase letter l and ends with the number 1 (it stands for "line printer number one").

More About Emacs

• When you are satisfied that the program is running correctly, shut down emacs by pressing its close X in the top right corner. (Or by pressing Ctrl-x followed by Ctrl-c.)

• As the semester progresses, you'll learn a lot more about emacs. For example, you can change the definitions of various keys to match your own preferences for editing operations. You can invoke a debugger from within emacs. For now however, a summary of basic editing commands should be sufficient, available at http://www.cs.colorado.edu/~main/cs1300/lab/emacs.html , and a handy pocket reference guide at. http://www.cs.colorado.edu/~main/cs1300/lab/refcard.html

  Later you might find it useful to also browse the emacs online manual from http://www.cs.utah.edu/csinfo/texinfo/emacs19/emacs_toc.html .

• On the university computers, your should copy your heatwave.cxx from the PC's hard drive to your floppy disk before you leave. Then clear the D: drive so that other students won't have access to your work. As part of our effort to reduce academic dishonesty, please always clear the D: drive before you leave:
  1. Click on the My Computer icon.
  2. RIGHT click on the D: drive.
  3. Select the Format option.
  4. Click Start.
  5. Click OK.
  6. Wait until the format finishes, then click the Logout icon.

• If you have an account on a university machine, such as ucsub or ucsu, you can also transfer files back and forth between the PC and the university machine. You'll use a program called ftp, following these steps:
  1. From the DOS command line, type the command: ftp ucsub.colorado.edu (or use ucsu if your account is on ucsu).
  2. Type your login name and password for the university machine.
  3. To send a file (such as heatwave.cxx) to the university machine, type: put heatwave.cxx
  4. To retrieve a file (such as heatwave.cxx) from the university machine, type: get heatwave.cxx
  5. When you are done using ftp, type the command bye.

  Some of the Engineering PCs also have a graphical version of the ftp program that's available through the Start|Programs menu.