Back to top

System Setup

— Christopher Genovese and Alex Reinhart

It will be easiest if everyone in the class has a similar setup for the their class repositories and common tools (e.g., Git, Python, R), so we can provide instructions that apply to everyone. These instructions will get you set up and running. You should only need to do this once per computer you use.

Pre-Setup #

Windows #

On Windows, you will need to install some software to get access to a traditional Unix shell. Fortunately, Microsoft has made this very easy with the Windows Subsystem for Linux (WSL). (We will be using WSL version 2, throughout.)

Complete instructions for the installation can be found here, but it’s actually quite easy:

  1. Open a PowerShell or Windows Command Prompt as an administrator.

    (A simple way to do this is enter powershell in the search bar and right click on the icon that comes up. Select “Run as administrator”.)

  2. At the powershell prompt, enter

    wsl --install

    This will install the software and the Ubuntu Linux distribution it uses and then will prompt you to select a username and password for your linux shell. Microsoft has recommended practices on this choice.

You should be set to go. To start a shell, enter wsl at the powershell prompt and get busy. You can also do wsl SHELLCOMMAND, replacing SHELLCOMMAND with a shell command, for a one-off.

When you first start out, you might want to enter the command

sudo apt update && sudo apt upgrade

in your linux shell, to upgrade all your commands to their latest version.

It is worth mentioning that a functional (but slightly more limited) shell experience is installed with git on windows, called Git Bash, which you can start from the

Mac #

Mac users do not need any special setup to access the shell and related commands. However, I highly recommend that you install Homebrew, a popular package manager for the Mac. This makes it easy to install, update, and remove a wide variety of useful tools. Definitely worthwhile.

Follow the link for details instructions, but the quick start is to paste the following a terminal shell prompt:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installation will give you some instructions, such as running brew doctor to check your installation. Enter brew help to see a summary of commands. A typical command looks like

brew install git

Linux #

No pre-setup is required for linux users.

Install Common Software #

  1. Install Git.

    • If you installed Git more than six months ago, upgrade to the latest version. You can do this by simply downloading and installing the latest version from the Git website.
    • On Windows, the installer will ask lots of questions. The defaults are all fine. If you plan to use Visual Studio Code, be sure it selects the option to use Visual Studio Code as Git’s default editor.

  2. Install a text editor.

    There is a large variety of good editors to choose from. VS Code is currently the most popular; it’s a easy to setup and comes “batteries included.” I prefer Emacs, but it does have a steeper learning curve. Use this list of good editors for guidance and help.

    In addition, try setting up your editor’s extensions for your favorite programming languages. All have extensions for R and Python that provide interactive support for programming, including syntax checking, documentation, consoles, and debuggers.

  3. Install R if you do not already have it.

  4. Install RStudio Desktop (the free version) if you do not already have it and intend to use R.

  5. Install Anaconda if you have not done so before. This includes Python and makes it easy to install many packages that have complicated requirements. Choose the Python 3 version.

    • The installer will ask if you want to install Visual Studio Code. If you don’t already have a preferred text editor, answer yes. VS Code is free and works well with R, Python, and many other languages.
    • Visual Studio Code has extensions for many languages. We recommend installing the Python extension and this R extension.

GitHub setup #

  1. Register for a GitHub account if you do not have one. You may use any username you prefer; we will later ask for your username so we can keep track.

  2. Set up a GitHub Personal Access Token if you have never done so before. This token is what you Git will use to log in to GitHub; any time Git asks you for a username and password (such as to clone a repository), provide your GitHub username and your Personal Access Token. The token only needs the repo scope. Select an expiration date after the end of the semester.

  3. Install Git Credential Manager (optional but recommended)

    I recommend that you install Git Credential Manager, which makes it easier to authenticate without having to repeatedly enter your access token.

    For Windows users, this be installed by default when you install Git for Windows. Windows users using WSL do not need to install Git Credential Manager in the subsystem; the subsystem shares the parent information.

    For Mac and Linux users and extra step is required, as described at the previous link.

    For example, using homebrew on the Mac, enter these commands

    brew tap microsoft/git
brew install --cask git-credential-manager-core

    On Ubuntu/Debian style Linux distributions

    sudo dpkg -i <path-to-package>

    We will configure git to use this in a later step.

  4. Follow the link, sent to you in a Canvas announcement, to get a GitHub repository for your homework assignments.

Configuring R and Python #

Windows #

Windows users using Anaconda need to configure their shell (e.g., WSL or Git Bash) so it can run Python. Open the “Anaconda Prompt” program and run this command:

conda init bash

It may complain “Operation failed”, but as long as you see modified next to the listing ending in .bash_profile, it should be fine.

Next, open Visual Studio Code (if you’re using it). Use the gear icon in the lower left to open the Settings page, then use the icon in the top right labeled “Open Settings (JSON)” to open settings.json. Make settings.json look exactly like this:

{
  "terminal.integrated.defaultProfile.windows": "WSL",
  "terminal.integrated.profiles.windows": {
    "PowerShell": {
      "source": "PowerShell",
      "icon": "terminal-powershell"
    },
    "Command Prompt": {
      "path": [
        "${env:windir}\\Sysnative\\cmd.exe",
        "${env:windir}\\System32\\cmd.exe"
      ],
      "args": [],
      "icon": "terminal-cmd"
    },
    "Git Bash": {
      "source": "Git Bash"
    },
    "WSL": {
      "path": [
        "C:\\WINDOWS\\System32\\wsl.exe"
      ],
      "args": [],
      "icon": "terminal-ubuntu-wsl"
    }
  },
  "r.rterm.windows": "C:\\Program Files\\R\\R-3.6.1\\bin\\x64\\R.exe"
}

