Lab 1 — Install the stack

VS Code, R, Quarto, TinyTeX (and optional Git / Claude Code)

This lab gets every required tool installed and rendering one Quarto document end-to-end. It is the practical companion to Week 1 — Your first render, which is the short conceptual reading for Week 1.

Work through this top to bottom. If you get stuck on a step, come to one of the scheduled studio meetings in the MAC or email me.

What you’ll have at the end

  • R (the computation language) installed.
  • VS Code — Visual Studio Code, the course’s standard editor — installed.
  • Quarto installed and runnable from a terminal.
  • TinyTeX (a minimal LaTeX distribution, installed through R) set up so Quarto can render PDFs.
  • A minimal set of VS Code extensions for the course workflow (Quarto, R).
  • (Optional) Git installed.
  • (Optional) Claude Code mentioned — not required, not assumed.
  • A math-software-portfolio/ folder somewhere sensible on your computer.
  • A .qmd file that renders to both HTML and PDF without errors.

If you already have some of these — great, skip ahead.

NoteVS Code, not Visual Studio

The course standard is Visual Studio Code (also called VS Code). This is the free, cross-platform editor from Microsoft. It is not the same product as Visual Studio (the much heavier Windows-only IDE). If the installer screen says “Visual Studio 2022” or shows project templates for .NET / C++ / mobile apps, you have the wrong product. Cancel and start over with Visual Studio Code from https://code.visualstudio.com.

0. Pick a portfolio location

Make a folder you will not move or rename for the semester. Suggested:

  • macOS / Linux: ~/Documents/math-software-portfolio/
  • Windows: C:\Users\YourName\Documents\math-software-portfolio\

Inside that folder, create a hw01/ subfolder. You’ll put your first .qmd there.

1. Install R

Download R from https://cran.r-project.org and install with all defaults.

  • macOS — pick the .pkg file matching your chip (Apple Silicon or Intel).
  • Windows — pick the .exe installer.
  • Linux — use your package manager (apt, dnf, etc.) or follow CRAN’s instructions for your distro.

Verify: open a terminal (Terminal on mac/Linux, PowerShell on Windows) and run:

R --version

You should see a version string. If the terminal says the command is not recognized, restart the terminal and try again. If it still fails, R is not on your PATH — flag this in the MAC.

2. Install VS Code

Download Visual Studio Code from https://code.visualstudio.com and install with the defaults.

  • macOS — drag Visual Studio Code.app into /Applications.
  • Windows — pick the User Installer for your architecture. During install, leave “Add to PATH” checked.
  • Linux — install the .deb/.rpm, or use your distro’s package manager.

