Lab 1

Ideally, before this lab begins, you will have been instructed to visit this link, and create your College of Engineering (CoE) computer account. You need to do this only if you don't have a CSIL account already.

You should already know the following from CS16 / CS24. If not, alert your TA/instructor immediately:

• How to log in with your CoE/CSIL account.

• How to use the Linux computers in:

  • Phelps 3525 (the computer lab where your sections are scheduled in), and
  • Computer Science Instructional Lab (CSIL) at Harold Frank Hall (accessed through an outside door on the side facing the ocean).

  The Linux computers in both places work the same way.

It MIGHT, SOMETIMES, be possible to do SOME of the course work on your own computer that is connected to the Internet. In lecture, I will give VERY brief demonstrations of how to access the CSIL machines over the internet using Windows, Mac, and Linux.

But for some of the assignment, using CSIL is required. You might be able to access CSIL over the internet from your own machine rather than coming to CSIL in person.

At the links below, we give you a "best effort" introduction to "how to do work on your own computer", and then YOU ARE ON YOUR OWN.

• There is no guarantee that this will always work.
• There are too many different OS versions, flavors, configurations, etc. for us to know the ins and outs of every single one.
• If/when you run into difficulties there, we cannot be your tech support. If you have a simple question and we know the answer, we'll tell you, but if you don't, our answer will be: "ok, then do your work in CSIL until you figure it out."

So, please be aware:

• The primary computing environment for this course is the Phelps and CSIL labs.
• The CSIL labs are open from early in the morning to late at night every day of the week.
• Though many labs can be done from your own computer, there may be some that require you to work on CSIL (either over the internet, or coming in person.)

If you are working from your own computer at home or in your dorm, i.e. in not in Phelps 3525, or the CSIL Lab, you may need information on:

• How to access CSIL from Windows, or
• How to access CSIL from Mac or Linux via ssh

We will be using github.com in this course. We have created an organization on github.com where you can create repositories (repos) for your assignments in this course. You may be familiar with GitHub organizations from CS 16 and 24 if you took it with Prof. Mirza. The advantage of creating private repos under that organization is that the course staff (your instructors, TAs and mentors) will be able to see your code and provide you with help, without you having to do anything special.

To join this organization, you need to do four things.

1. If you don't already have a github.com account, create one on the "free" plan.
2. If you don't already have your @umail.ucsb.edu email address associated with your github.com account, go to "settings", add that email, and confirm that email address.
3. Visit https://cs32-linker.herokuapp.com and enter your GitHub username. That will automatically send you an invitation to join the course organization.
4. Click on the invitation link and accept it. You can also go straight to https://github.com/ucsb-cs32-s22 and accept the invitation there.

If you are not familiar with git, I highly recommend learning this skill since this will be extremely valuable when collaborating on large software projects. More information on git can be found here: https://ucsb-cs32.github.io/topics/git/.

I have manually added everyone (using your @umail.ucsb.edu accounts) currently enrolled in the course to the Gradescope system. You should have received an email from the Gradescope system asking you to create a password. Once you follow the instructions to set your password, you should have access to the autograding system. You should see "CMPSC 32" in your courses.

The lab assignment Lab1 should appear in your Gradescope dashboard in CMPSC 32.

This lab may be done solo, or in pairs.

Before you begin working on the lab, please decide if you will work solo or with a partner.

If you decide to work with a partner, read the Working in pairs section of the course webpage.

Once you and your partner are in agreement, choose an initial driver and navigator, and have the driver log into their account.

The first thing we should do is edit our Makefile using an editor like nano, emacs or vim, or whatever text editor you prefer. For example:

• emacs Makefile, or
• vim Makefile, or
• nano Makefile

If you are not familiar with any of the editors, nano is a good beginner-friendly choice, it is not as powerful/extensible as other two but it is easier to use and you see the common shortcuts on the bottom For reading the shortcuts in nano/emacs: ^ means control. For example, ^O means Ctrl-O which is labeled Write Out in nano, so it writes your changes to the file. The shortcuts in these editors may feel strange because they were developed before the common desktop shortcuts got agreed upon.

