Suggestion: Sample launch.json files with comments.

[jamesjuett]

What
The proposal has 2 complementary ideas:

• Provide sample launch.json files for students to copy, rather than creating via the interface.
• Add comments to the launch.json file to explain what each part does and provide guidance on any edits.

Where
Mac/Windows setup tutorials for VS Code. OR, a separate location for sample launch.json files (if e.g. we wanted to host them for various courses).

Idea 1 - Provide Sample launch.json Configurations
Creating launch.json through the VS Code interface is OK, but there are a few annoyances:

• If students haven't opened a C++ file, they aren't provided the correct option in the dropdown to add a configuration.
• CodeLLDB fails to create launch.json when rust is not installed #224 where a bug in the CodeLLDB extension made the dropdown launch.json creation not work.
• Students clicking the wrong thing or being unsure whether they want e.g. C++ (GDB/LLDB) vs. CodeLLDB

I think creating a launch.json file manually (e.g. mkdir -p .vscode && touch .vscode/launch.json) or via the interface and then copying in a configuration is probably more reliable.

And, I don't think there's any pedagogical loss in providing a sample launch.json config - we already tell them exactly what to click and then a default config pops up. To be honest, any time I've ever configured something myself, the first thing I do is look for a sample online, e.g. https://tsx.is/vscode.