Verify: open VS Code. You should see the Welcome page and a sidebar with file/Explorer/extensions icons. Open a terminal inside VS Code (View → Terminal, or Ctrl/Cmd + `) and run:

code --version

You should see a version string.

If the screenshots online showing four panes and an “RStudio” title bar look very different from what you see — that is expected. VS Code has a different layout than RStudio. You are in the right place.

3. Install Quarto

Download Quarto from https://quarto.org/docs/get-started/ and install with the defaults.

Verify: in a terminal (system terminal or VS Code’s integrated terminal):

quarto --version

You should see a version string like 1.x.y.

4. Install TinyTeX (from R)

TinyTeX is a small, install-on-demand LaTeX distribution. It lets Quarto render PDFs and lets you compile .tex files. It is installed through R, not as a separate download.

Start an R session. You can do this from any terminal by running R, or you can open VS Code’s terminal and run R there. Then run:

install.packages("tinytex")
tinytex::install_tinytex()

The install can take a few minutes. If install_tinytex() finishes without errors, you’re done.

Verify (still in R):

tinytex::tinytex_root()

This should print a path like /Users/you/Library/TinyTeX or C:\Users\You\AppData\Roaming\TinyTeX.

Exit R when you’re done with q() (answer n when asked about saving the workspace).

5. Install VS Code extensions

VS Code becomes useful for this course once you install two extensions. Open VS Code → Extensions sidebar (the four-blocks icon) or press Ctrl/Cmd + Shift + X, then search and install:

Extension Publisher What it does for this course
Quarto quarto.quarto Recognizes .qmd files. Adds the Quarto: Preview command (and a preview pane). Code-cell syntax highlighting.
R REditorSupport R syntax highlighting, R terminal integration, package help.
ImportantInstall the Quarto extension, and check the language mode

The Quarto extension is what makes .qmd files work in VS Code. If it is not installed, VS Code may treat your file as Plain Text and none of the Quarto features will activate. After installing it, open a .qmd file and look at the lower-right corner of the VS Code window: it should say Quarto (or Quarto Markdown / Markdown), not Plain Text. If it says Plain Text, click that label and pick Quarto (or Markdown) from the list. Also confirm the file name actually ends in .qmd.

Optional, install if you’ll use them:

Extension Publisher When you’d want it
GitLens or GitHub Pull Requests (various) Only if you use Git/GitHub for your portfolio.
vscode-pdf tomoki1207 Lets you preview rendered PDFs inside VS Code.

After installing the R extension, you may also want to install the R language-server package from inside R:

install.packages("languageserver")

This unlocks autocomplete and inline help when editing R code in VS Code.

6. (Optional) Install Git

Git is optional for this course. You only need it if you plan to make your portfolio a public or private GitHub repository. A local folder works fine.

  • macOS — git ships with Xcode command-line tools. Run xcode-select --install if not already done.
  • Windows — install Git for Windows from https://git-scm.com/download/win.
  • Linux — sudo apt install git (or your distro’s equivalent).

Verify: git --version in a terminal.

If you choose to use a GitHub repo for your portfolio, see the optional “first portfolio repo” lab later in the term.

7. (Optional) Claude Code

Claude Code is Anthropic’s AI-assisted coding tool. It is a plausible advanced helper for technical work in this course — it can edit files, run terminal commands, and read project structure under your supervision. It is completely optional, requires a paid Anthropic account, and no part of the course assumes you have it.

If you choose to try it, follow the official install instructions at https://docs.claude.com/en/docs/agents-and-tools/claude-code. Pin its working directory to your math-software-portfolio/ folder so it cannot see unrelated files on your computer. The same AI Use Note expectations apply (Tool / Purpose / Verification — see the AI use guidelines).

8. Render your first Quarto document

In your hw01/ folder, create a file called hw01.qmd with these contents:

---
title: "Hello, Quarto"
author: "YOUR NAME"
format:
  html: default
  pdf: default
---

# A first equation

The quadratic formula:

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.
$$

# A first R chunk

```{r}
set.seed(1)
x <- rnorm(10)
mean(x)
```

# AI Use Note

**Tool:** [assistant name and approximate version, or "did not use AI"]
**Purpose:** [what you used it for, if any]
**Verification:** [how you checked the output, if any]

You have two ways to render the file. Use either; both produce the same result.

Preferred — VS Code “Quarto: Preview”. Open the hw01/ folder in VS Code (File → Open Folder…). Open hw01.qmd in the editor. Then:

  1. Press Ctrl/Cmd + Shift + P to open the Command Palette and run Quarto: Preview, or
  2. press the keyboard shortcut Ctrl/Cmd + Shift + K, or
  3. if the Quarto extension shows a Preview button in the upper-right editor toolbar, click that.

All three do the same thing. The first PDF render can take 30–60 seconds because TinyTeX is downloading packages on demand.

Always works — terminal. Open a terminal in the folder that contains the .qmd file (VS Code’s integrated terminal works fine; you don’t need to leave the editor) and run:

cd path/to/math-software-portfolio/hw01
quarto render hw01.qmd

Either way, you should see hw01.html and hw01.pdf next to your .qmd.

Common problems

This is the realistic-troubleshooting section. Skim it before you start; come back to it when something breaks.

Wrong product installed

  • You installed Visual Studio instead of Visual Studio Code. The giveaway is a Microsoft installer screen showing .NET / C++ / mobile-app workloads, or a Start menu entry called “Visual Studio 2022”. Uninstall it (or leave it alone) and install Visual Studio Code from https://code.visualstudio.com.
  • You installed the R extension but R itself is not installed. The extension cannot find an R binary. Install R first (Section 1), then restart VS Code.

VS Code can’t find R

  • VS Code Quarto extension says “R not found.” Quarto needs to know where R lives. The fix is almost always: (1) confirm R --version works in a fresh system terminal, (2) close and reopen VS Code so it picks up the updated PATH.
  • Windows-specific. If R installed to a non-standard location, you may need to add it to PATH manually: System Properties → Environment Variables → add R’s bin directory.

Quarto can’t find R when rendering

  • Render errors with “Unable to locate R.” Make sure R was installed before Quarto. Reopen the terminal you’re rendering from. On Windows, log out and back in if the terminal still does not see R.

PDF render problems

  • First PDF render fails on a fresh TinyTeX. Run quarto render hw01.qmd a second time — TinyTeX downloads missing LaTeX packages on demand the first time it sees them. The second render usually succeeds.
  • PDF render fails with “tlmgr” / “package not found” errors. Run tinytex::tlmgr_install("PACKAGE_NAME") in R for the named package, or just rerun quarto render — Quarto will request the package.
  • PDF compiles but math is missing. You probably wrote \$x\$ instead of $x$. Drop the backslashes.

Terminal / PATH problems

  • quarto: command not found (mac/Linux) or 'quarto' is not recognized as the name of a cmdlet... (Windows PowerShell). Quarto isn’t on your PATH. Quit and reopen the terminal. If that doesn’t work, the installer didn’t finish — reinstall and watch for permission prompts.
  • Windows: opening a new PowerShell doesn’t pick up the new PATH. Close every PowerShell window, then open a fresh one. Sometimes a full sign-out / sign-in is needed.

VS Code workflow snags

  • You opened a single .qmd file instead of a folder. Open the folder (hw01/) via File → Open Folder, not the single file. The Quarto extension behaves better with a folder open and a workspace set.
  • R chunk doesn’t run. Make sure the fenced code block is written exactly as ```{r} (lowercase r, no extra spaces inside the braces).
  • No Quarto commands, or the file shows as “Plain Text”. Look at the lower-right corner of the VS Code window. If it says Plain Text, the Quarto extension hasn’t taken over the file. Click the Plain Text label and choose Quarto (or Markdown). If there is no Quarto option at all, the Quarto extension is not installed or not enabled — open the Extensions sidebar, search “Quarto,” confirm the publisher is quarto.quarto, and install/enable it. Also confirm the file name ends in .qmd. When in doubt, fall back to the terminal: quarto render hw01.qmd.
  • “No valid input files passed to render”. The terminal is not in the folder that holds your .qmd, or the filename is misspelled. Run ls (mac/Linux) or dir (Windows) to confirm hw01.qmd is listed in the current folder, cd into the right folder if not, and check the spelling of the filename in your quarto render command.

“I keep finding RStudio instructions online”

Most R tutorials assume RStudio because it has been the dominant R editor for years. The good news: the R language itself is identical. Anything an RStudio tutorial tells you to type at the R console works identically when you type it in an R terminal session inside VS Code (just run R in the terminal, then type). When a tutorial says “click the Render button in RStudio,” the equivalent in VS Code is to run Quarto: Preview from the Command Palette (Ctrl/Cmd + Shift + P), press Ctrl/Cmd + Shift + K, or run quarto render in a terminal.

If you already know RStudio well and prefer it for R work, you can use it for editing R-only files. The course’s standard for all in-class demos, screenshots, and walkthroughs is VS Code, so plan to follow VS Code conventions for any cross-checking work and at the Setup conference.

What this prepares you to do

When you finish this lab you should be able to:

  • run R, VS Code, Quarto, and TinyTeX on your own computer,
  • find your math-software-portfolio/ folder and a hw01/ subfolder inside it,
  • open the portfolio folder in VS Code,
  • edit a .qmd source file in VS Code,
  • render that source to both HTML and PDF without errors,
  • locate the rendered files next to the source.

The Week 1 assignment in the course LMS uses exactly this workflow — the course LMS holds the prompt, the file-naming convention, and the submission area. The Week 1 Setup conference is where we confirm together that the chain works end-to-end; be ready to show your rendered document, your source file, and your portfolio folder in VS Code when we meet.