Development Environment | Chemeketa CS

Codespace Development Workflow

Mon, 01 Jan 0001 00:00:00 +0000

Follow these steps each time you work on a project in Codespaces. When working in a local environment you won't need to sync to GitHub (Step 3) unless you have started by cloning a project you cloned from GitHub and want to save your changes to that repository.

1. Edit and save

Chemeketa Worklog watches the project files and makes frequent Git commits as you save. These commits document how your program developed. They are stored in the working copy until you push them.

2. Build and run

Open Run and Debug in VS Code and choose the program or test configuration for your project. To build from the terminal instead, use the commands in Compile and Run.

3. Submit the assignment

Follow the submission instructions in the assignment. When a ZIP is required, open the Command Palette and run Zip Project, then upload the resulting project.zip file.

4. Sync to GitHub (Optional)

Making commits in your codespace (or having Chemeketa Worklog make them for you) does not automatically update the GitHub repository. You must sync or push your commits to GitHub to save your work there. Syncing your work back to GitHub is optional. But it is the only way to preserve your work after your codespace is deleted.

Open Source Control in VS Code.
Wait for Worklog to commit your most recent saved changes. If changes remain, commit them manually.
Select Sync Changes or Push.
Open the repository on GitHub and confirm that the latest files and commits appear.

5. Stop a Codespace

Closing the browser tab does not necessarily stop the Codespace. Open the Command Palette and run Codespaces: Stop Current Codespace, or manage it from github.com/codespaces.

Stopping preserves the Codespace. You can restart it later and continue working on the same project. This is like putting a computer to sleep.

Deleting a Codespace is equivalent to throwing away a computer. Only delete a Codespace once you are completely done with it. If you first sync your work to GitHub, you can delete the Codespace and later clone the repository to a new Codespace or to your local computer.

Projects that are stopped still consume storage space that counts against your quota on Github. Once you are done with a project (it is turned in and you have received a grade), you should delete the Codespace to free up storage space.

Develop in GitHub Codespaces

Mon, 01 Jan 0001 00:00:00 +0000

Use GitHub Codespaces for your first projects. It runs VS Code in a web browser and already has the C++ compiler, Git, and VS Code extensions used in Chemeketa CS courses. You can move the same projects to your own computer later.

Watch this overview to see a repository opened and used in Codespaces:

Set up GitHub

Create a GitHub account if you do not already have one. Use your Chemeketa email address and apply for GitHub Education benefits.

You can begin using Codespaces while GitHub reviews your education application. GitHub changes its included usage allowances periodically, so check the Codespaces billing documentation for current limits.

Create the repository

Create a GitHub repository from the Chemeketa project template required by your assignment.

Open the template required by your assignment.
Select Use this template, then Create a new repository.
Give the repository a descriptive name.
Set its visibility to Private unless your instructor says otherwise.
Select Create repository.

Do not choose Open in a codespace directly from the template repository. Create your own repository first so your work has a permanent home.

Create the Codespace

On your new repository's page, select Code.
Select the Codespaces tab.
Select Create codespace on main.
Wait while GitHub builds the development environment.

The VS Code editor opens in your browser when the Codespace is ready.

The repository on GitHub is the permanent home for the project. The Codespace is a temporary computer containing a working copy. You must sync your commits to GitHub before deleting a Codespace.

Development Setup Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

A command is not recognized

Run the command in a newly opened terminal. Install or repair the component if the test fails:

g++ --version
make --version
git --version

On native Windows, test mingw32-make --version instead of make --version. On macOS, test g++-15 --version.

If a command works in one terminal but not VS Code, completely quit and reopen VS Code so it receives the updated Path.

Include errors or wrong compiler

If the project builds but VS Code underlines valid #include statements:

Open the Command Palette.
Run C/C++: Select IntelliSense Configuration.
Select the compiler installed for the current environment.

Expected locations include:

