CISC181 lab04, Spring 2006
(section 010-015, Instructor: P. Conrad)

Introduction

This lab is an introduction to project 1, the drawingMaker project.

The main purpose of this lab is to get you ready to do project 1. In fact, when you finish this lab, you'll be already part of the way done with project 1.

Learning objectives

By the time you finish (lab04 + proj1) you'll have demonstrated your ability to:

1. Write data to the screen using cout, and to external files using ofstream objects.
2. Modify existing function and create new functions that use parameters of type int and double (passed by value), and call these functions where appropriate.
3. Modify and create functions that pass parameters of type ostream (by reference).
4. Use for loops, nested for loops and if/else.
5. Use Makefiles and separate compilation to manage a project that is moderately complex in size.
6. Make files available on the web.

You'll also acquire the following skills.

1. Using gnuplot to create graphics.
2. Controlling the creation of gnuplot files and data file for gnuplot from a C++ program.
3. Basic principles of working with 2D graphics (e.g. using sine and cosine to determine x, y coordinates, and scaling and translating figures in a cartesian plane.)

Step-by-Step Instructions

Step 1: Preview the finished project for project 1

Go to the web page http://www.udel.edu/CIS/181/pconrad/06S/pngFiles/proj1 and look at the .png files you see there. Each is a picture that you will draw as part of project 1. You'll draw these pictures by making some changes to a C++ library stored in a pair of files called drawings.cpp/drawings.h, and then writing some C++ programs that utilize this library.

In each case, you'll draw a picture that looks just like the one shown—with one exception: the file called drawPhillsPicture.png will be called drawXXXXsPicture.png in your directory, where XXXX is your own first name. The figure drawXXXXsPicture.png will be different from mine; it will be an expression of your own creativity. You'll read more about that when you look at the instructions for project1. For now, I just wanted you to start by looking at these files; lab04 is a warm-up for project 1, and I wanted you to have an idea of where this lab is headed.

Step 2: Now preview the finished product for this lab and understand what you need to do

Now look at the files in each of two web links below. They show a set of .png files produced by the code that you can copy from the lab04 subdirectory on the course web page (under the labs link.) The "before" pictures show the .png files that are produced when you run the programs as they are right now. The "after" pictures show what the png files should look like after you are finished with some changes to the C++ code.

You should notice several differences. The following tables explains the differences, and where you will be making changes in the C++ code that result in the "after" pictures instead of the "before" pictures.

Notes on this table:

1. You'll add two lines and a star to make the Texas flag. The drawTexasFlag function has a comment that mentions a web site where you can get more detail on the exact proportions of all the elements of the flag. Note that for now, the star can be a simple five pointed star (it doesn't have to be the outline star as explained in lecture, and illustrated in the proj1 png file web page.) There is already a routine in the drawings.cpp file that you can use to draw this five pointed star.
    
   
2. The finished drawNightFlags.png file has 6 stars, but the starting point drawNightFlags.png contains only three. Your next job is to add some more calls to drawStar into the drawNightFlags.cpp file so that there are at least six stars in the sky.
   
   
   You can rearrange the stars, or change their values (size, number of points, position, skip value, etc.) to make them look nice. They don't have to match mine exactly—in fact, it would probably be nicer if they didn't. You just need six stars scattered in the sky somehow. Use your imagination.
   


3. Your last job is to add a new function to draw a french flag, and a call to that function inside drawNightFlags.cpp. That will add the French flag to the drawNightFlags.png file. You'll need to add a drawFrenchFlag prototype inside the drawings.h file, and a function definition inside drawings.cpp, and then a call to that function inside drawNightFlags.cpp.
    
   This should re-enforce a key concept you need to be sure you have at this point in the course: the difference between and among function prototype, definition, and call. 

Note that this step is just "understanding what you are supposed to do". Before you actually dive in, look over steps 3 and 4.

Step 3: Coping the code and understanding the "Makefile"

To get started, create a directory for lab04, with the command:

mkdir ~/cisc181/lab04

Then use the following command to copy all the files you'll need for this lab into your lab04 directory:

