6.031
6.031 — Software Construction
Spring 2022

Getting Started

6.031 requires you to get up to speed quickly. You need to:

  • set up your software development environment,
  • learn the basics of programming in TypeScript, and
  • learn basic version control with Git.

To learn TypeScript, you will start with Reading 2 and complete the reading exercises on that page. Over the next few weeks, you will do TypeScript Tutor exercises to practice writing code.

If you have any questions, or any trouble following the instructions below, please visit lab hours to ask questions and get help from TAs and LAs.

Lab hours and deadlines in the 1st week

Monday, Jan 31

Tuesday, Feb 1

Wednesday, Feb 2

Thursday, Feb 3

Friday, Feb 4

Class 1 at 11am

 

Lab hours
2-5pm in 24-323
7-10pm in 32-044

 

 

Lab hours
2-5pm in 24-323
7-10pm in 32-044

 

10pm: Reading 1 and Reading 2 reading exercises and TypeScript Tutor exercises due

11am before Class 2: Problem Set 0 Part I due, including all steps and GitStream exercises on this page. You must have Node, TypeScript, Visual Studio Code, Constellation, and Git set up and working on your laptop.

Lab hours
2-5pm in 24-323
7-10pm in 32-044

 

 

 
 
 

 

10pm: Reading 3 reading exercises and TypeScript Tutor exercises due

Class 3 at 11am

 

Regular lab hours begin Saturday

See the course calendar for the full schedule of office and lab hours. Lab hours may change depending on deadlines, so always check the calendar to see when lab hours are scheduled.

Step 1: Install TypeScript

1.1 Install Node

Go to the Node.js Downloads page, and then:

  • for Windows or macOS: use the Windows or macOS installer

  • for Linux: click on “Installing Node.js via package manager” at the bottom of the page, and find the appropriate package for your Linux flavor

Make sure you install the LTS version of Node, version 16.x.x. Do not install the “Current” version, it’s a bleeding-edge development version that is not supported long-term. If you already had an older version of Node installed, the installer will replace it with Node 16.

If the installer asks questions during installation, you can accept the default choices and just click Next.

After installing Node, confirm the installation and version by opening a terminal or command prompt and running:

node --version

It should report that you have version 16.x.y for some x, y.

1.2 Install TypeScript

After installing Node, open your terminal or command prompt, and run:

  • for macOS or Linux:

    sudo -H npm install -g typescript
  • for Windows:

    npm install -g typescript

You may see a deprecation warning like “deprecated uuid@3.4.0: Please upgrade to version 7 or higher.” You can ignore this warning.

Confirm that your installation was successful by running the TypeScript compiler:

tsc --version

It should report that you have TypeScript version 4.5.x (or higher).

Step 2: Install Visual Studio Code

Go to the Visual Studio Code download page, and download and install the appropriate installer for your platform. If you already have Visual Studio Code installed, you don’t need to reinstall it, just make sure it’s up to date by following the instructions below.

If the installer asks questions during installation, you can accept the default choices and just click Next.

Make sure that you have the latest version installed. Run Visual Studio Code, and either:

  • macOS: CodeCheck for Updates…
  • Windows/Linux: HelpCheck for Updates…

It should either say “No updates available”, or help you update to the latest version.

Finally, confirm the version you are running:

  • macOS: CodeAbout Visual Studio Code
  • Windows/Linux: HelpAbout

The first line of the dialog box should be version 1.63.x (or higher).

Step 3: Install TypeScript Tutor

