Introduction to CSCI206 Lab
The goal of this course (CSCI206) is to understand at a fundamental level how computers work. To give you hands on experience in lab, we will learn to work with lower-level Linux tools. Becoming familiar with these tools will be immensely valuable as you become professional Computer Scientists and Engineers. The Linux command line is a veritable swiss army knife for getting work done. By mastering the basics and knowing about the other tools, you will be well prepared to solve any challenge.
- Learn to create a local git repository for CSCI 206 lab solutions and link it to a remote repository on gitlab.
- Begin learning how to use the Linux terminal.
- Practice using emacs and vim.
Exercise 1: Setup git source code management
In this course, we will use git for source code management and for the submission of labs and other assignments. It is essential that you follow these directions exactly to get set up correctly. We are doing all this in lab so that you can ask for help if anything seems confusing.
If you haven’t used our gitlab server before the first thing you will need to do is create an ssh key for authentication and upload it to gitlab. If you have done this before (like in CSCI205), skip to exercise 2.
To begin, open a terminal window; we will use it to generate an ssh key by running the command below:
This will ask where you want to save the key. Choose the default location suggested to you, which is ~/.ssh/id_rsa.pub (just press enter to accept the default). If the file already exists, do not overwrite it; you can (and should) use your existing key.
Next, you will be asked to supply a passphrase. At this level, you are not required to have a passphrase, go ahead and leave this blank. If you do create a passphrase you will have to type it every time you access gitlab or figure out how to add it to your system keyring, which is not covered here.
Now, open a web browser and point it to https://gitlab.bucknell.edu/ .Use your normal Bucknell username and password to login. Once logged in, you will see a similar screen to the following as your gitlab “home” screen. First click the “down arrow” button at the top-right corner of the screen, you should see a pull-down menu. Click the “Profile Settings” button from that pull-down menu.
On the profile setting screen, find and click the section “SSH Keys.” You should see a screen similar to the following.
Go back to the terminal window and type the following on your shell prompt:
This will print your public key as text on the terminal. Next, select and copy the entire contents that were printed to the terminal (this will start with “ssh-rsa…” and end with your email address). Go back to the browser window of gitlab and paste the copied text into the large textbox labeled “Key”. Fill in the Title box with a reasonable title for the key, for example, “git-key-2017-spring” and then click “Add key” button. Now, gitlab will be able to associate your public ssh key with your user account.
Exercise 2: Setup gitlab for CSCI206
After you have added the ssh key to gitlab, go back to the dashboard by clicking the “dash-board” button in the middle of the screen. Once you are at your dash board, click the “New Project” button at the upper right corner. It will bring you to a screen similar to the following.
Enter “csci206” for the Project name, leave the default Project path which should be the gitlab web address plus your Bucknell user name and Visibility level which should be Private. Then click the “Create Project” button as seen in the following screen-shot. NOTE: use lowercase csci206 for the project name, exactly as shown above). The creating-project button should bring you to a screen similar to the following.
Some settings are not available until there is a file in the repository, so we’ll make one now. Click the button in the middle of the screen that will create the file “README” (in a statement Otherwise you can start with adding …). Create a file as shown below called “README.md” with the contents “This is the csci206 project that will contain all programming work for the course.” and add a commit message “Created the README file.” and click the “Commit Changes” green button at the lower left corner.
Once the file is created and committed, click the “Project” tab, then click the “Settings” button at the upper right corner (the gear icon). A pull-down menu should show up, choose the “Members” option. It will bring you to the following screen.
Now add your instructors and all of the TAs below with “Developer” access level. This will allow us to push grading comments back to your gitlab repository.
Our instructors are:
- Professor Joshua Booth <firstname.lastname@example.org>
- Professor Xiannong Meng <email@example.com>
- Professor Joshua Stough <firstname.lastname@example.org>
Our TAs for this semester are:
- Xiaoying Pu <email@example.com>
- Jordan Sechler <firstname.lastname@example.org>
- Keyi Zhang <email@example.com>
After entering the correct information for your instructors and TAs, please click the green button “Add users to project” (make sure you allow them the Developer level access.) You should now have seven members to your csci206 project (including yourself). When you are done, click on the “Setting” icon again, and choose the “Protected Branches” option from the pull-down menu, as seen in the following.
On the protected branches screen we want to unprotect the master branch. On the bottom of the screen click the red “Unprotect” button. This will allow our TAs to push comments and grades into your repository with ease. In your future use of gitlab, you might want to consider a more fine protection scheme for your project. But for this course, we’ll use this setting. If you’re curious about project permissions on git, please feel free to read the “project permissions” description. As a result of your setting the permissions, you should see a screen similar to the following after the master branch is unprotected.
Exercise 3: Creating an organized directory structure
In Linux, there is a philosophy that “everything is a file” (almost). This is an interesting philosophy that impacts how we work with Linux systems. First of all, a little terminology to make sure we are all on the same page: we call terminal the application where you can type commands and shell the command interpreter that runs inside the terminal window. There are are various types of shell, the one we use most commonly in the department is called bash.
One of our goals in this class is get you to learn to manipulate files from the shell prompt (not all Linux systems have a graphical display and it’s faster anyway). To get help from the shell prompt, you can always read the man (or manual) page. Go to your prompt in a terminal and type:
$ man man
This will display the manual page for the man interface. Within man, notice the bottom most line has important status messages. It should say something like “Manual page man(1) line 1 (press h for help or q to quit).” The phrase man(1) indicates that this manual page is for the topic of man and it is in Section 1 of the manual pages. Press the h key now to show the help screen (case does not matter). Some important things to notice are that you can press q to quit, arrow keys (and others) to scroll around by rows or columns, space key to go to next page, letter b for previous page, and / to search. Press any key to exit the help screen. Skim the DESCRIPTION section of the manual page for man.
Notice there are several sections in the Linux manual pages (we will use mostly Section 2, the system calls, in this course). This man page is in Section 1 which contains all executable programs or shell commands. Also, each man page is typically divided into common sections (NAME, SYNOPSIS, etc). Understanding how to quickly scan a man page to find the information you need at any given time is an essential skill for any Linux user.
For example to read the manual page for the command cp (copy) you would type the command at your command prompt $: man cp .
Read the man pages for: ls, pwd, cp, mkdir, rmdir, and touch. Don’t try to memorize all of the details: people who have used Linux for decades still have to check man pages often. The point is to become good at skimming the pages for the information you need at the moment. Just try to get a sense of the big picture about what each command does and how you might use it.
If you haven’t used git on the lab machines before, we first have to configure your name and email. If you have used git before, you can skip these two commands (but it won’t hurt to do it again if you aren’t sure). Note replace the abc123 below with your Bucknell username (usually your initials plus a three digit number), and replace “First Last” by your first and last name. If any command fails, fix it before going on! (ask for help)
$ git config --global user.name "First Last" $ git config --global user.email "firstname.lastname@example.org"
In addition, please enter the following commands at your command line prompt.
$ git config --global push.default simple $ ssh-add
The first git command tells git to confirm with some of the newer features in its push behavior. The second command adds private key identities to the authentication agent, which is needed for the git server.
Your next task is to create an organized directory structure for csci206. You will use mkdir to create all our directories rooted at your ~/csci206 (the leading ~ is expanded by the shell with your home directory). Inside ~/csci206, which is the root for this class, you can create folders for homework, notes, etc. For each lab, you will create a new folder, LabXX inside a folder called Labs, which in turn will be inside your ~/csci206 folder. Note we use Lab01 instead of Lab1 so when sorted alphabetically your labs will appear in order (Lab01 comes before Lab10).
Type the following commands in your shell to get started (again, be sure to replace abc123 with your Bucknell username):
$ mkdir ~/csci206 $ git clone email@example.com:abc123/csci206.git ~/csci206/
This will create the directory ~/csci206 and link it to your gitlab repository. Next, we want to create a directory to hold your Lab01 inside the directory Labs, so type the command:
$ mkdir ~/csci206/Labs/Lab01
This will give you an error: “mkdir: cannot create directory…”
Go back to the man page for mkdir and find the option to make parent directories as needed (use the man page search functionality to help you find it) . Keep working until you manage to create the directory structure ~/csci206/Labs/Lab01 with a single call to mkdir. Make sure to remember (or write down) this command so that you can provide it later as the solution to this problem.
To practice adding a file to your gitlab repository, use the touch command to create an empty file called lab01.txt (inside your ~/csci206/Labs/Lab01 folder!). If you don’t know how to do this, read the man page for touch! After creating the file, you can use the following commands to add lab01.txt to your local git repository and push it to gitlab (the remote repository). The -m option to git commit is used to specify the commit message (you could find this by reading the git-commit man page as well!). If any command fails, fix it before going on! (ask for help).
$ cd ~/csci206 $ git add Labs/Lab01/lab01.txt $ git commit -m 'gitlab setup' $ git push
To verify that everything worked, open your gitlab repository over the web as you did in Exercise 2. Click the dashboard button, then click the “Project” tab, you should see a screen similar to the following. Notice that the commit message “gitlab setup” which is what you were asked to enter when committing the files. It could be any other messages you used.
At this screen, please click the commit ID which is the number before the commit message to see the actual information about the file you committed (lab01.txt). In the above case, the commit ID is d43ac4f9, yours will be a different number.
You can use this same procedure to add local files to your local repository, commit the changes, and push them to the gitlab server. Keep in mind we grade only the work you successfully pushed to gitlab. If you forget to push any files, that is the same as forgetting to hand them in. Don’t let that happen! If you forget whether you added a file, use the git status command and use the gitlab web interface to double check.
Exercise 4: Creating and viewing a text file
In any file system there are two basic types of files:
- binary, which may be executable programs or data files used by other programs. These files are not human readable, meaning that you need a special program to use these files.
- text, which contains human readable text. Many Linux programs (including the OS itself) store configuration data in text files. Since source code for programs is also stored as text files, as a programmer, you spend most of your time manipulating text files.
We will start with a very basic way to edit a file using our friend the cp command. First, cd into your Lab01 folder. Now type:
$ cd ~/csci206/Labs/Lab01 $ cp /dev/tty lab01.txt
This will bring your terminal to a blank line. (If warned “overwrite file”, respond with “yes”.) Remember how everything is a file in Linux? The file for keyboard I/O is /dev/tty. This instructs the cp program to copy data from the keyboard into a text file with the given filename. In your terminal type the following (fill in your actual name):
<Your first and last name> CSCI206 Lab01 <Date of the lab>
The cp command copies the entire contents of the source file (in this case /dev/tty, i.e., your terminal) until it hits an end-of-file marker. We will simulate this end-of-file marker by pressing control-d at the terminal, which will give you back a command prompt. Use the ls command to verify that the file lab01.txt was created.
To verify the contents of the file, we simply reverse the source and destination in the cp command you used previously:
$ cp lab01.txt /dev/tty
Note: this command will generate the message: cp: overwrite `/dev/tty’? Press y then <enter>.
This command does the exact opposite as before and copies the contents of the file to the terminal (i.e., your screen). Verify the information entered is correct, re-run the cp command and re-create your file if you have a mistake. As a side note, most people wouldn’t use cp to view a text file. There are more user friendly ways to go about this. Read the man pages for: cat, more, less, head, and tail. Give each one a try to inspect the contents of your lab01.txt file. In your notebook, write down a one sentence description for each command.
Exercise 5: The editor wars
As you might expect, most people don’t use cp to create text files, either. It blindly copies data from the terminal to the file. If you make a mistake you can’t go back to a previous line to make changes. We need a text editor for serious work. We want you to become familiar with a good terminal-based text editor because, as we said before, many computing systems (servers, embedded devices, etc) do not have a graphical display. Once you learn to use the terminal editor, you won’t need the GUI, anyway. Don’t worry, all of the productivity-enhancing features found in GUI tools like Idle, Eclipse, or Visual Studio (syntax highlighting, spell check, brace matching, auto-indentation, auto-completion, etc) are available in terminal form.
The two primary terminal-based editors to know are vim and emacs. These editors (or their parents/descendants) have been around since nearly the beginning of computing. There is active debate between the two camps. Note that modern versions of emacs default to a simple GUI. Read the emacs man page to discover the option to start it without the GUI. Some search words to look for are: “window” and “special interface.” Make sure to record in your notebook the full command to start up emacs without a GUI, so that you can provide it as the solution to this problem. vim starts up in text-mode by default, but gvim provides a simple GUI for vim. The default vim settings are a bit dated so I recommend making a few changes to your ~/.vimrc file (which holds the default settings). One place to start is to install the basic or awesome settings from this repository https://github.com/amix/vimrc.
You should experiment with both emacs and vim, so that you can decide which one you like best for use in the rest of this semester. This is a big decision, give both of them a try and go with what works best for you. They both have built in tutors. For vim it is a separate program called vimtutor. For emacs, first start it up normally (in non-window mode) and use this sequence: Press Control-h, then release Control-h, and then press t (in emacs speak, this would be written simply as C-h t).
Spend about 30 minutes with each tutorial. You may choose not to finish them, but you should spend long enough time to get a general feel for how each editor works. If you get stuck and want to exit the editor: to quit vim type ESC :q! and to quit emacs type Control-x Control-c. In addition to these tutorials, you can always search the internet for answers to some of the common functionality of emacs and vim. The only way to really learn either of these editors is to spend time using them. When you are done with the tutorials, pick one editor to use for the rest of the semester. This commitment will ensure that you have time to become proficient with the one you chose.
Once you have made your decision, use your selected editor to open your lab01.txt file. After the header (name/date/course/Lab01) append the answers to the questions listed in the Grading rubrics in your file.Please copy each of the questions, then type your answer under the question. Make sure you number the questions properly.
The following rubrics will be used in grading your work.
- [15 points] One line mkdir ~/csci206/Labs/Lab01 command, and leaving your lab01.txt in the right place.
- [5 point each] One sentence description of each of the following commands do: cat, more, less, head, and tail.
- [10 points] The complete command line to start up emacs without a GUI.
- [10 points] What is the command to show line numbers in vim?
- [10 points] What is the command to show line numbers in emacs?
- [10 points] Complete this sentence in your file: After careful consideration, I will use <vim or emacs> in csci206 as my text editor.
Make sure to use the correct case for the names of directories and files for full credit. Note that the name of your directory is not Lab1, but Lab01 instead. If you get this naming convention messed up, you will lose points in this and in future labs (it really complicates the lives of the people who grade your work if you don’t follow the expected convention!)
When you are done, be sure to add, commit, and push your lab01.txt file to gitlab!