VS Code Tutorial Revisions

[jamesjuett]

This PR contains revisions to the VS Code tutorials. It incorporates some changes to smooth out minor incompatibilities with the new P1, adjustments for the move to Ubuntu-24.04, and other revisions.

I'd put it at moderate urgency, because I believe the changes will make setup significantly smoother for current students.

Significant Revisions

• Now covers the integrated terminal in VS Code.
• More clearly delineates running from terminal vs. debugging through VS code i.e. launch.json.
• Update instructions for creating project directory.
• Removes some redundant or outdated pitfalls. Moves a few to the WSL Setup tutorial.
• Adds more context/explanation for some commands.
• Fixes #194

The hierarchy of the page is changed:

• Add existing files (i.e. starter files) comes first. Then add new files.
• Multi-level hierarchy for configuring launch.json and debugging.

It also attempts to resolve a few issues that result from students literally using this to set up P1 AND students using the tutorial for a later project in EECS 280 (or for people not in EECS 280 at all).

• Adds a few indicators of where students only do things for EECS 280 P1
• Removes implied requirement of creating main.cpp (we can potentially now remove the instructions from most of our project specs that students need to remove this if the setup had them create it).
• Creates stats.cpp rather than main.cpp as an example of creating a new file - this will be more compatible with the new P1.
• Provides the .main.cpp and Makefile used in the debugging example as downloadable files (wget -nc to avoid clobbering existing files), but only used if they walk through the example.

Some images are updated, and most didn't need to be. There are a few slightly outdated images not showing the exact set of new F24 P1 files, and I've created #195 for that, but I think it's lower priority and shouldn't block these updates.

Section Headings

I double checked that no links are broken as a result of changes to some section headings (or removing others). I did this by inspecting a grep across all our relevant repositories, e.g.:

grep -r "#debug" p1-stats p2-cv p3-euchre p4-editor p5-ml tutorials/docs

Here's my accounting of the ones that have changed.

"Run" -> "Launch Debugger" (was not linked from anywhere) "Run" -> "Run" (another heading called run, was not linked from anywhere) "Arguments and Options" -> "Command Line Arguments and Options" (preserved old heading via anchor tag) "Debug" (There were multiple headings called "debug". None are linked except internally within the vscode mac tutorial. They're still good.) "Breakpoint" -> "Set Breakpoints" (was not linked from anywhere)

Try it out

I've walked through the updated version on these platforms:

• [x] Windows 10 machine with complete factory reset
• [x] Windows 11 machine, fresh Ubuntu-24.04 (but with other Ubuntus and previous vscode install)
• [x] M1 Mac with complete factory reset

[github-actions[bot]]

The spec from this PR is available at https://preview.sesh.rs/previews/eecs280staff/tutorials/192/.

^{(Available until Sun Sep 29 2024.)}

[jamesjuett]

@awdeorio I think this is ready to re-review. In 254fe00, I've implemented the changes we discussed so that the sample main.cpp and Makefile are introduced earlier. Run/Debug examples now use main.exe rather than anything specific to P1.

The changes are compatible with the current P1, since we have a main.exe target in the Makefile there for compatibility purposes. (So current EECS 280 students are expected to wget/create the sample tutorial files, then the P1 starter files. That will clobber the Makefile, but it's compatible.)

Thanks for the feedback and suggesting these changes! I think having the prominent set of sample files for the tutorial will work well for both 280 and non 280 folks.

[jamesjuett]

Thanks for the improvements! LGTM