Windows: C:\mingw64\bin\g++.exe
Apple Silicon macOS: /opt/homebrew/bin/g++-15
Linux or WSL: the result of which g++

The compiler can have a different path on Intel Macs or Linux distributions. Select the path reported by which g++-15 or which g++ rather than copying another platform's path.

VS Code runs in the wrong environment

On Windows, check the lower-left corner of VS Code:

A normal Windows window uses the native MinGW compiler.
A window labeled WSL: Ubuntu uses tools installed inside WSL.
A Codespaces window uses the tools in the cloud development container.

Open a terminal in that window and run g++ --version to test the environment VS Code is actually using.

The Run and Debug choices are missing

Open the entire project folder rather than an individual source file. Confirm that the folder contains .vscode, Makefile, and the program or test source files.

Worklog is not making commits

Confirm that:

the Chemeketa Worklog extension is installed in the current environment;
you opened the entire project folder;
the project came from a prepared Chemeketa template; and
git config --global --list shows your name and email.

Worklog does not push automatically. Use Sync Changes after it commits.

A Codespace says you are offline

Browser privacy settings or content-blocking extensions can prevent Codespaces from loading. Temporarily disable blocking for GitHub, allow the site's required cookies, or try a supported browser without privacy extensions.

Git reports a conflict

Stop editing and do not delete either copy. A conflict means two environments changed the same history. Preserve both versions and ask your instructor or tutor for help if you are unsure which changes to keep.

Before changing environments, complete the environment-switching checklist to prevent conflicts.

Git and Chemeketa Worklog

Mon, 01 Jan 0001 00:00:00 +0000

Git records changes to a project as commits. Chemeketa Worklog creates frequent commits while you work in a Chemeketa project template. Keep this history: it documents how you developed the program and is part of programming assignment requirements.

This demonstration uses Worklog's former name, GitDoc. The workflow remains the same:

Commits vs Local Saves

VSCode will save local edits to files. These saves are not recorded in the git history. A commit is a snapshot of the changes to the project that is recorded in the git history. When you save a project to turn in, your local VS code edit history is NOT included. Only the git commits will be available to your instructor.

Troubleshooting the Worklog While Developing Locally

If you are working locally (using VS code on your computer and not in a codespace) and you do not see commits being created, check that the Chemeketa Worklog extension is installed and enabled. If it is installed, verify that you have configured your Git identity. See the Git Identity Setup instructions.

Git Identity Setup

Mon, 01 Jan 0001 00:00:00 +0000

After installing Git, you must configure your identity with your name and Chemeketa email address. This is required for the Chemeketa Worklog extension to create commits while you work in a project template.

To do so, open a terminal and run these commands. Replace the example values with your own name and Chemeketa email address:

git config --global user.name "Your Name"
git config --global user.email "yourname@my.chemeketa.edu"

Verify the settings:

git config --global --list

Configure Git separately in native Windows and WSL if you use both environments.

Install Windows Subsystem for Linux

Mon, 01 Jan 0001 00:00:00 +0000

Install Windows Subsystem for Linux (WSL) after completing the native Windows setup. WSL lets you run Linux tools, including Valgrind, on your Windows computer.

WSL has its own compiler, Git configuration, and VS Code extensions. Your course projects can remain in the Windows filesystem and be accessed from both Windows and WSL.

You must have an up-to-date copy of Windows 10 or Windows 11.

Enable Windows Subsystem for Linux

Open the Start menu and search for Turn Windows features on or off.
Open it and select Windows Subsystem for Linux and Virtual Machine Platform.
Select OK and allow Windows to install the feature.
Restart your computer when prompted.

Install Ubuntu

Open the Microsoft Store.
Search for Ubuntu.
Select the unversioned Ubuntu app and install it. If an unversioned app is not available, install the app with the highest version number.
Open Ubuntu from the Start menu after installation finishes.

