Description
Welcome to CSci 2041. Please be sure to get a copy of the syllabus
before you leave the lab. Read it before lecture on Wednesday.
### Goals of this lab:
+ In this lab you will set up your University of Minnesota GitHub
repository that will be used to turn in your homework assignments for
this course.
+ You will also install the OCaml compilers and associated tools that we
will be using in this class.
+ Finally, you will modify an OCaml program, run it, and turn it in
via GitHub.
+ There should be enough computers for each person to have their own.
+ If you have a laptop, please feel free to use it for this if you
want. But keep in mind that your homework is graded on the lab
machines and must work there.
### GitHub:
* The University of Minnesota has its own GitHub installation that we
will be using in the course. We **are not** using
https://github.com.
* Git is a software version control system that we will be using in
the class. You will turn your work in using GitHub, not Moodle. We
will provide feedback on your work using GitHub as well.
### Set up your CSE Labs account if you do not have one
If you do not yet have a CSE Labs account, perhaps because your are a College of
Liberal Arts student, then create that account now.
To do so, go to this web site and fill in the requested information:
https://wwws.cs.umn.edu/account-management/
# Lab Steps to Complete
## Working with GitHub and Git
### Initialize your GitHub account
+ If you’ve already logged into https://github.umn.edu, then proceed
to the next step since your repository should already be set up.
+ If you’ve never logged into https://github.umn.edu, then do so now.
Then give your University Internet Id (we’ll call this UIID for short)
to a lab TA so that they can set up your repository. This is the same
as the part of your University email address that comes before the
`@umn.edu` part of the address.
+ Note that this is **not** your student ID number that appears on
your student Id card. We will never ask you for that number.
### Verify that your 2041 repository is set up
+ If your University Internet Id is **user0123** then your repository
will be named **repo-user0123**. In the examples and text below,
replace **user0123** with your University Internet Id.
+ Log into https://github.umn.edu and select the **umn-csci-2041-S18**
organization and click on the repository named **repo-user0123**.
+ At the URL
https://github.umn.edu/umn-csci-2041-S18/repo-user0123
you should see a list of files in your repository. This will
include only a file named **README.md**.
If this file is not there, speak to a TA in your lab.
This repository is a database containing the files and the history of
all their changes made since they were added to the repository. It is
much more than a simple copy of a set of files.
### Setting up Git in your CSE Labs account
+ Log into your CSE (College of Science and Engineering) account.
+ Verify Git is installed. Execute the following:
(But don’t type the `%`. That is meant to symbolize the prompt you see in your terminal window. It may be different that the `%` sign. You’ll just type `git –version`. Don’t type the `%` in any of the other examples below.)
“`
% git –version
“`
+ Configure Git.
You need to tell Git what your name, email address and favorite
editor are. Below is the series of commands that you should
enter. Be sure to fill in the appropriate details for yourself
“`
% git config –global user.name “YOUR NAME HERE”
% git config –global user.email “YOUR UMN EMAIL ADDRESS”
% git config –global core.editor “nano”
“`
If you have a favorite editor (for example `emacs` or `vim` instead of
`nano`) then you can enter the command to start that editor where it says
`nano` above.
Note that your name appears between double quotes since it has spaces
in it. Your email address doesn’t, so it doesn’t need to be in
quotes. If you would like “emacs -nw” as your editor (emacs such that
it doesn’t open a new window but opens in the terminal) then you’ll
want double quotes around that 2 word phrase.
Check that these are set correctly; execute
“`
% git config -l
“`
### Create a space for your Git workspaces
Create a directory in your CSE account named “csci2041” (You can use
some other name, of course, but in the discussion we will assume that
you used “csci2041”). Then enter your newly created directory.
“`
% mkdir csci2041
% cd csci2041
“`
In **csci2041** we will put copies of a “public” read-only repository
containing files that we want to distribute to you during the semester
and also copies of your individual repository that only you and the
TAs and instructor have access to.
### Clone your individual repository
The Git “clone” operation makes a copy of a repository and places it
in your account. This copy contains the files and also all the
history of changes—just like the repository stored on
https://github.umn.edu.
In your **csci2041** directory, execute the following
“`
% git clone http://github.umn.edu/umn-csci-2041-S18/repo-user1234.git
“`
After entering your UIID credentials this will create the directory
called repo-user1234.
It will contain a **README.md** file.
Execute the following:
“`
% cd repo-user1234
% ls
“`
When you clone your repository Git will create some hidden files
stored in the **.git** directory that contain the long name of this
repository, so that we won’t need to type it anymore.
This directory contains the copy of the repository with all the past
history of changes to the files and other information. So now there
are two copies of your repository.
These hidden files tell Git where the GitHub central server is so that
operations involving the server won’t need this long name.
Execute the following:
“`
% ls -a
% ls .git/
“`
Modifying these hidden **.git** files by hand, or creating them by
copying directories, is an extremely bad idea. It will cause you many
headaches with Git. **So don’t do it!**
*You only need to do this clone step once to initially install the
repository in your account.*
If you have another computer and want to do some of your homework on
that, then you will need to repeat this step for that computer as
well.
### Commands that access the repository
The following command reads these hidden files and will tell you the
URL of the central repository, and some other information.
Execute the following:
“`
% git remote –verbose
“`
A status operation will also tell you if you’ve made changes to your
workspace since the last time you updated it with files from the
repository. This is important because we grade your work by getting it
out of your repository. If it is in your workspace but not the central
GitHub repository we can’t see it and it won’t be graded.
Run the following:
“`
% git status
“`
Since the files in your
workspace (see below) and repositories (both local and the one on
https://github.umn.edu) are the same, Git tells you as much.
### Working files
So, if the hidden directory **.git** is another copy of the
repository, what are the files in this directory?
These files are copies of the files that you can edit. You can create
new files and delete files that are no longer needed. **But**, we
will need to “commit” any changes that we make to these files to the
repository, eventually, so that the repository and the “working files”
in your account are synchronized.
Ensure you are in your git repository. Then create a `Lab_01` directory and
change into it by executing the following:
“`
% mkdir Lab_01
% cd Lab_01
“`
Using the text editor of your choice, create a file named `fib.ml`
in your just-created `Lab_01` directory. Copy the following OCaml
code into that file and save it.
“`
(* Author: Eric Van Wyk
Modified by: … replace the text between the dots with your name … *)
(* A function computing the Fibonacci sequence: 1, 1, 2, 3, 5, 8, … *)
(* There is a bug in the following program. Can you fix it? *)
let rec fib x =
if x < 3 then 1 else fib (n-1) + fib (n-1)
“`
Add your name into the comment on the second line of the file.
Don’t worry about the rest of the file, we will learn how to read this
OCaml code soon enough.
### Adding files
Check the status of your working files and repository by executing the
following:
“`
% git status
“`
This tells you that there is now an “untracked” file named `fib.ml`
and that Git is not tracking changes to this file. To tell Git to do
so, we must `add` the file using the following command:
“`
% git add fib.ml
“`
Now run `git status` again and see what it says. What is Git telling
you here?
### Committing changes
Git is now aware of this file and sees that changes have been made
that have not be “committed”. Only “committed” changes to the file
can be pushed up to the central GitHub server (http://github.umn.edu)
and thus it is only these that will be graded or assessed.
To commit the file changes you’ve made, execute the following
“`
% git commit -m “Adding my name to the file”
“`
The text in quotes is the commit message. It should provide a brief
description of what changes are being made in this commit; in this case
we have added our name to the file `fib.ml`.
Now go back to your browser and refresh the page showing your
repository. Does this file show up there?
No, it doesn’t. The **commit** command adds your changes to your
local repository only. We now need to **push** those changes from
your local repository up to the one stored on https://github.umn.edu.
We will do that next.
But first, run “` % git status “` What is it telling you? Your
changes are committed to the local repository but not the “central”
one on https://github.umn.edu
### Pushing changes
Type
“`
% git push
“`
This pushes your changes from your local repository up to the central
one.
Run
“`
% git status
“`
again. It should now tell you that your working copy of the files and
both repositories are all synchronized.
In your web browser, check that a file named `Lab_01_Feedback.md` has
been added to your repository. You can click on the link to see its
contents. These files will typically be generated for your
assignments everytime you push changes to your programs up to
GitHub and they will give you some feedback on your assignment.
If the feedback indicates that something is wrong, then fix your code
and “add“, “commit“, and “push“ it again. The feedback file
should be updated soon to indicate if your fix was successful. Note
the timestamp in these files so you know if the feeback file has been
generated again.
**You can push new versions of your code as often as you like until
you are satisfied with it.**
If the results here are not what you expect then you need to either
fix the issues identified with your program, or, talk to a TA or post
a question on Moodle to see if there is a problem with the tools that
automatically generate these files.
In this case, these tools will verify that your program is in the
right directory, in the right file, but broken and not yet working.
Later in the lab you will fix the problems.
Now run the following:
“`
% git pull
“`
This will “pull” the feedback file down to your local workspace. You
will need to do a “git pull“ before you can do another “git push“
so that the changes made to your repository on https://github.umn.edu
by the feedback scripts can be merged into your local copy.
This merge should always succeed for the work we do in 2041. If it
fails, pay close attention to the error messags from git to see if you
can fix things.
### Clone the public repository
Go back to your **csci2041** directory, by executing the following
command:
“`
% cd ../..
“`
Now clone the public class repository by executing the following
command:
“`
% git clone http://github.umn.edu/umn-csci-2041-S18/public-class-repo.git
“`
In the directory `Labs` you will see the Markdown file
`Lab_01_Jan_16_Getting_started_with_OCaml_and_Git.md` from which this
web page is generated.
When we add new files to the central repository you will be asked to
execute the following:
“`
% git pull
“`
This “pulls” changes from the central repository down to your local
one and updates the working copy of those files in your account with
the changes.
Try it. It doesn’t have any effect, but it doesn’t cause any harm
either.
## Working with OCaml
### Install OCaml
Go back to your account home directory:
“`
% cd
“`
We need to verify that the correct version of OCaml is installed. The libraries are
slightly different between versions and so it is important to use the correct one.
Execute the following command:
“`
% which ocaml
“`
This will indicate if ocaml is installed and display the path to the
ocaml compiler on the machine. It should be **/usr/local/bin/ocaml**
or something similar.
Next, execute the following:
“`
% ocaml -version
“`
This should tell you that you are using version 4.06 of OCaml. There may be some machines
which do not yet have this version on OCaml installed and instead are running version 4.02.
We are working to get all machines update to 4.06 but it should not matter for the first
couple of labs. However, if you decide to install OCaml on your own machine please
be sure to get version 4.06.
### Use OCaml
Go back to the `Lab_01` directory in your individual repository.
Perhaps by the following commands:
“`
% cd
% cd csci2041/repo-user0123/Lab_01
“`
Start the OCaml interpreter:
“`
% ocaml
“`
At the Ocaml prompt (#) enter the following (do type “#use”, not just
“use”):
“`
# #use “fib.ml” ;;
“`
Note that the prompt is “#” and directives to the interpreter to load
files and quit also begin with a “#”.
OCaml will report an error in the program:
> File “fib.ml”, line 10, characters 30-31:
> Error: Unbound value n
Quit OCaml using the “quit” command as illustrated below:
“`
# #quit ;;
“`
We will now need to fix the file.
### Fix the sample file
Using a text editor (emacs, vim, gedit, etc.) edit the `fib.ml` file.
We have already seen one error: on line 10 we use a the name n which has not been
defined. Replace the variable n with the correct variable name, x.
Also, replace the text between dots in the comment with your name if you’ve not already done so.
Save the file and repeat the steps above to start OCaml and load the file.
If the file is successfully loaded you should compute the 5th Fibonacci number by typing the following:
“`
# fib 5 ;;
“`
There is a bug in this program. It will return `16` instead of the
correct answer of `5`. Let’s fix that bug now.
The nth Fibonacci number is computed by adding together the previous two Fibonacci numbers. Traditionally,
the first two fibonacci numbers are both `1`. We will use an extended sequence which has a `0` as the
“0th” Fibonacci number.
Your sequence should start with `fib 0` returning `0` and both `fib 1` and `fib 2` return `1`. You will
need an if-then-else expression to check if `x = 0` and evaluate to the correct value if true. The else
branch will also be an if-then-else expression, you may use the one that is there now. The final function
should look something like the following
“`
let rec fib x =
if x = 0 then 0 else
if x < 3 then 1 else fib (n-1) + fib(n-2)
“`
After you’ve saved the file, test it. Fire up `ocaml` again and see
if you get the right answer.
### Commit and push so that the corrected version is up on GitHub.
Now you need to just turn in your work. First, see what Git says
about the status of your files
“`
% git status
“`
It tells you that a file has been modified.
You now need to commit your changes and push them up to your central
GitHub repository.
Execute the appropriate `git add` and `git commit` commands and the
run `git push`. What is the error message that you get?
It is telling you that changes have been made to code up on the GitHub
server and that you need to “pull” those changes before you can “push”
new changes up to the repository.
Execute the following:
“`
% git pull
“`
The above command “should” work and seems to work for many of you. If it doesn’t you’ll get a message about the need to “merge” the local repository in your account with the repository up on the https://github.umn.edu server.
You will be put into an editor window where you could enter a message to document this “merge” operation. There is no need for this comment, so just save the file. Now try `git pull` again. It should tell you that your repository is already up to date.
You should now see that feedback file in your local directory (just
above your `Lab_01` directory. Verify that it is there.
Now do a `git push` to see that your changed code is pushed up to the
Github server. Also verify that the feedback file gets updated to
indicate that your code is now working properly.
Verify that this worked, by using your browser to see the changes on
https://github.umn.edu.
This concludes Lab 01.
### **Due:** Friday, January 19 at 5:00pm.
You should be able to complete lab work during the lab. But
occasionally some work may not get completed, thus this due date.
Note that these changes must exist in your repository on
https://github.umn.edu. Doing the work, but failing to push those
changes to your central repository cannot be assessed.
After the due date, we will typically run additional tests and the
results of this assessment will be put a file named
`Lab_01_Assessment.md` in your repository. This file will have your
score for the lab. A similar pattern will be repeated for other
assignments.