On the first line of the file, put this, substituting your name and that of your pair partner(s) if applicable, for YOUR NAME(S) HERE, as appropriate:

# Makefile for lab1, YOUR NAME(S) HERE, CS32, F19

Then, leave a blank line, and add the following two lines shown here, so that you end up with this as the first four lines of your Makefile:

# Makefile for lab1, YOUR NAME(S) HERE, CS32, F19

CXX=clang++
# CXX=g++

In the step of this lab where you copied files into your directory, one of the files you copied in was a simple HelloWorld.cpp program. Take a moment to look at the source code of that program, using the Unix less command:

less helloWorld.cpp

The only reason this simple program is here is so we can practice setting up a rule in the Makefile, from scratch, to compile a simple program. Here is what that rule will look like. Add it below the lines we already have, as shown here.

Two important things:

• Note that the first of the two lines that we are adding MUST start in the leftmost column.
• The second of the two lines MUST start with a TAB character, NOT spaces.
• Because of the TAB vs. Spaces thing, copying and pasting this WILL NOT WORK. At the very least, if you copy and paste, you need to delete the spaces in front of ${CXX} and replace them with a single TAB character.

# Makefile for lab1, YOUR NAME(S) HERE, CS32, F19

CXX=clang++
# CXX=g++

helloWorld: helloWorld.o
        ${CXX} helloWorld.o -o helloWorld

What do these two lines mean?

• The first part of the first line, helloWorld: helloWorld.o defines the start of a target. The part that comes before the colon, helloWorld is the name of the target, and is a file that we want to make. We make this file by typing make helloWorld at the Unix command line. The file helloWorld is going to be our executable program.
• The second part of the second line, the part after the colon, helloWorld.o, indicates a list of files that the target depends on. In this case, the executable program helloWorld depends only on the file helloWorld.o.
• ${CXX} is replace with the name of the C++ compiler (either clang++ or gnu++) by dereferencing the symbol CXX. We call this dereferencing because like the * operator used with pointers in C/C++, the $ in a Makefile indicates that instead of using the letters CXX, the Makefile should use what they refer to, i.e. the value of the variable CXX.
• The command ${CXX} helloWorld.o -o helloWorld therefore turns into either clang++ helloWorld.o -o helloWorld or g++ helloWorld.o -o helloWorld depending on the value of the symbol ${CXX},

Now it turns out that helloWorld.o is a file we do not have in our directory at the moment. The following rule is one that will create that, so add this to our Makefile next. Remember that you need to use a TAB character on the indented lines, not spaces; so copying and pasting this WILL NOT WORK.

Leave a blank line after your rule for the helloWorld target, and add these two lines to your Makefile:

helloWorld.o: helloWorld.cpp
        ${CXX} -c helloWorld.cpp

Now we are ready to test this all out. That's what we'll do in the next step.

To test what we have so far:

1. Save your Makefile, and return to the Unix prompt.

2. At the Unix prompt, type make helloWorld and you should see output like the following:

   % make helloWorld
   clang++ -c helloWorld.cpp
   clang++ helloWorld.o -o helloWorld
   % 
   

3. You can now run the helloWorld program by typing ./helloWorld as we have done all along throughout CS16 and CS24. Try that now:

   % ./helloWorld
   Hello, World!
   % 
   

4. Now, if type make helloWorld again, we should see the following output. Do that now. Notice it is different from before:

   % make helloWorld
   make: ~helloWorld' is up to date.
   % 
   

5. Now, edit your helloWorld.cpp program, changing the program by adding a comment with your name(s) between the first two comments:

   // helloWorld.cpp  for UCSB CS32 F19
   // Edited by: YOUR NAME(S) HERE
   // minimal Hello World! program for testing Makefiles
   

   Save the change.