The first launch takes a few minutes to finish setting up Ubuntu. It then asks you to create a Linux username and password. Choose a password you can remember and keep it private. Linux does not display characters while you type a password; that is normal.

Install Linux development tools

In the Ubuntu terminal, update the available package information:

sudo apt update

Ubuntu checks its package sources and displays the available updates:

Enter the Linux password you created when prompted. Then install the compiler, debugger, Git, and Valgrind:

sudo apt install build-essential gdb git valgrind

Then test the tools:

g++ --version
make --version
gdb --version
git --version
valgrind --version

The project Makefiles use the default g++ command. The template's included IntelliSense configuration may name a versioned compiler such as /usr/bin/g++-15. If VS Code shows include errors, select the compiler you installed as described in Troubleshooting.

Configure Git inside WSL

Git's Windows configuration is not automatically reused inside WSL. Follow Configure your identity from an Ubuntu terminal.

Navigating in the Virtual Machine

Windows drives appear inside WSL under /mnt. For example, C:\CSProjects is /mnt/c/CSProjects in Ubuntu.

This video demonstrates how to navigate in WSL and access files stored in Windows:

This alternate walkthrough demonstrates the same Windows-file navigation in another version of Ubuntu:

After the commands work, connect VS Code to WSL.

Linux Local Setup

Mon, 01 Jan 0001 00:00:00 +0000

On Ubuntu or another distribution that uses apt, install the required tools with:

sudo apt update
sudo apt install build-essential gdb git

Test the tools:

g++ --version
make --version
gdb --version
git --version

Chemeketa projects use C++20. Package names and compiler versions vary among Linux distributions. If your compiler cannot build the project, install a newer GCC package using your distribution's instructions.

Install VS Code and extensions

Install Visual Studio Code using the package for your distribution. Open the Extensions view with Ctrl+Shift+X and install:

ms-vscode.cpptools
cschlosser.doxdocgen
usernamehw.errorlens
ascholer.chemeketa-gitdoc
davidkaiser.kaiser-project-zip

Configure Git

The git package was installed with the development tools above. Complete the Git identity setup before starting a local project.

Verify the complete setup

Create or download a fresh Basic Project, open its entire folder in VS Code, and run the Run Program configuration.

The template's IntelliSense configuration currently names /usr/bin/g++-15. If your compiler has a different path, use C/C++: Select IntelliSense Configuration in the Command Palette and select the g++ you installed.

macOS Local Setup

Mon, 01 Jan 0001 00:00:00 +0000

Install Homebrew GCC 15 for Chemeketa projects. The project settings select this compiler instead of Apple's Clang compiler.

Install the command-line tools

Open Terminal and run:

xcode-select --install

This installs Make, Git, and other command-line tools required by Homebrew and VS Code.

Install Homebrew and GCC

Follow the installation command at brew.sh.
Follow every shell-configuration instruction Homebrew prints after installation.
Close and reopen Terminal.
Install the GCC version used by the templates:

brew install gcc@15

Test the compiler and other command-line tools:

g++-15 --version
make --version
git --version

This demonstration shows the Xcode tools, Homebrew, and GCC installation process. Follow the current commands above if the Homebrew output or GCC version shown in the video differs:

Install VS Code and extensions

Install Visual Studio Code. Open the Extensions view with Cmd+Shift+X and install:

ms-vscode.cpptools
cschlosser.doxdocgen
usernamehw.errorlens
ascholer.chemeketa-gitdoc
davidkaiser.kaiser-project-zip
vadimcn.vscode-lldb

Configure Git

Git was installed with the Xcode command-line tools. Complete the Git identity setup before starting a local project.

Verify the complete setup

Create or download a fresh Basic Project, open its entire folder in VS Code, and run the Run Program (Mac) configuration.

