CSCI 159 lab 1 (inlab exercise), F24N01/N02

CSCI 159 Lab exercise 1, F24N01/N02

Introductory lab notes

Most lab exercises will consist of two parts:

Part 1 generally involves editing a basic C++ program used to practice with a few new core features: this portion is usually detailed in a very step-by-step fashion.
Part 2 generally involves a larger program that you will design and build yourself (with some extra requirements to make sure people are getting appropriate practice with those core new language features)

Ideally you complete all of part 1 and get started on part 2 while you're in your weekly lab, then complete and submit it on your own time over the following two weeks (specific deadlines can be found on the main labs page).

For this first lab, however, the entire lab will be done in a very paint-by-numbers fashion to introduce the core tools and processes we'll need to follow for the rest of the term, and you'll finish and submit it prior to the start of your next lab (a week later).

In this first lab we'll also have to go through a couple of setup steps to get your account and files/directories set up and organized for the term.

For each lab, there are several key C++ syntax elements you'll need to be familiar with.
The core part 1 syntax elements can be found here.

NOTE THAT I'LL BE DISTRIBUTING YOUR CSCI LOGIN IDS IN THIS LAB
you will be unable to login on our linux servers to work on your labs until you have this information

The objectives for this lab are to master some basic linux skills, learn how to obtain and submit labs, and learn how to edit, compile, and run C++ programs in a linux environment,

The layout of instructions for this part of lab 1 will be quite different than for the remaining labs. In this lab, instructions are laid out in a very step-by-step fashion to walk you through an introduction to our linux labs, your accounts, and the use of C++.

Be sure to go through each of the steps carefully, and in the order given, successfully completing each step before moving on to the next one.

1. Get logged in to your CSCI account and open some needed tools