cp -r /www/htdocs/CIS/181/pconrad/06S/work/labs/lab04/* ~/cisc181/lab04 

Then change your working directory to the lab04 directory, and list the files in the directory.

cd ~/cisc181/lab04
ls

You'll see a file with the name "Makefile". This file helps to "customize" the actions of the "make" command to help you complete the project more efficiently. To see how this work, first, try typing the following command:

make all

This will compile all the routines, and then run shell scripts that create each of the .png files.

Then, try typing the following:

make install

That will create your ~/public_html/cisc181/lab04 directory, copy all your .png files into that web directory, and set the permissions correctly. As you can see, the Makefile file automates a lot of the tedious work of maintaining a complex software project.

Look at the contents of the Makefile, and try to understand the "make install" rule. The -p flag on the mkdir command makes sure that in case the directory already exists, no error message is created. the "-m 755" option builds a "chmod" for the directory into the mkdir command. Make sure you are familar with both of those Unix commands for the next exam (ask your TA and/or your instructor for help if you are not sure.) Ask your instructor to explain the contents of the Makefile in lecture.

You won't need to modify the Makefile for this lab. However, you'll need to modify it for project 1, so try to understand all the steps in the Makefile and what they do. Ask your TA for help during lab, and your instructor for help during lecture if you have questions. Your Anderson textbook also has information about Makefiles.

Step 4: Now, make the necessary changes to the C++ files

Make the changes in drawings.h, drawings.cpp, drawNightFlags.cpp.

Use the "make clean", "make all", and "make install" commands as needed to see the necessary changes take place in the .png files. You can use a web browser to check the contents of those files as you work.

Note that you can just type "make" instead of "make all".

A side note: note that in the drawings.cpp file, I used "#include <iomanip>", "using std::setiosflags" and "setiosflags(ios::fixed)". This is apparently what you have to do to get around the problem that some older version of g++ don't support the "fixed" keyword properly.

Once you have finished this, and all of your drawings look right, and your code is ready to turn in, you have two more things to do for this lab: update some links on your web page, and create a "tar file" to submit. The remaining steps in this lab will walk you through all of that.

Step 5: Some background on HTML that you need before you continue.

You'll be adding a "link" to your lab04 directory on your web page. This section explains how to do that.

Note: Even if you already know a lot about HTML, read this section. It contains terminology that might be on the next two exams.

First, as background, let's clarify the difference between your personal web page, which is controlled by the file ~/public_html/index.html, and your CISC181 web page, which is controlled by the file ~/public_html/cisc181/index.html. If I direct you to add something to your CISC181 web page, you should use emacs (or vi) to change the file ~/public_html/cisc181/index.html.

Next, let's understand how to "add a link" to a web page. Up until now, you've added links by following examples. Here's the "theory" behind adding a link.

In HTML (the language used to describe web pages), an "element" is anything in the following form:

<foo> ... </foo>

In this case, foo is the name of the element. The element is tagged with a start tag such as <foo>, and a close tag such as </foo>. The name of the tag is surrounded in with the less than (<) and greater than (>) signs, i.e. < >. These symbols are often called "angle brackets" in this context, since they are not being used to signify less than or greater than.

Some elements are defined with tags that contain attributes. An attribute is listed as part of the opening tag. For example, to make the words my lab04 files link to the directory ~/public_html/cisc181/lab04, one would include the following text in the HTML file:

Note that the <a> open tag includes the text href="http://udel.edu/~userid/cisc181/lab04". This is called the href attribute of the <a> tag (a stands for anchor). The href attribute lists the URL of the target of a link. The </a> close tag show where the link ends. This form of link is called an "absolute" link becaues it links directly to a specific absolute location. You could move this HTML code to any location on the web and it would still point to the same place.

Another way to specify this link is with a so-called "relative" URL. The relative URL is shorter to type because it relies on the fact that you know something about where the HTML file is located. For example, suppose you know that your HTML code is stored in the following file on strauss: ~/public_html/cisc181/index.html. In that case, you can specify a link to the files in ~/public_html/cisc181/lab04 with the following HTML code:

Note that the "dot slash" (.) refers to the "current directory", just like it does in Unix commands. So, ./lab04 refers to the lab04 subdirectory of the current working directory, i.e. the one where this index.html files is located, i.e. ~/public_html/cisc181. This way of specifying the directory is shorter, and it can also be more efficient. An key difference with this technique is that if the HTML file is moved, the link it contains doesn't point to the same place anymore; it will point to the ./lab04 subdirectory of whatever directory that html file is moved to. (So, that's one more thing you need to know for your next exam: the difference between an "absolute" link and an "relative" link.)

Step 6: Link your CISC181 web page to your lab04 files.

In this step, you will add a link to on your CISC181 web page that helps your TA find your lab04 files. By this point in the lab, the subdirectory ~/public_html/cisc181/lab04 should already exist, it should contain your two .png files, and those files should be readable on the web.

So now, make a link to that directory (which is accessible by the URL http://copland.udel.edu/~userid/cisc181/lab04) on your CISC181 web page.

As a reminder, your CISC181 web page is the file ~/public_html/cisc181/index.html, and is referred to by the URL http://copland.udel.edu/~userid/cisc181.

Step 7: Creating a tar file of your finished product.

Don't start this step until you have finished all your programming, and are ready to submit your work. However, don't wait until this last minute; you may need some time to figure this part out.

A "tar" file is a file that allows an entire collection of files to wrapped up into a single file.

You may be familiar with "zip" files, which are often used to distribute software packages on Windows PCs, or "sit" files which are used to distribute files on Macintosh computers. The files known as "tar" files are similar.

(A bit of history: "tar" originally stood for "tape archive". It's still the format sometimes used to store backup files on tape drives.)

To create a tar file from your lab04 files, follow these steps:

1. Change into your ~/cisc181/lab04 directory and do a "make clean". This is very important! If you don't do this step first, you'll end up with a tar file that will be huge; this will annoy your TAs greatly and cause your final grade to be lowered.
   
2. Change directory to one directory above your ~/cisc181/lab04 directory. You can you can use "cd .." to move up one level from your current directory, or you can use "cd ~/cisc181" to go there directly.
   
3. Use the command:
   

     tar -cvf lab04.tar lab04

   This command says "create a new tar file named lab04.tar"
   (that's the -cvf lab04.tar part) and put all the files from the subdirectory lab04 into it.
   
4. To test your file, create a new subdirectory called ~/cisc181/test, and cd into it.
   Copy your lab04.tar file into that directory. Then use the command:
   

     tar -xvf lab04.tar

   This command should expand the lab04.tar file, and leave you with a new subdirectory ~/cisc181/test/lab04 that contains all of the files from your lab04 directory. Change your working directory into that directory and use the "ls" command to list your files. Then, try the "make clean", "make all" and "make install" commands and make sure that everything still works properly. If so, then you can now submit "lab04.tar" as your submission to WebCT.
   
   Note: you have reached a milestone in your development as a Unix programmer: you have created your first "package". A package is a tar file that contains source code, and a Makefile. Sometimes these packages are called "tarballs", and they are how professional Unix programmers distribute their software.
   

Finishing up and Submitting

For Steps 1-7

1. Make a script called lab04.txt. In your script, you should cd into your lab04 directory, cat all of your .cpp files and your .h file, and then cat your Makefile. Finally, do following three commands: "make clean", "make all", and "make install". That completes your script.
2. Then, submit your lab04.txt and your lab04.tar file to WebCT. Be sure that your lab04 tar file was created right after doing a "make clean". If you create it correctly, the size should be no more than a couple hundred KB, maybe less. (You can use the unix command ls -lh to see how large each file is in bytes, KB, MB, or GB.)
3. Print your lab04.txt file and give it to your TA.
4. Make sure you have a link on your CISC181 web page to your ~/public_html/cisc181/lab04 directory.

Grading: 100 points total

Next Steps

• Now you are ready to start on Project 1.

You will soon find the description of Project 1 in the project directory of the course web site.

(If you are finished with lab04, and Project 1 isn't "available" yet, email your instructor.)