The templates expect Homebrew at /opt/homebrew, the normal location on Apple Silicon Macs. On an Intel Mac, or if which g++-15 reports another location, use C/C++: Select IntelliSense Configuration in the Command Palette and select the installed g++-15. See Troubleshooting if the project builds but VS Code shows include errors.

Project Templates

Mon, 01 Jan 0001 00:00:00 +0000

Start each project from the template named in the assignment. The template includes the build, debugging, formatting, and Worklog settings used by Chemeketa CS courses.

Choose a template

Basic Project contains a main.cpp program.
Unit Test Project contains a doctest test program.
Combo Project contains both a main program and a doctest test program.

Use the Basic Project when your instructor does not specify a template.

Create a GitHub repository

This is the recommended method for Codespaces and local development.

Open the appropriate template repository.
Select Use this template, then Create a new repository.
Name the repository and make it private.
Create it, then either open a Codespace or clone it to your computer.

Create a project without GitHub

Use this method only when you need a project that will remain completely local.

Open the appropriate template repository.
Open the Releases page and select the release marked Latest.
Download the prepared project ZIP attached to that release.
Extract it and rename the project folder.

Do not use GitHub's general Download ZIP button. That archive does not include the prepared Git history needed by Chemeketa Worklog.

Avoid spaces in project names and do not place active projects in OneDrive, iCloud, or another synchronized folder.

Use the included project settings

Keep the template's Makefile and .vscode folder with your project. Together, they:

build C++20 projects through a Makefile;
provide VS Code build and debugging commands;
use MinGW GCC on Windows, Homebrew GCC on macOS, and GCC on Linux;
enable Chemeketa Worklog to make frequent local commits; and
provide a Codespaces development container.

Worklog creates commits but does not push them to GitHub. Follow the steps in Git and Worklog to save those commits to GitHub.

Set Up Your Computer

Mon, 01 Jan 0001 00:00:00 +0000

Continue using Codespaces until your course asks you to work locally. Then install the tools for your operating system:

You then will need to configure Git with your name and Chemeketa email address. See Git and Worklog for instructions.

Git setup

Install all four components before opening an assignment on your computer:

A C++ compiler and Make
Visual Studio Code
The required VS Code extensions
Git, including your name and email configuration

This demonstration shows how to install VS Code and the course extensions. Use your operating system's setup steps above for the current extension list:

Use VS Code with WSL

Mon, 01 Jan 0001 00:00:00 +0000

Use the copy of VS Code installed in Windows; do not install a second copy inside WSL. Install this extension in the Windows copy of VS Code:

ms-vscode-remote.remote-wsl

Keep projects in the Windows filesystem

Use the same Windows project folder you created for local development. Do not put projects in OneDrive, Dropbox, or another synchronized folder, and do not create a second copy in the WSL home folder.

WSL mounts the Windows C: drive at /mnt/c. For example, the Windows project C:\CSProjects\MyProject is available in WSL at:

/mnt/c/CSProjects/MyProject

Open the project in WSL

Open Ubuntu and change to the Windows project folder:

cd /mnt/c/CSProjects/MyProject

Replace the example path with the location of your project. Put quotation marks around the path if any folder name contains spaces. Then run:

code .

VS Code opens a new window connected to WSL. Look for WSL: Ubuntu in the lower-left corner. Terminals, builds, and debugging in this window now run inside Linux.

VS Code extensions that execute tools must also be installed in WSL. When prompted, install the recommended C/C++, Error Lens, Doxygen, Worklog, and Project Zip extensions in the WSL environment.

Switch between Windows and WSL

Close the current VS Code window before opening the project in the other environment. Windows and Linux programs are not interchangeable, even when both are named program.exe. Clean the old build before rebuilding:

After moving from Windows to WSL, run make clean, then build in WSL.
After moving from WSL to Windows, run mingw32-make clean, then build in Windows.

Do not edit the project from Windows and WSL at the same time. Before moving between your computer and Codespaces, use the environment-switching checklist.

Windows Local Setup

