CSCI 1300 - Exercise 1
Using GNU Emacs and G++

When and Where to Start this First Exercise
...and What To Do If You Missed the First Recitation

PC Labs in the
Engineering Center
CR 235    CR 239
CR 244    CR 252 (24 hours)
It is best to start a lab exercise during your assigned recitation period. If you run into any immediate problems, one of the instructors will be able to help. However, some of you might have missed your assigned time during the first week. If so, then you'll need to work on your own home machine or go to one of the PC labs on your own to get started.

Required Completion Date

This exercise must be completed as soon as possible after your first recitation. Otherwise you won't have time to complete the first homework (which is due the next week).

Set up Your University Account and Identikey

Start the CS1300 Software

Create a Working Directory

At the end of the installation step, you should have a black window open where you will carry out all your work. The prompt message in the black window should list your Documents folder or Home folder as the current working directory (such as C:\Users\michael\Documents or C:\Users\michael). If it does not list this, then please ask your TA how to change to your Documents folder (I do it with the command "cd /Users/main/Documents" because my identikey name is main.)

Within that folder, you will create a separate subfolder for today's work. I called my subfolder lab1, and I created it and moved into it with these commands typed in the black window:
  mkdir lab1
  cd lab1

Always put your work in a subfolder (rather than at the top of the Documents folder). It's also useful to have a Windows Explorer window open in this subfolder, so do this now by these steps: From the Start menu, choose Computer. Then click on the drive that you are using (usually C:), click on Users, click on your name, and click on your subdirectory.

Copying and Listing Files

Now you'll download a file into your working directory. Open a browser (the instructions here are for the Firefox browser). Go to www.cs.colorado.edu/~main/cs1300/lab/. From here, you'll need to download the file called heatwave.cxx (right click and choose Save Link As). After the file downloads, please right click on the file in the Downloads window and choose Open Containing Folder. Then drag and drop the file from there into your working directory. Ask your TA if you are uncertain how to do this on your machine. You can then minimize this window for now, and open it again when needed.
Compiling and Running a C++ Program
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 black command window. 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 main". The word int indicates that the main program computes an integer value and returns this value to the Windows operating system. 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 bgi++ 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. (If you want to indicate an unsuccessful program, you can return EXIT_FAILURE instead).

  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: bgi++ -Wall -g heatwave.cxx -o heatwave.exe

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.

Modifying the Heatwave Program
Printing a Program

You can print a 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 black command window:

notepad heatwave.cxx
This will open the notepad program with heatwave.cxx, and you can choose the print option from the File menu. Don't edit your program within notepad, though, because it's not set up to provide much help such as pretty-printing and compiling and debugging.

More About Emacs

Backing Up Your Work