illinois-cs341-system-programming/content/en/chap2/Debugging_Environments.md

+++ title = "Debugging and Environments" +++

Debugging and Environments

I’m going to tell you a secret about this course: it is about working smarter not harder. The course can be time-consuming but the reason that so many people see it as such (and why so many students don’t see it as such) is the relative familiarity of people with their tools. Let’s go through some of the common tools that you’ll be working on and need to be familiar with.

ssh

ssh is short for the Secure Shell (“Ssh(1),” #ref-openbsd_ssh). It is a network protocol that allows you to spawn a shell on a remote machine. Most of the times in this class you will need to ssh into your VM like this

$ ssh netid@sem-cs241-VM.cs.illinois.edu

If you don’t want to type your password out every time, you can generate an ssh key that uniquely identifies your machine. If you already have a key pair, you can skip to the copy id stage.

> ssh-keygen -t rsa -b 4096
# Do whatever keygen tells you
# Don't feel like you need a passcode if your login password is secure
> ssh-copy-id netid@sem-cs241-VM.cs.illinois.edu
# Enter your password for maybe the final time
> ssh  netid@sem-cs241-VM.cs.illinois.edu

If you still think that that is too much typing, you can always alias hosts. You may need to restart your VM or reload sshd for this to take effect. The config file is available on Linux and Mac distros. For Windows, you’ll have to use the Windows Linux Subsystem or configure any aliases in PuTTY

> cat ~/.ssh/config
Host vm
  User          netid
  HostName      sem-cs241-VM.cs.illinois.edu
> ssh vm

git

What is ‘git‘? Git is a version control system. What that means is git stores the entire history of a directory. We refer to the directory as a repository. So what do you need to know is a few things. First, create your repository with the repo creator. If you haven’t already signed into enterprise GitHub, make sure to do so otherwise your repository won’t be created for you. After that, that means your repository is created on the server. Git is a decentralized version control system, meaning that you’ll need to get a repository onto your VM. We can do this with a clone. Whatever you do, do not go through the README.md tutorial.

$ git clone https://github-dev.cs.illinois.edu/cs241-fa18/<netid>.git

This will create a local repository. The workflow is you make a change on your local repository, add the changes to a current commit, actually commit, and push the changes to the server.

$ # edit the file, maybe using vim
$ git add <file>
$ git commit -m "Committing my file"
$ git push origin master

Now to explain git well, you need to understand that git for our purposes will look like a linked list. You will always be at the head of master, and you will do the edit-add-commit-push loop. We have a separate branch on Github that we push feedback to under a specific branch which you can view on Github website. The markdown file will have information on the test cases and results (like standard out).

Every so often git can break. Here is a list of commands you probably won’t need to fix your repo

1. git-cherry-pick
2. git-pack
3. git-gc
4. git-clean
5. git-rebase
6. git-stash/git-apply/git-pop
7. git-branch

If you are currently on a branch, and you don’t see either

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

or

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   <FILE>
        ...

no changes added to commit (use "git add" and/or "git commit -a")

And something like

$ git status
HEAD detached at 4bc4426
nothing to commit, working directory clean

Don’t panic, but your repository may be in an unworkable state. If you aren’t nearing a deadline, come to office hours or ask your question on Piazza, and we’d be happy to help. In an emergency scenario, delete your repository and re-clone (you’ll have to add the release as above). This will lose any local uncommitted changes. Make sure to copy any files you were working on outside the directory, remove and copy them back in

If you want to learn more about git, there are all but an endless number of tutorials and resources online that can help you. Here are some links that can help you out

1. https://git-scm.com/docs/gittutorial

2. https://www.atlassian.com/git/tutorials/what-is-version-control

3. https://thenewstack.io/tutorial-git-for-absolutely-everyone/

Editors

Some people take this as an opportunity to learn a new editor, others not so much. The first part is those of you who want to learn a new editor. In the editor war that spans decades, we have come to the battle of vim vs emacs.

Vim is a text editor and a Unix-like utility. You enter vim by typing vim [file], which takes you into the editor. There are three most commonly used modes: normal mode, insert mode, and command mode. You start off in normal mode. In this mode, you can move around with many keys with the most common ones being hjkl (corresponding to left, down, up, and right respectively). To run commands in vim, you can first type : and then a command after it. For instance, to quit vim, simply type :q (q stands for quit). If you have any unsaved edits, you must either save them :w, save and quit :wq, or quit and discard changes :q!. To make edits you can either type i to change you into insert mode or a to change to insert mode after the cursor. This is the basics when it comes to vim. In addition to the countless great resources out there on the internet, vim also has its own built-in tutorials set up for beginners. To access the interactive tutorial, enter vimtutor in the command line (not inside of vim), and you are all set!

Emacs is more of a way of life, and I don’t mean that figuratively. A lot of people say that emacs is a powerful operating system lacking a decent text editor. This means emacs can house a terminal, gdb session, ssh session, code and a whole lot more. It would not be fitting any other way to introduce you to the gnu-emacs any other way than the gnu-docs https://www.gnu.org/software/emacs/tour/. Just note that emacs is insanely powerful. You can do almost anything with it. There are a fair number of students who like the IDE-aspect of other programming languages. Know that you can set up emacs to be an IDE, but you have to learn a bit of Lisp http://martinsosic.com/development/emacs/2017/12/09/emacs-cpp-ide.html.

Then there are those of you who like to use your own editors. That is completely fine. For this, we require sshfs which has ports on many different machines.

1. Windows https://github.com/billziss-gh/sshfs-win

2. Mac https://github.com/osxfuse/osxfuse/wiki/SSHFS

3. Linux https://help.ubuntu.com/community/SSHFS

At that point, the files on your VM are synced with the files on your machine and edits can be made and will be synced.

At the time of writing, an author likes to use spacemacs http://spacemacs.org/ which marries both vim and emacs and both of their difficulties. I’ll give my soapbox for why I like it, but be warned that if you are starting from absolutely no vim or emacs experience the learning curve along with this course may be too much.

1. Extensible. Spacemacs has a clean design written in lisp. There are 100s of packages ready to be installed by editing your spacemacs config and reloading that do everything from syntax checking, automatic static analyzing, etc.

2. Most of the good parts from vim and emacs. Emacs is good at doing everything by being a fast editor. Vim is good at making fast edits and moving around. Spacemacs is the best of both worlds allowing vim keybindings to all the emacs goodness underneath.

3. Lots of preconfiguration done. As opposed with a fresh emacs install, a lot of the configurations with language and projects are done for you like neotree, helm, various language layers. All that you have to do is navigate neotree to the base of your project and emacs will turn into an IDE for that programming language.

But obviously to each his or her own. Many people will argue that editor gurus spend more time editing their editors and actually editing.

Clean Code

Make your code modular using helper functions. If there is a repeated task (getting the pointers to contiguous blocks in the malloc MP, for example), make them helper functions. And make sure each function does one thing well so that you don’t have to debug twice. Let’s say that we are doing selection sort by finding the minimum element each iteration like so,

void selection_sort(int *a, long len){
     for(long i = len-1; i > 0; --i){
         long max_index = i;
         for(long j = len-1; j >= 0; --j){
             if(a[max_index] < a[j]){
                  max_index = j;
             }
         }
         int temp = a[i];
         a[i] = a[max_index];
         a[max_index] = temp;
     }

}

Many can see the bug in the code, but it can help to refactor the above method into

long max_index(int *a, long start, long end);
void swap(int *a, long idx1, long idx2);
void selection_sort(int *a, long len);

And the error is specifically in one function. In the end, this class is about writing system programs, not a class about refactoring/debugging your code. In fact, most kernel code is so atrocious that you don’t want to read it – the defense there is that it needs to be. But for the sake of debugging, it may benefit you in the long run to adopt some of these practices.

Asserts

Use assertions to make sure your code works up to a certain point – and importantly, to make sure you don’t break it later. For example, if your data structure is a doubly-linked list, you can do something like assert(node == node->next->prev) to assert that the next node has a pointer to the current node. You can also check the pointer is pointing to an expected range of memory address, non-null, ->size is reasonable, etc. The DEBUG macro will disable all assertions, so don’t forget to set that once you finish debugging (“Assert,”¹).

Here is a quick example with an assert. Let’s say that we are writing code using memcpy. We would want to put an assert before that checks whether my two memory regions overlap. If they do overlap, memcpy runs into undefined behavior, so we want to catch that problem than later.

assert(!(src < dest+n && dest < src+n)); //Checks overlap memcpy(dest, src, n);

This check can be turned off at compile-time, but will save you tons of trouble debugging!

---

1. “Assert.” n.d. Cplusplus.com. cplusplus.com. http://www.cplusplus.com/reference/cassert/assert/. ↩︎