Mon, 01 Jan 0001 00:00:00 +0000

Install the native Windows tools first. You will use them for local projects before you add WSL.

Install the compiler and Make

Download the GCC 15 MinGW archive. (We are installing the 64-bit version of GCC 15.2.0 with POSIX threading, SEH, and the UCRT runtime.)

Windows 11 can extract .7z archives. On older systems, install 7-Zip first.

Extract the archive to C:\.
Confirm that C:\mingw64\bin contains g++.exe and mingw32-make.exe.
Open the Start menu and search for Edit the system environment variables.
Open the result, select the Advanced tab, and select Environment Variables.
Select Path under User variables, then select Edit.
Select New, enter C:\mingw64\bin, and select OK until all the settings windows close.
Close and reopen any terminal windows.

Open PowerShell and test both tools:

g++ --version
mingw32-make --version

This demonstration shows how to extract MinGW and add its bin folder to the Windows Path. Follow the folder names and compiler version in the written steps above if they differ from the video:

Install VS Code and extensions

Install Visual Studio Code. Then open the Extensions view with Ctrl+Shift+X and install:

ms-vscode.cpptools
cschlosser.doxdocgen
usernamehw.errorlens
ascholer.chemeketa-gitdoc
davidkaiser.kaiser-project-zip

Install and configure Git

Install the 64-bit version of Git for Windows. Choose Visual Studio Code when the installer asks for a default text editor.

Open a new PowerShell window and verify the installation:

git --version

Then configure your Git identity.

Verify the complete setup

Create or download a fresh Basic Project and open its entire folder in VS Code.

Open Run and Debug.
Select Run Program.
Start the program.

The template should run mingw32-make, create program.exe, and open the program in the debugger. If it does not, see Troubleshooting.

Work on a Project Locally

Mon, 01 Jan 0001 00:00:00 +0000

Complete the local setup for your operating system before following this page.

Choose a project location

Make a folder for your CS projects. Avoid spaces in folder names and avoid OneDrive, iCloud, Dropbox, or other synchronized folders. Synchronization programs can interfere with Git and build tools.

Set up the Code

Use one of these methods to get the project code on your computer.

A. Clone code from GitHub

For projects that began in Codespaces. Or if you want to be able to synchronize with a GitHub repository.

Make a Github repository from the Chemeketa project template required by your assignment. (Or find your existing repository on GitHub.)
In VSCode, open the Command Palette with Ctrl+Shift+P or Cmd+Shift+P.
Run Git: Clone.
Select Clone from GitHub and authorize VS Code if prompted.
Select the project repository.
Choose your CS projects folder on your computer as the destination.
Open the cloned project when VS Code prompts you.

B. Start a completely local project

If you just want to work on a project locally without using GitHub, download the prepared release described under Create a project without GitHub.

Open the whole project folder in VS Code (File > Open Folder).

Do not open single files in VS Code. Opening a folder is required for the build and debugger to work correctly (they need the Makefile and .vscode folder).

Build and run

Open Run and Debug, select the configuration for your platform and target, and start the program. See Compile and Run to build from the terminal.

Switch between development environments

A GitHub repository lets you work on the same project in Codespaces, directly on your computer, or in WSL. GitHub is the handoff point between those working copies.

Before leaving the current environment

Save every file.
Confirm that Worklog committed the latest changes.
Open Source Control and select Sync Changes or Push.
Open the repository on GitHub and confirm the latest commit appears.
Close the project or stop the Codespace.

When entering the other environment

If this is the first time using the project there, clone the repository.
If it has already been cloned, pull or sync before editing anything.
Resolve any reported conflict before continuing to work.

Do not edit the same project in two environments at the same time. Worklog can create commits in both copies, making conflicts more likely.

Downloading a ZIP is appropriate for submitting an assignment or making a snapshot. It is not the normal way to move an active project between development environments because the ZIP is disconnected from its GitHub repository.