6. Although this change doesn't really affect the program, it is enough for the Make utility to see that the file has been changed. If we now type make helloWorld again, we'll see that the program is recompiled:

   % make helloWorld
   clang++ -c helloWorld.cpp
   clang++ helloWorld.o -o helloWorld
   % 
   

7. Here is what you need to understand, both to work with make, and for your exams in this course:

   • The make utility works from timestamps and dependencies to figure out what does—or does not—need to be relinked and/or compiled.

   So, based on the rules:

   helloWorld: helloWorld.o
           ${CXX} helloWorld.o -o helloWorld
   
   helloWorld.o: helloWorld.cpp
           ${CXX} -c helloWorld.cpp
   

   We have this chain of dependencies: helloWorld.cpp~→~helloWorld.o~→~helloWorld.

   • Here, I'm showing an arrow pointing in the direction in which make needs to make the files.
   • For example, if the makefile has b: a it means b depends on a, and we write a→b to show that we need a's timestamp to be earlier than b's timestamp. If a has a later timestamp than b, it means that b is "out of date" and needs to be remade.
   • Another case is the case when b does not exist at all (e.g. it has never been made at all, or it has been deleted since it was last made.) In that case, we also need to remake b, typically using a as the input file.

   After constructing the dependencies, the make program then looks to see which files already exist (or not), and what the time stamps are, and executes the necessary commands in the order needed.

   That is why the result, when we make a change to helloWorld.cpp is that the rules are done in this order:

   What we see	Explanation
   % make helloWorld	we type make helloWorld to make the executable, and make constructs the dependency chain helloWorld.cpp~→~helloWorld.o~→~helloWorld
   clang++ -c helloWorld.cpp	From the dependency chain, this is the first thing that must be done. It must be done because helloWorld.cpp is "newer" than helloWorld.o. The command recompiles helloWorld.cpp into helloWorld.o~—the ~-c flag indicates "compile only; do not link", so we get a helloWorld.o file as the result.
   clang++ helloWorld.o -o helloWorld	This is the link step. It is done because NOW helloWorld.o, which is newly remade from the previous step, is NOW newer than the executable helloWorld. The command relinks the helloWorld.o code (the machine language version of ONLY the code from the helloWorld.cpp file) with the machine language versions of the code in the standard libaries (e.g. the code for the iostream library that provides cout, endl, among other things.) The result of this command is a new version of the executable file helloWorld
   %	The bash prompt indicates that the command is complete and the shell is ready for our next command.

   So what should you know from this for your exams? These items suggest a few of things you might be asked about.

   • Be able to explain the difference between Makefile commands that compile, vs. commands that link.
   • From this step of this lab, be able to write the syntax of Makefiles commands for compiling and/or linking a simple standalong C++ program. (Later we'll also learn how to write Makefiles for complex program consisting of multiple source files.)
   • Be able to explain how Makefiles construct a chain of dependencies based on timestamps to determine what needs to be recompiled or relinked.
   • Be able to explain the variables such as CXX are dereferenced when the $ is put in front of them, and they are surrounded by braces.

Sometimes we may want to remove all of the executable and .o files from our directory. As you may recall from Makefiles that were supplied to you in CS16 and CS24, that is traditionally done with a clean target that allows us to type make clean.

Here are some examples of when that is appropriate:

• When we are switching from one compiler to another, e.g. from clang++ to g++—the .o files produced by one compiler are not compatible with the other.
• When we have made signficant changes to the interface between multiple parts of a program that uses separate compilation, i.e. multiple .cpp files (and hence .o files). By "interface", here we typically mean the .h files that specify definitions of structs, classes, and function prototypes. If those have changed, a "make clean" may be a good idea.
• If we are about to copy the files to another directory (e.g. to share with a pair partner), or if we are finished with a project and want to save disk space. We really only need the source files (.h, .cpp and Makefile). The .o and executable files can always be remade if/when they are needed.

A clean rule looks like this, and is typically at or near the end of your Makefile. Add this to your Makefile now. Note that the second line starts with a tab, and that there should be a blank line after your rule.

clean: 
        rm -f *.o helloWorld

make clean almost always runs the clean rule. In general, any Makefile target with no files specified after the colon is always run when it is invoked. Technically, there is one exception: when there is a file that has exactly the same name as the rule in the file. So it is best to avoid having any executable or other file with the exact name clean. In such a case, the make clean rule would never be invoked. That's what we call a corner case -—it rarely happens in practice, but is possible in theory, so its good to keep in mind.

The fact that this rule has clean: as the first line with nothing after the colon (:) means that clean does not depend on anything. That has a special meaning in a Makefile—it means that every time we invoke make clean, the commands following the first line of the rule will always be executed. (Well, almost always. See the note at right for an exception.)

So make clean always results in the command rm -f *.o helloWorld being executed, which removes all .o files (the * being a wildcard that matches any filename.

Why rm -f rather than just rm?

• We could also specify /bin/rm rather than rm to declare exactly what version of the rm program (the Unix delete program) to use. This is generally safer, in case someone has redefined rm to do something different than we might expect.
• The -f option stands for force and says "do this even if there is a problem". A problem might be, for example, that there aren't any .o files or helloWorld files to remove. Without the -f option, the rm command might given an error message. With that option, it just works and doesn't complain.rm complaining is good default behavior when calling rm directly, you would not want to accidentally delete some write-protected files or a whole directory

% make clean
rm -f *.o helloWorld
% make helloWorld
clang++ -c helloWorld.cpp
clang++ helloWorld.o -o helloWorld
% make helloWorld
make: ~helloWorld' is up to date.
% 

Now let's test it out. Run make clean, then run make helloWorld twice.

Your output should look like what you see at right.

• You will see that when we type make clean, the rm -f *.o helloWorld command is executed.
• When we type make helloWorld the first time, the commands to compile and link are executed.
• When we type make helloWorld the second time, we get a message that ~ ~helloWorld' is up to date. ~. This is because make examined the whole dependency chain (helloWorld.cpp~→~helloWorld.o~→~helloWorld), and found that nothing needed to be done—all of the files needed were present, and all the timestamps were in the correct sequence.

Be able to predict how typing make clean will affect what happens when make commands are invoked, and be able to explain why.

So now, we are almost ready to run our ./lab1Test program and start working on getting test cases to pass. BUT FIRST, we need to adjust our make clean rule.

Here's how it looks now:

clean: 
        rm -f *.o helloWorld

Here is how it needs to look instead:

clean: 
        rm -f *.o helloWorld lab1Test

We need to add the lab1Test executable to the make clean rule. In a future lab, we'll see how we can factor out parts of this to make keeping a Makefile up to date less tedious.

Take a minute to read UCSB's Academic Integrity Policy: http://judicialaffairs.sa.ucsb.edu/academic-integrity

It is important that your code is a product of your work. The only time you are allowed to share code is between you and your pair programming partner. You may not distribute or share your solution to any other student. You may not base your code on other students' code (this includes retyping someone else's solution, make slight modifications, and submit it as your own work).

We will also test your code against other data files too—not just these. So while you might be able to pass the tests on Gradescope now by just doing a hard-coded "cout" of the expected output, that will NOT receive credit.

To be very clear, code like this will pass on Gradescope, BUT REPRESENTS A FORM OF ACADEMIC DISHONESTY since it is an attempt to just "game the system", i.e. to get the tests to pass without really solving the problem.

I would hope this would be obvious, but I have to say it so that there is no ambiguity: hard coding your output is a form of cheating, i.e. a form of "academic dishonesty". Submitting a program of this kind would be subject not only to a reduced grade, but to possible disciplinary penalties. If there is any doubt about this fact, please ask your TA and/or your instructor for clarification.