TypeScript Tutor is 6.031’s tool for learning the syntax and semantics of TypeScript.

  1. Download the TypeScript Tutor extension, which will save to your laptop as a file called praxis.vsix.

  2. Run Visual Studio Code, and go to View → Extensions.

  3. In the upper right corner of the Extensions pane that appears, click on ..., then Install from VSIX…, then find and install the praxis.vsix file you just downloaded.

  4. Close Visual Studio Code and restart it.

  5. From the menubar, choose View → Explorer. Then look at the bottom of the lefthand pane for the TYPESCRIPT TUTOR heading. Click on that heading to make it visible. The TypeScript Tutor pane may say something like “Not Found” or “Oops. The Java Tutor doesn’t know who you are” which means you still have to configure it using the next few steps.
    (TypeScript Tutor is hosted on the Java Tutor server, so it may mention “Java” in its error messages. That’s okay.)

  6. Open the Settings panel:

    • Windows/Linux: File → Preferences → Settings

    • macOS: Code → Preferences → Settings

  7. Click here to get your personal start URL.
    (TypeScript Tutor is hosted on the Java Tutor server, so the URL will still include “Java” in several places. That’s okay.)

  8. In the box labeled Location: Personal Link, copy and paste your personal start URL.
    You should see the TypeScript Tutor immediately reload and show a page with “Basic TypeScript” at the top, which means it’s ready for use.

  9. Close the Settings panel.

Step 4: Install Constellation

Constellation is 6.031’s system for working on in-class programming exercises with a partner.

  1. Download the Constellation extension, constellation-vscode-0.4.7.vsix.

  2. In VS Code, go to View → Extensions, click on ..., then Install from VSIX…, and select constellation-vscode-0.4.7.vsix.

  3. Once again, close VS Code and restart it.

  4. Go to View → Command Palette, which brings up a search box that allows you to find and run any command in VS Code. Type “set up constellation” and select Set up Constellation.

    • Windows/Linux: if this fails with the error “certificate has expired,” open the VS Code Settings panel again and search for systemcertificates. Un-check the Http: System Certificates option, then restart VS Code and try again.

  5. Your web browser should open a Constellation page that requires MIT Touchstone login. Click the red Go! button.

  6. After following the prompts, you should see a “successfully authenticated and connected” notification in VS Code to confirm that Constellation is ready to use.

Step 5: Install Git

We will use Git on the command-line interface.

You may already have Git installed. If so, you do not need to install the latest version. Windows users should look for Git Bash. macOS and Linux users should open a terminal and try running: git

To install Git: from the Git project page, follow the link on the right side to download the installer for your platform. Follow the instructions in the README file in the downloaded .zip or .dmg.

Windows users should choose:

  • use Git from the Windows command prompt,
  • checkout Windows-style, commit UNIX-style line endings, and
  • add a shortcut to the Desktop

during the installation.

macOS: if you receive an “unidentified developer” warning, right-click the .pkg file, select Open, then click Open.

Step 6: Open the command line

One thing that makes learning Git harder for many students is that it’s a command-line program. If you’re not familiar with the command-line, this can be confusing.

A command-line is an interface to your computer, similar to the Mac Finder or Windows Explorer, except that it’s text-based. As the name implies, you interact with it through “commands” — each line of input begins with a command and has zero or more arguments, separated by spaces. The command-line keeps track of what directory (folder) you’re in, which is important to many of the commands you might be running.

On macOS and Linux, open the Terminal application.

On Windows, Git for Windows includes Git Bash. Run Git Bash to open a terminal where you can run all the commands below, in addition to Git commands.

Common commands

  • cd (stands for “change directory”)

    Changes the current directory. If you’re in a directory that has a subdirectory called hello, then cd hello moves into that subdirectory.

    Use cd .. to move to the parent directory of your current directory.

  • pwd (“print working directory”)

    Prints out the current directory, if you’re not sure where you are.

    On a well-configured system, your current directory is displayed as part of the prompt that the system shows when it’s ready to receive a command. If that’s not the case on your system, post on Piazza to get help configuring your prompt.

  • ls (“list”)

    Lists the files in the current directory.

    Use ls -l for extra information (a “long” listing) about the files. Use ls -a (stands for “all”) to show hidden files, which are files and subdirectories whose names begin with a period.

  • mkdir (“make directory”)

    Creates a new directory in the current directory. To create a directory called goodbye, use mkdir goodbye.

  • up arrow and down arrow

    Use up arrow to put the command you just ran back on the command line. You can now edit that command to fix a typo, or just press enter to run it again.

    Use the up and down arrow keys to navigate through your history of commands, so you never have to re-type a long command line.