(you'll do this every time you want to work on one of your CSCI labs)

Using your account id ( available from the course instructor), follow the instructions below to login on one of the linux pcs in lab 102.
Use the account information (linux username and initial password) given to you by the instructor to sign in on one of the lab machines
YOU WON'T SEE THE CURSOR MOVE WHILE YOU ENTER YOUR PASSWORD,
keep typing normally anyway, and hit enter when you're done
This first time signing in it will probably ask you to set a new password, follow the usual secure-but-I'll-remember-it approach to passwords.
Instructions on how to change your password later, or how to deal with a forgotten password, are provided on the technotes page.

Once you're logged in, open a web browser and go to our labs URL:
csci.viu.ca/~wesselsd/courses/csci159/labs.html
There are two browsers, each accessible through the Applications menu on the upper left of the screen (Applications->Internet->Chromium or Firefox)
Follow the link to lab 1, which should take you to this page.
Open a command (terminal) window through the applications menu:
Applications->System Tools->Mate Terminal
In this window you'll be able to enter linux commands.
Most lab sessions you'll go through this same cycle of logging in, opening the browser to the current lab, and opening a terminal window to actually work in.

THE PRINTED HANDOUT ENDS HERE, THE REST OF THE LAB INSTRUCTIONS FOLLOW BELOW ON THE WEB PAGE

2. Practice some basic linux:

Whenever you connect to the linux server you'll be started in the home directory (like a Windows folder) for your account.
Enter the command ls to list the current contents (file and directories) of your account.

For those of you who have taken CSCI 159 previously: We're going to be creating a csci159 directory in your account, but you may already have one left over from the fall. If so, we'll rename your old one so you don't run into conflicts with our new one. To do so, enter the command
mv csci159 old159

You can create new directories using the mkdir command and the name of the new directory. Try creating one named csci159:
mkdir csci159
Linux takes a "no news is good news" approach to command success: if the command succeeded it will simply give you a new prompt.
If the command succeeded, it will have created the new directory inside your current directory. Try the ls command again to see if it shows up.
We can move from one directory to another using the cd command and the name of the directory we wish to go to, try
cd csci159
(by default it assumes you're giving the name of a directory inside the current one).
If it succeeded, try ls again, which should show the directory is empty so far (unless you've taken the course previously).
We can display the full name of our current directory location using the command pwd (for print working directory).
We can go back "up" one layer, in this case to our home directory, using cd ..
We can also jump directly to our home directory from anywhere else using the command cd (with no arguments)
Use either of the two approaches to get back to your home directory, then try pwd and ls again to confirm you are where you want to be.

3. Get a special file that we'll use for the rest of the term

We're going to copy a special 'makefile' from the instructor's account to your home directory.

This allows us to bundle up sets of linux commands, and run them through a program called 'make'. This semester I'll be providing a variety of makefiles to simplify the process of obtaining, compiling, and submitting your lab exercises.

This very first makefile belongs in your home directory and will be named make159. Instructions for obtaining using it are as follows:

Make sure you're in your home directory by entering the following command
cd
To copy the file from the instructor account to your own, first make sure you're in your home directory (e.g. using cd) then issue the following copy command precisely:
cp ~wesselsd/make159 make159
Use the ls command afterwards to check the file is present and named correctly.

We'll now run the make program, telling it which makefile to use (i.e. make159) and what we want it to create. In this case, that will be a directory csci159/lab1 (i.e. a lab1 directory inside your csci159 directory).

The full command to do this is
make -f make159 csci159/lab1
(The -f tells it we're going to specify the name of the makefile, make159 is the name of that file, and csci159/lab1 is the thing we're telling it to create.)

If the command is mistyped then you'll likely get a series of complaints from the make program, simply check the precise command and try again.

If the command is successful then you'll see a series of git and ssh responses as it sets up a variety of files and directories based on the instructor's git repository. (Git is a tool heavily used for version control and for sharing code bases.)

What is the makefile doing right now?
The instructor has created a special directory containing the starting files for lab 1, including starter code and its own makefile, which in turn allows you to automatically compile and submit your C++ code for lab 1.

If you'd like a look at a makefile's content you can dump it onto the screen using the cat command and the filename, e.g.
cat make159

If you're curious about the workings of git for assignment submission (i.e. what the makefile is doing for you) there is a short rundown linked from the technotes page.

4. Go to today's lab directory and try out the starting code

Go to your home directory (you're probably already there, this is just a precaution to make sure I get everyone starting from the same place):
cd
Change from the current directory into your lab1 directory and see what's there:
cd csci159/lab1
ls
Hopefully you'll see files named makefile and lab1.cpp
lab1.cpp is the starting C++ source code file for this week's lab exercise.
Try using make to compile the program into an executable named lab1x (note that those precise names are encoded in the makefile, so spelling and capitalization must be exact):
make lab1x
The make program will show you the commands it is running, in this case a g++ command to compile the program.
If successful, ls should now also show a file named lab1x, the newly created executable.
Hopefully the file contains no errors (I didn't intend to include any), so it should compile cleanly (no error or warning messages) and we can try running it:
./lab1x
At the moment the program should simply display a small message then end.

5. Try editing, compiling, running, and submitting the starting code

For now we'll use an editor called pico to modify the .cpp files we're working with, but later you can experiment with a variety of others and find one you like.
In your terminal window, type the following command exactly
pico lab1.cpp
The pico editor will open in the terminal window you have open, and should show the current content of your lab1.cpp (a C++ program with a simple main routine).
(You'll probably want to play with the colour scheme some, the default is pretty bad.)

You can edit normally in pico
Change the message inside the cout text string to some new welcome message, then save.
Once you've made the change, to save use control-O (it calls it write-out) and to exit use control-X.

We compile our altered program using the command below (now that we're out of pico and back in the terminal window)
make lab1x

make recompiles lab1.cpp to create a new lab1x using the g++ compiler, using a command such as
g++ -Wall -Wextra lab1.cpp -o lab1x

If it gives error messages then we broke something editing the cout text string -- see if you can figure out the nature of the problem based on the file content and the g++ error message, but don't hesitate to ask for help!

As an alternative to opening and closing pico all the time, you can open a second terminal window, do a "cd csci159/lab1" in that one to make sure they're both in the same directory, then run pico in one and type your linux make and ./lab1x commands in the other.

Keep going through the edit/compile cycle until it compiles cleanly, then try running the updated executable to see if your new message appears correctly
./lab1x

Try submitting the exercise

We'll use a make command to turn in your work:
make submit

If successful, you'll see a variety of status updates as it uses the git version control program to copy your updated directory contents to a location where the instructor can obtain/mark it. You can do this as often as desired, each new submit simply replaces the previous one.

Each time you do a "make submit" git is used to store the current state of the directory and copy it to the instructor-accessible location. It only works if you're in the correct lab directory, e.g. csci159/lab1 today, and the instructor can only see changes after you submit them, so be sure to do a make submit after your final set of changes for any lab.

6. Try closing things up and logging out (then we'll sign back in to do more work)

You've now completed one cycle of our typical lab process, so next we'll try logging out, logging back in, and getting back to our lab1 code to work on it further.

Exit the editor, then to logout of the PC select "logout yourusername" under the system menu at the top of the screen.

Always remember to logout, not lock screen, when you leave.
1. if you forget to logout then whoever comes in next could use your account, which get ugly.
2. if you lock screen instead of logout then you're tying up the machine for whoever comes in next, and instructors can get quite grumpy if they have a full lab section and a handful of machines are locked.

7. Sign back in and get set up to continue working

Now let's log back in (on the same machine or any other in the lab, they're all accessing the same shared file system, so your account contents will look the same on each).

login using your linux username and the new password you set
open the browser (Applications->Internet->Chromium), go to the labs page, and navigate to lab 1 again
csci.viu.ca/~wesselsd/courses/csci159/labs.html
go into your csci159 directory and from there to your lab1 directory
cd csci159
cd lab1
open your lab1.cpp file using pico again
proceed to the instructions below for creating a program with input, output, and variables

8. Now let's turn our lab1.cpp into a real program and submit it

For lab1 we're writing a short program to get the user to enter some information about a bunny sighting on campus: telling us what day they saw it, what colour it was, and how big it was. Our program will then display a summary of their sighting information back to them.
The steps below will walk through the construction of the program

We've got the basic structure of a C++ program in our lab1.cpp already,

#include <iostream>

int main()
{
   std::cout << "Welcome to lab1!" << std::endl;

   return 0;
}

First we'll add another library we're going to need: string (we'll use string variables to hold the colour and size of the bunny and what building it was closed to). The top of the program will now look like:
```
#include <iostream>
#include <string>
```
Change the file content, save, then try recompiling in the terminal window
make lab1x
If you get any compilation errors then go back to the editor and keep fixing/compiling until it's ok, then try running it. (For the moment, the behaviour will be exactly the same as before.)
./lab1x

Next we'll display a short intro to the program so the user has some idea of what's going on.

We'll add this using more cout statements, replacing the single cout we originally had, e.g.

   std::cout << "Welcome to BunnySight: the program that lets you enter information about a ";
   std::cout << "bunny sightings on the VIU campus." << std::endl;
   std::cout << "You will be asked to enter the date, ";
   std::cout << "the bunny size and colour, and what building it was closest to." << std::endl;

Again try compiling/fixing until it compiles cleanly, and now when we run it we should see the message above.

Now we can add some variables to hold the date, bunny size/colour, and the building number.
The day (1-31), month (1-12), year, and building number will all be entered and stored as integers, whereas we'll have them enter the size (small, average, large) and colour (e.g. brown) as words. The two data types we'll use can thus be int and string.
For each variable we'll pick a meaningful name and we'll put a descriptive comment beside the variable.
We'll put all this just after the { at the start of the main routine, e.g.
```
int main()
{
    int day, month, year; // the date the bunny was seen (1-31 for day, 1-12 for month)
    std::string colour; // the colour of the bunny as a single word, e.g. "brown"
    std::string size; // the size of the bunny as one of "small", "average", "large"
    int building; // the number of the building closest to the bunny (e.g. 315)

    ... the cout's would be down here ...
```
Again try compiling/fixing until it compiles cleanly other than warnings about unused variables (those will go away as we actually get the user to input some data).
If we run it now (i.e. the ./lab1x command) it should still just give the descriptive message then end.
Now, one-by-one, we'll prompt the user to enter part of the information and we'll read it into a variable, e.g.
```
   std::cout << "Enter the day you saw the bunny (1-31)" << std::endl;
   std::cin >> day;
     
```
These will go below our earlier cout (so they see the program description *then* it starts asking for data) but above the return 0 (since that effectively ends a run of the main routine).
Do similarly for each of the six variables, giving the user a clear description of what they should be entering for each, e.g.
```
   std::cout << "Enter the size of the bunny as either small, average, or large" << std::endl;
   std::cin >> size;
```
As usual, compile and fix until it compiles ok. (Notice the warnings for the variables have changed, now it tells us we've set values for them but aren't using them. This will be fixed in the next step.)
Now if we run the program it should prompt us to enter the various values, stopping and waiting for us to enter a value each time.
Finally we'll add a section to display all the stored data back to the user in a meaningful way. This will go after the last of our cin statements (but before the return 0).
```
   std::cout << "To summarize your sighting:" << std::endl;
   std::cout << "   it was on " << day << "/" << month << "/" << year << std::endl;
   std::cout << "   the bunny was " << colour << " and " << size << std::endl;
   std::cout << "   and was near building " << building << std::endl;
```
Compile and fix (as usual), and hopefully the program should behave as expected when run: giving the user a description of the program, prompting the user for each part of the sighting information and reading it in, then displaying all the information back to the user at the end.
Keep tweaking and fixing the program until you're satisfied it is working correctly and you're happy with the appearance of the output.

9. Sample output

The example below shows a sample run of the program.

Just to make the output below clearer, things the user typed have been emphasized in bold italics. (That wouldn't be the case when you run your programs, it's just to make the example a little clearer.)

Welcome to BunnySight: the program that lets you enter information about bunny sightings on the VIU campus.
You will be asked to enter the date, the bunny size and colour, and what building it was closest to.

Enter the day you saw the bunny (1-31)
10 
Enter the month you saw the bunny (1-12)
9 
Enter the year you saw the bunny (e.g. 2024)
2024 
Enter the colour of the bunny as a single word, e.g. brown
blue 
Enter the size of the bunny as one of small, average, or large
large 
Enter the number of the building nearest the bunny, e.g. 315
300 

To summarize your sighting:
   it was on 10/9/2024
   the bunny was blue and large
   and was near building 300

10. Code standards

In future labs your code will also be required to meet the course code standards, but for this first lab we'll focus on just getting the functionality correct and making sure we can submit it successfully.

11. When you're done:

be sure to do a final "make submit" from inside your csci159/lab1 directory
be sure to logout (under the System menu)

12. Deadlines and late penalties

Submission deadlines and late penalties for all lab exercises are provided on the main labs page.

13. Supporting tools

Most of the time we won't complete the entire lab in the two-hour lab block, so you'll want to come back to the lab later in the week or connect from home.

Discussion of the basic tools and steps for doing so can be found here.