This lab exercise will get you started using the
an editor called GNU emacs
and a C++ compiler called g++, all in the Windows environment.
If this editor and compiler are not installed on your machine, then
you may obtain them from
www.cs.colorado.edu/~main/cs1300/README.html.
.
One small warning: This was originally written for our second semester
class, so there might be aspects of programming that you don't fully
understand. Don't worry about that just now.
-
Create a Working Directory
-
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 mine on my
D: drive and called it D:\exercise.
-
Starting a DOS Session
-
Some of the work is easier to carry out from the DOS command line.
So open up a DOS window (usually by clicking on the Start menu,
then select Programs, and select the MS-Dos command window).
Click in this window and change to your working directory that
you created in the previous step. For example, I typed this
DOS command and pressed return:
cd D:\exercise
-
Copying and Listing Files
-
Now you'll copy some files into your working directory. Assuming
that you installed the cs1300 tools in the directory c:\cs1300,
you can copy the necessary files to your working directory with
these commands from the DOS command line:
copy c:\cs1300\manuals\lab\*.cxx
copy c:\cs1300\manuals\lab\*.h
After you've done this copying, list the working directory (with
the dir command) and you should see 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.H
-
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 a small program called 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, and
exit emacs (with the exit command Ctrl-X followed by Ctrl-C).
When you exit, emacs will ask whether you want to save the changes
to the file. You should type y.
-
Compiling a Program
-
The next steps will ensure that you know how to compile and run a
C++ program. Even if you already know this, go ahead and go through the
steps--it won't take long and you'll probably pick up at least one
tip.
The program that we'll use is heatwave.cxx (from the previous
step), and the compiler is the Gnu C++ compiler.
This compiler is called g++, and you
can compile heatwave.cxx with the simple command: g++ heatwave.cxx--but we
suggest that you use a more complex C++ compile command:
g++ -Wall heatwave.cxx -o heatwave
During the compilation, you might get Borland C++ error
message. This means that g++ is interfering with your Borland
compiler. To fix the problem, make sure that this line is last in
your autoexec.bat file:
PATH=%PATH%;C:\Language\cs1300\bin
The switch -Wall instructs the compiler to list all warning messages.
These warning messages usually indicate programming errors, and we'll
forbid warning messages in your programs. At the end of the compilation
line, the arguments "-o heatwave" indicate that the compiler should put
its result (the "object code") in a file called heatwave.exe. If you don't
specify a location for the object code, then the compiler places its
result in a file named a.exe, which is not a particularly useful name.
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 141,280 07-19-99 2:58p heatwave.exe
-
Running a Program
-
Anyway, the important thing now is that heatwave is an executable file,
meaning that you can run it by typing its name. Do this now. Type
heatwave, press return, and then interact with the program (which
computes how long a tree will heat a house).
-
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:
-
Comments in C++ are indicated by two slashes in a row. The entire line,
after the // is a comment.
-
The program has two include directives that include two C++ standard
libraries:
#include <iostream.h> // Provides cin, cout
#include ^lt;stdlib.h> // Provides EXIT_SUCCESS
These directive will appear in most every C++ program. The library
iostream.h provides standard input and output functions and devices such
as the standard input. The library stdlib.h provides several other
standard items such as a constant named EXIT_SUCCESS that our program
uses.
-
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.
-
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 stdlib.h 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++).
-
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).
-
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 Ctrl-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 file
(normally Ctrl-p just moves the cursor to the previous line.)
Here are the indentation items that I have set up in the
.emacs 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 Ctrl-p in a C or C++ program,
emacs will nicely indent the entire file. If you find that
you need to turn off this behavior (so that Ctrl-p just moves
the cursor up), you should go into the .emacs and put
three semi-colons at the front of the lines that look like this:
(local-set-key [16] 'indent-all)
Now that you know about pretty-printing, you can exit
the editor and 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 "on line 42".
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 quit emacs (saving the file).
-
More About Emacs
-
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/lab/emacs.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
.
-
Separate Compilation of the intarray Module
-
Small programs can be written in a single file, such as heatwave.cxx.
Larger programs should be broken into manageable pieces. Each piece can
be developed, compiled, and tested on its own--all in a manageable size.
Normally, such a program will have one file that is the main program, and
one or more "modules" that provide something for the main program to use.
Each module comes in two parts: (1) a header file that provides a
prototype for each of the module's functions, and (2) an implementation
file that provides the actual implementations of the module's functions.
You'll see this separation over-and-over again. As a first
example, one of the files that you have already copied is such a
module called intarray.
The intarray module provides some functions for manipulating arrays of
integers. You can browse through the header file to see exactly what's
present. After browsing for a while, exit your editor and give this
compile command:
g++ -Wall -c intarray.cxx
The -c switch tells g++ to compile only, and not to create an executable
file. In fact, you can't create an executable file because intarray.cxx
does not have a main function. When a module is compiled like this, with
no main function, you need the -c switch. Also, there is no need to use
the -o switch, since you are not creating an executable file.
With the -c switch turned on, intarray.cxx is compiled, and the resulting
code is placed in a nonexecutable file named intarray.o. After your
compilation, do a directory listing to make sure that intarray.o is present.
-
A Program That Uses the intarray Module
-
Once the intarray module has been compiled, any program can use the items
it provides. I've written a program that uses the intarray
module.
The program is the file sinewave.cxx, which you copied earlier.
Use the editor to browse through the file.
You might not understand all of the program, but notice the include
directive:
#include "intarray.h"
This include directive is all that's
needed in the code of the program that uses the intarray module.
Notice that the intarray include directive uses quotation marks rather
than angle brackets. The angle brackets (such as #include <iostream.h>)
are used only for one of the standard header files. The quotation marks
are for one of your own header files. (The compiler looks for these two
different kinds of header files in different places).
Anyway, you can now quit the editor and compile the sinewave program, with
the compilation command:
g++ -Wall -c sinewave.cxx
This compiles sinewave.cxx, but it does not yet create an executable file.
Instead, it puts the compiled code in a file named sinewave.o. In the next
step, you'll put all the pieces together, finally creating an executable
file.
-
Linking Several Pieces Together
-
Your total executable sinewave program will include three pieces: (1) The
compiled code for the intarray module, (2) the compiled code from
sinewave.cxx, and (3) some compiled code for mathematical functions that
are part of the C++ math library. (You might have noticed the use of the
math library in sinewave.cxx by the include directive #include <math.h>.)
We can put all three pieces together with one last compilation command:
g++ sinewave.o intarray.o -o sinewave
We did not use the -Wall option because we are not compiling any new
code--just putting together previously compiled pieces. Some
versions of the compiler also require you to put "-lm" to include
the math library. But that's not needed for our compiler.
At the end, the -o option tells the
compiler where to place the executable file that it creates. After this
compilation you'll have an executable file named sinewave,exe, and you can
run it. Give it a try now by typing the command
sinewave
-
Cleaning Up
-
If you are working on a university machine and you want to save
your files, then you should now copy all files from your working
directory to a floppy disk. Then delete the files from the D:
drive.
Later in the semester, your instructor might show you how to save
files on your permanent account on one of the other university machines.