(Make sure the version in r.rterm.windows, 3.6.1 in this case, matches the version number of R you installed. If you don’t know the version, open R Studio. The first thing it shows in the console is the text “R version…” with the number.)

Save the file. Next, open the Terminal menu on the top and select New Terminal. We’ll use this terminal to run the following commands.

For those of you not using Visual Studio Code, you should open a shell to run the following commands.

cd ~
curl https://36-750.github.io/setup-profile.py | python -

You should see a message that it “Successfully installed settings” to a file. Before proceeding, type exit in the terminal, hit Enter, and then open a new terminal. The settings will not take effect until you open a new terminal.

The setup-profile.py script does a few things: it sets up Python and R to work correctly on Windows in the shell, adds R to the PATH so the shell can find it, and sets your home directory to be C:/Users/yourusername/Documents.

Mac and Linux #

Mac and Linux users should be able to run Python and R from the command line with no extra setup, once they are installed. You should verify that they run correctly by opening a terminal and running these commands:

R --version
python --version

(You can use the terminal inside Visual Studio Code, use the Terminal app included with macOS, or use your favorite Linux terminal program.)

These commands should print out the versions of R and Python you have installed. Make sure you installed Python 3, not 2, preferably Python 3.5 or higher.

Mac users using Visual Studio Code: Follow these instructions so the code command works from the command line (e.g. so Git can use it to edit commit messages).

Set Your Git Config #

When Git records commit messages, it records them with your name and email address so that when you collaborate with others, they know who made which commits. You need to tell Git your name and email before you use it. In a terminal, run the commands:

git config --global user.name "Your Name"
git config --global user.email "youremail@example.com"

If you use the email address you used on GitHub, then GitHub will automatically link your commits to your account.

On your computer, you have default programs: programs that the operating system knows to use to open specific types of files. Git also has the idea of a “default editor”. It uses this editor when you write a commit message, and in certain other circumstances. You should set this editor to the text editor that you like to use, e.g., the editor you installed in an earlier step.

Run one of these commands in a terminal (or WSL/Git Bash), depending on the editor you picked:

# Visual Studio Code:
git config --global core.editor "code --wait"

# Emacs:
# There are various options here, ask Chris
# A good choice: put (server-start) in your init file and use
git config --global core.editor emacsclient

# Vim:
git config --global core.editor vim

# Atom:
git config --global core.editor "atom --wait"

Note that RStudio does not support being used as the Git editor, so you should install an editor like Visual Studio Code as a backup editor.

Also, you can use any of these editors at the command line to edit a file. For example, run the command code foo.txt to open the file foo.txt in Visual Studio Code to edit.

Windows users may want to standardize handling of line end characters by setting

git config --global core.autocrlf true

For Linux or Mac users, the analogous setting is

git config --global core.autocrlf input

If you installed Git Credential Manager above, then for Mac and Linux users, a step is required to tell git to use it.

If you are using homebrew on the Mac (recommended), enter these commands

git config --global credential.helper /usr/local/share/gcm-core/git-credential-manager-core

You can replace the last pathname by the location of the credential manager program if you installed it some other way.

On Ubuntu/Debian style Linux distributions, do:

git-credential-manager-core configure

Create a Class Directory and Move There #

Now move to your home directory. Create the s750 directory and move into it.

cd ~
mkdir s750
cd s750

The s750 directory is where you will keep all your work for this course throughout the semester.

Setting Up Your Repositories #

When you have Git installed and have a GitHub account, do the following. Otherwise, you should do both those earlier steps before proceeding.

If you try to do this later, remember to do it only after doing cd ~/s750 first.

  1. Clone the course repositories

    git clone https://github.com/36-750/documents.git
git clone https://github.com/36-750/problem-bank.git

    You may need to enter your GitHub access token. If using Git Credential Manager, you will only need to do this once every so often.

    You might get an error when you run the second command. There are two possibilities:

    • If the error says you do not have permission or the repository is not found, you need to check your email for the GitHub invitation to join the 36-750 organization, and accept the invitation. Wait for this invitation before proceeding. It may not arrive immediately – we send the invitations manually every day or so.

    • If the error says that “Support for password authentication was removed”, remember that you need to provide a GitHub Personal Access Token, not your GitHub password. If Git did not ask you for a password, it likely has stored a password you used for GitHub several years ago. Removing the old password depends on which version of Git you used and what operating system you had, so if you’re not sure how to do it, ask us for help.

  2. Clone your assignment repository. Do

    git clone https://github.com/36-750/assignments-YOURUSERNAME.git

    replacing YOURUSERNAME with your GitHub account name in the command.

  3. Verify that everything looks right:

    ls ~/s750

    should list three directories: documents, problem-bank, and assignments-YOURUSERNAME. If this is not what you see, verify that you followed the steps above, or ask us for help.

Installing the new-homework Script #

The new-homework script is provided in your assignment repository. Before you can run the script, you’ll need to install a Python package that lets Python scripts use Git. Run

pip install GitPython

and let it install the GitPython package. (This is like installing a package from CRAN in R.)

Move to your assignment repository and try running the script to make sure it worked. It should print out a brief summary of its options:

cd ~/s750/assignments-YOURUSERNAME
python new-homework.py

If you get a message like “command not found”, something is wrong with your Python installation. Check that you have it installed or ask us for help.

Directions for using the new-homework command are provided in the Assignment Instructions.

© Christopher R. Genovese and Alex Reinhart, 2022. This site is generated using Hugo 0.119.0 + Onyx