The sample files could be copied out of the tutorial page, or provided via a wget like our sample .gitignore. We would need one sample for Windows+WSL and one for Mac. (I don't think we need a different sample for different projects.)

(For Mac, we could potentially maintain two examples, one for CodeLLDB and one for the MS extension, or only provide the CodeLLDB version. Regardless, having a note to double check the "type" against your installed extension would be helpful for students who get that mixed up.)

We could also consider whether it might make sense for EECS 280 to maintain several sample launch.json configs that may be used by other courses.

Idea 2 - Explanatory Comments in launch.json
If students don't understand the configuration, it's hard for them to adapt, even in small ways (e.g. setting up command line arguments).

Adding comments to a sample launch.json puts the key information right there for students when they are looking at launch.json. It also serves as a clear guide for "change this if you need to do X". While .json files don't universally support comments, VS Code treats launch.json specially (and in fact the generated one has comments).

My hope is that students would also create multiple configurations (rather than editing "program", "args", etc. back and forth) and that the process of copying and updating the configuration options will actually help them learn and remember what each piece does better.

Example

I put together a quick example for Windows+WSL in EECS 280.

{
  "version": "0.2.0",

  // A list of debug configurations. You may add more, separated by commas.
  // The name you specify is shown in a dropdown menu on the debug panel.
  // To run a configuration, select it there and click the green play button.
  // EXAMPLE - for the euchre project, you might create configurations for:
  //  - "Card Public Tests" (running card_public_tests.exe)
  //  - "Card Tests" (running card_tests.exe)
  //  - "Euchre Test 00" (running euchre.exe, with arguments for test 00)
  //  - "Euchre Test 01" (running euchre.exe, with arguments for test 01)
  //  - (similar configs for Pack, Player, and other Euchre tests)
  "configurations": [
    
    // EXAMPLE - Windows+WSL C++ Debugging
    // Edit/copy this config. Customize the appropriate properties.
    {
      // The name of this configuration, shown in the debug panel dropdown.
      "name": "EXAMPLE",

      // The type of debugger to use. On Windows+WSL this should be "cppdbg".
      // (You must also have the C++ extension installed.)
      "type": "cppdbg",
      "request": "launch",

      // The program to debug. (Examples: card_public_tests.exe, euchre.exe).
      // REMEMBER - you must compile/recompile your program before debugging!
      "program": "${workspaceFolder}/example.exe",

      // Command line arguments to pass to the program when debugging.
      // Example: ["pack.in", "noshuffle", 3, "Ivan", "Human", ...]
      "args": [],

      // Set the current working directory for the debugged program, where
      // input files are expected to be found. For EECS 280 projects, this
      // is the top-level project directory, using ${workspaceFolder}.
      "cwd": "${workspaceFolder}",

      // Environment variables to set for the debugged program. If compiling
      // with the AddressSanitizer (ASan) enabled, uncomment the ASAN_OPTIONS.
      "environment": [
        // {
        //   "name": "ASAN_OPTIONS",
        //   // Pause on ASan errors. Disable ASan leak checker, which doesn't
        //   // play nicely with debuggers.
        //   "value": "abort_on_error=1:detect_leaks=0" 
        // }
      ],

      ///// You probably don't need to configure options below this line //////

      // If true, automatically pause debugger at the first line of main().
      "stopAtEntry": false,

      // Generally set to false to use the integrated terminal in VS Code.
      "externalConsole": false,

      // The debugger to use. On Windows+WSL, use "gdb".
      "MIMode": "gdb",

      "setupCommands": [

        // Enable pretty-printing for gdb to improve display of STL containers.
        {
          "description": "Enable pretty-printing for gdb",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ]
    }
  ]
}

Another example from my 498 for debugging a TypeScript program run via tsx:

{
  "version": "0.2.0",

  // launch.json defines debugging configurations. You can select among
  // the configurations from the dropdown menu in the Debug left panel.

  "configurations": [

    // Debug the active TS file (i.e. the one open in the editor).
    // If you launch while looking at launch.json, you'll get an error!
    {
      "name": "Debug Current File (tsx)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",// "npx tsx" with the current file.
      "args": [ "tsx", "--", "${file}"],
      "cwd": "${workspaceFolder}", // Set working directory to workspace root.
      "console": "integratedTerminal", // Necessary for user input via stdin.
      "internalConsoleOptions": "neverOpen", // Don't focus debug console automatically.
      "sourceMaps": true, // Enable source maps for TypeScript debugging.
      "skipFiles": [ // Don't step into libraries or dependencies when debugging.
        "<node_internals>/**",
        "${workspaceFolder}/node_modules/**",
      ],
      "smartStep": true, // Skip over implicitly generated code when stepping.
    },

    // Edit/copy this configuration, replacing EXAMPLE with your own filename,
    // if you would like a dedicated debug configuration for a specific file.
    {
      "name": "Debug EXAMPLE (tsx)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx", // "npx tsx" with file below.
      "args": [ "tsx", "--", "src/EXAMPLE.ts"],
      "cwd": "${workspaceFolder}", // Set working directory to workspace root.
      "console": "integratedTerminal", // Necessary for user input via stdin.
      "internalConsoleOptions": "neverOpen", // Don't focus debug console automatically.
      "sourceMaps": true, // Enable source maps for TypeScript debugging.
      "skipFiles": [ // Don't step into libraries or dependencies when debugging.
        "<node_internals>/**",
        "${workspaceFolder}/node_modules/**",
      ],
      "smartStep": true, // Skip over implicitly generated code when stepping.
    }
  ]
}

[hardy-ethan]

i like it. it could also be interesting to have our own extension they could (optionally?) install which would allow them to choose the sample launch.jsons from a vscode modal

[awdeorio]

Some time ago, we used to provide a copy-paste launch.json. On the upside, it's quick and easy to copy, paste, debug. There were two downsides that I can remember. The first was maintaining the copy. When sometime in an extension changed, we needed to update our sample. The second was students configuring their debugger for subsequent projects (in EECS 280 as well as other courses). They had to remember how/where to find the thing they needed to copy to get it working.

WDYT about a hybrid approach? Maybe put something under https://eecs280staff.github.io/tutorials/setup_vscode_macos.html#create-launchjson where we say that its an alternative to copy/paste X into launch.json.

EDIT: I'd also be fine with adding a subsection for other courses.

[jamesjuett]

I don't estimate there would be a significant maintenance burden to maintain a sample launch.json for each EECS 280 environment and/or extension.

In principle, VS Code and extension maintainers should have an incentive not to make updates that break existing launch.json files, which I think offers some reassurance for the future. If new config options are added or there is a deprecation (e.g. ${workspaceRoot} vs. ${workspaceFolder}), there should be a pretty forgiving window for us to update.

I looked briefly through this repo and p1-stats back to some of the originals in 2018 and I can't really find cases where a config would have changed out from under us. Of course, the launch.json we provided changed e.g. going from Cygwin to WSL 1 to WSL 2, or switching back and forth between the MS Extension and CodeLLDB for debugging on Mac. But those kinds of changes require significant changes to the tutorial anyway and arguably require more substantial changes to the tutorials to update the UI instructions/screenshots and text description of what to customize in the generated default config.

There have also been several cases where we've needed to update the instructions or add pitfall warnings because of an unexpected change to UI behavior (e.g. run button changed, defaults and ordering in dropdown of configs changed (must scroll to bottom), not showing C++ options unless you click a .cpp file first, bug in CodeLLDB where it refuses to create a launch.json). These often include screenshot updates, which are kind of a pain, and some we have to revert once the UI is fixed.

IMO, a starter launch.json would actually simplify things quite a bit and avoid a number of these issues.

It's a fair point that students would need to remember how get a sample launch.json from the tutorial, but if we're working on the assumption that they can't remember there are instructions in the setup tutorial, I don't think it's any more likely they remember where to go in the UI, which configuration to select from the dropdown (including multiple similarly named options), and what they need to edit. But in any case - the right approach is to provide an essential reminder to setup your debugger at the top of each spec, which we currently do. A benefit of a sample launch.json with comments is also that the instructions could be simpler, since the comments provide guidance on creating your own configuration.

I'll also mention that many students currently take the approach of copying a previous project's launch.json anyway and use it as a template, which I think would work fine with the proposed approach.

I'm open to a hybrid approach, but I'd like to understand if I'm missing something in understanding the downsides of a sample launch.json you mentioned or if there is a pedagogical reason to prefer the UI or listing both options.

I'll also emphasize the main goal is not ease of copy/paste and debug without students going through configuration, but to set up a workflow where students have the information at hand in the launch.json to walk through editing the debugger config themselves and understand some more of what they are doing.

[jamesjuett]

i like it. it could also be interesting to have our own extension they could (optionally?) install which would allow them to choose the sample launch.jsons from a vscode modal

One thing I'm not sure about - if a sample configuration is provided through an extension, can it have comments attached? I'm wondering if an extension provides it as an object, rather than as text, in which case I don't think it could have comments.

[hardy-ethan]

That’s true… the API I’m familiar with uses an object… but I’m also pretty sure I’m remember some extensions having comments in their launch.jsons, so I can look into it.

…

On Sun, Jan 25, 2026 at 1:18 PM James Juett ***@***.***> wrote: *jamesjuett* left a comment (eecs280staff/tutorials#242) <#242 (comment)> i like it. it could also be interesting to have our own extension they could (optionally?) install which would allow them to choose the sample launch.jsons from a vscode modal One thing I'm not sure about - if a sample configuration is provided through an extension, can it have comments attached? I'm wondering if an extension provides it as an object, rather than as text, in which case I don't think it could have comments. — Reply to this email directly, view it on GitHub <#242 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AYQTEUM5UO2XQ762L7TQEFD4IUCILAVCNFSM6AAAAACSJ3ENVGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOOJXGA2DCOBSGA> . You are receiving this because you commented.Message ID: ***@***.***>