Step 7: Set up Git and github.mit.edu

7.1: Configure npm to use Git Bash (Windows only)

If you are using Windows, run the following command so that your npm command will be able to build problem sets:

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

If you are using macOS or Linux, do not run this command.

7.2: Set preferences

Before using Git, we’ll do some required setup and make it behave a little nicer.

  1. Who are you?

    Every Git commit includes the author’s name and e-mail. Make sure Git knows your name and email by running these two commands:

    git config --global user.name "Your Name"
    git config --global user.email username@mit.edu
  2. Editing commit messages.

    Every Git commit has a descriptive message, called the commit message. Pick one of the two options below to set up your commit message editor.

    Option 1: set up an easy-to-use editor

    macOS and Linux: use nano

    nano is a simple text editor. It does not come with the Windows version of Git, so Windows users should choose a different option.

    To see if you have nano, try running:

    nano

    in the terminal. The result should be a simple editor with instructions at the bottom of the screen; quit with ctrl-X. If that worked:

    git config --global core.editor nano

    will configure Git to use the nano editor. The commands to use the text editor (like copy, paste, quit, etc.) will be shown on the bottom of the screen. The ^ symbol represents the ctrl key. For example, you can press ctrl-O to save (nano calls it “write out”) and then ctrl-X to quit.

    Windows: use Notepad

    You can change the default editor to Notepad with:

    git config --global core.editor notepad

    If you prefer to edit your commit messages in the terminal, choose Option 2 instead.

    Option 2: use Vim

    On macOS and Windows, your default editor will be Vim.

    On Linux, the default editor depends on your distribution.

    To see if you have Vim, try running:

    vim

    in the terminal.

    You start in a mode called “normal mode”. You can’t immediately type anything into the file!

    In order to start typing, press i (stands for “insert”). This will bring you to “insert mode”, so named because in this mode you can type text into the file.

    When you are done typing, press esc. This will bring you back to “normal mode”.

    Once you’re back in normal mode, you can type commands that start with :.

    To save your work, type :w (stands for “write”) and press return.

    To exit (quit) Vim, type :q and press return.

    To save and quit in one command, combine them: type :wq and press return.

  3. LOL.

    As we’ll see in step 8 of this guide, git log is a command for looking at the history of your repository.

    To create a special version of git log that summarizes the history of your repo, let’s create a git lol alias using the command (all on one line):

    git config --global alias.lol "log --graph --oneline --decorate --color --all"

    Now, in any repository you can use:

    git lol

    to see an ASCII-art graph of the commit history.

  4. To confirm that you set up Git properly, run

    git config --list

    and look for the settings you made in its output:

    user.name=...
    user.email=...
    ...
    core.editor=...
    ...
    alias.lol=log --graph --oneline --decorate --color --all
    ...

7.3: Connect to github.mit.edu

  1. Visit github.mit.edu and log in.

    Your problem set and project repositories for 6.031 will be stored on github.mit.edu.

  2. From the menu at the top right corner of the page, go to Settings, and select SSH and GPG keys.

  3. Follow the GitHub Enterprise instructions to set up SSH:

    1. Check if you already have SSH keys

    2. Generate a SSH key if you don’t have one

    3. Add the SSH key to your account – make sure you are working on github.mit.edu, not github.com

    4. Test the SSH connection – the hostname is github.mit.edu, and correct host key fingerprints are in the IS&T KB

Step 8: Learn the Git workflow

As you read: complete the GitStream exercises to practice using Git.

GitStream will not work with multiple exercise pages open at the same time.

Don’t open exercises in multiple tabs. If an exercise doesn’t work, please close all open GitStream pages and try again.

If you encounter a problem, please post on Piazza.

What is Git?

Git is a version control system (VCS). The Pro Git book describes what Git is used for:

Version control is a system that records changes to a file or set of files over time so that you can recall specific versions later. […] It allows you to revert selected files back to a previous state, revert the entire project back to a previous state, compare changes over time, see who last modified something that might be causing a problem, who introduced an issue and when, and more. Using a VCS also generally means that if you screw things up or lose files, you can easily recover.

Some of the most important Git concepts:

  • repository: A folder containing all the files associated with a project (e.g., a 6.031 problem set or team project), as well as the entire history of commits to those files.

  • commit (or “revision”): A snapshot of the files in a repository at a given point in time.

  • add (or “stage”): Before changes to a file can be committed to a repository, the files in question must be added or staged (before each commit). This lets you commit changes to only certain files of your choosing at a time, but can also be a bit of a pain if you accidentally forget to add all the files you wanted to commit before committing.

  • clone: Since Git is a “distributed” version control system, there is no concept of a centralized Git “server” that holds the latest official version of your code. Instead, developers “clone” remote repositories that contain files they want access to, and then commit to their local clones. Only when they push their local commits to the original remote repository are other developers able to see their changes.

  • push: The act of sending your local commits to a remote repository. Again, until you add, commit, and push your changes, no one else can see them.

  • pull: The act of retrieving commits made to a remote repository and writing them into your local repository. This is how you are able to see commits made by others after the time at which you made an initial clone.

Cloning

You start working with Git repos in 6.031 by cloning a remote repository into a local repository on your computer.

To do this, open the terminal (use Git Bash on Windows) and use the cd command to change to the directory where you would like to store your code. Then run:

git clone URI-of-remote-repo

or

git clone URI-of-remote-repo project-name

Replace URI-of-remote-repo with the location of the remote repository, and replace project-name with the appropriate project name, like ps0. The result will be a new directory project-name with the contents of the repository. This is your local repository.

After you have cloned a repository, you should navigate into the repository on your command prompt using cd. This lets you run git commands on the repository.

GitStreamPractice git clone

Note that GitStream doesn’t keep track of whether you’ve already done this exercise. To see which GitStream exercises you’ve already done, look at Omnivore.

Cloning problem sets: for each problem set in 6.031, you will have a repository on github.mit.edu.

Initially this remote repository only contains some template code.

To start working on the problem set, you will clone that repository onto your machine.

As you complete each part of the problem set, you will commit your changes to the local repository and then push them to the remote repository.

When the time comes for grading your assignment, we will clone the remote repository and look at the last commit you made and pushed there before the deadline.

Creating a commit

The basic building block of data in Git is called a “commit”. A commit represents some change to one or more files (or the creation or deletion of one or more files).

When you change a file or create a new file, that change is not part of the repository. Adding it takes two steps. First, run:

git add file.txt (where file.txt is the file you want to add)

You’ll either need to run that command from the same directory as the file, or include directory names in the file path.

This stages the file. Second, once you’ve staged all your changes, run:

git commit

This will pop up the editor for your commit message. When you save and close the editor, the commit will be created.

Getting the status of your repository

Git has some nice commands for seeing the status of your repository.

The most important of these is git status. Run it any time to see which files Git sees have been modified and are still unstaged and which files have been modified and staged (so that if you git commit those changes will be included in the commit). Note that the same file might have both staged and unstaged changes, if you modified the file again after running git add.

When you have unstaged changes, you can see what the changes were (relative to the last commit) by running git diff. Note that this will not include changes that were staged (but not committed). You can see those by running git diff --staged.

Pushing

After you’ve made some commits, you’ll want to push them to a remote repository. In 6.031, you should have only one remote repository to push to, called origin. To push to it, you run the command:

git push origin main

The origin in the command specifies that you’re pushing to the origin remote. By convention, that’s the remote repository you cloned from.

The main refers to the main branch, the default branch in our Git repositories. We won’t use branches other than main in 6.031. All our commits will be on main, and that’s the branch we want to push.

Once you run this, you will be prompted for your password and hopefully everything will push. You’ll get a line like this:

a67cc45..b4db9b0  main -> main

Merges

Sometimes, when you try to push, things will go wrong. You might get an output like this:

! [rejected]      main -> main (non-fast-forward)

What’s going on here is that Git won’t let you push to a repository unless all your commits come after all the ones already in the remote repository. If you get an error message like that, it means that there is a commit in your remote repository that you don’t have in your local one (on a project, probably because a teammate pushed before you did). If you find yourself in this situation, you have to pull first and then push.

Pulling

To perform a pull, you should run git pull. When you run this, Git actually does two things:

  1. It downloads the changes and stores them in its internal state. At this point, the repository doesn’t look any different, but it knows what the state of the remote repository is and what the state of your local repository is.

  2. It incorporates the changes from the remote repository into the local repository by merging, described below.

Merging

If you made some changes to your repository and you’re trying to incorporate the changes from another repository, you need to merge them together somehow. In terms of commits, what actually needs to happen is that you have to create a special merge commit that combines both changes. How this process actually happens depends on the changes.

If you’re lucky, then the changes you made and the changes that you downloaded from the remote repository don’t conflict. For example, maybe you changed one file and your project partner changed another. In this case, it’s safe to just include both changes. Similarly, maybe you changed different parts of the same file. In these cases, Git can do the merge automatically. When you run git pull, it will pop up an editor as if you were making a commit: this is the commit message of the merge commit that Git automatically generated. Once you save and close this editor, the merge commit will be made and you will have incorporated both changes. At this point, you should compile your code and run your tests (to make sure the merge really worked) and then try to git push again.

Merge conflicts

Sometimes, you’re not so lucky. If the changes you made and the changes you pulled edit the same part of the same file, Git won’t know how to resolve it. This is called a merge conflict. In this case, you will get an output that says CONFLICT in big letters. If you run git status, it will show the conflicting files with the label Both modified. You now have to edit these files and resolve them by hand.

First, open the files in Visual Studio Code. The parts that are conflicted will be really obviously marked with obnoxious <<<<<<<<<<<<<<<<<<, ==================, and >>>>>>>>>>>>>>>>>> lines. Everything between the <<<< and the ==== lines are the changes you made. Everything between the ==== and the >>>> lines are the changes you pulled in. It’s your job to figure out how to combine these. The answer will of course depend on the situation. Maybe one change logically supercedes the other, or maybe they can be merged somehow. You should edit the file to your satisfaction and remove the <<<</====/>>>> markers when you’re done.

Once you have resolved all the conflicts (note that there can be several conflicting files, and also several conflicts per file), you should compile your code and run your tests. Then git add all the affected files and then git commit. You will have an opportunity to write the merge commit message (where you should describe how you did the merge). Now you should be able to push.

Avoid merges and merge conflicts:

Pull before you start working

Before you start working, always git pull. That way, you’ll be working from the latest version of your code, and you’ll be less likely to have to perform a merge later.

Getting the history of the repository

You can see the list of all the commits in the repository (with their commit messages) using git log. You can see the last commit on the repository using git show. This will show you the commit message as well as all the modifications.

Long output: if git log or git show generate more output than fits on one page, you will see a colon (:) symbol at the bottom of the screen. You will not be able to type another command! Use the arrow keys to scroll up and down, and quit the output viewer by pressing q. (You can also press h for see the viewer’s other commands, but scrolling and quitting are the most important to know.)

Commit IDs: every Git commit has a unique ID, the hexadecimal numbers you see in git log or git show. The commit ID is a unique cryptographic hash of the contents of that commit. Every commit, not just within your repository but within the universe of all Git repositories, has a unique ID (with extremely high probability).

You can reference a commit by its ID (usually just by the first few characters). This is useful with a command like git show, where you can look at a particular commit rather than only the most recent one.

You will also see commits identified by ID in tools like github.mit.edu and Didit.

Reverting to previous versions

If you’d like to practice using the version history to undo a change:

GitStream → (optional exercise) Practice git log and git revert

We will revisit Git and learn more about version control in future classes. If you’ve installed the software and completed the GitStream exercises above, you’re ready to move on to Problem Set 0.