Setting Up Visual Studio Code

The recommended development environment for C++ programming in CPTR 124 and CPTR 318 this semester is Microsoft's Visual Studio Code (VSCode). VSCode is available for free for Microsoft Windows, Apple macOS, and Linux. Many other fine C++ integrated development environments exist for these platforms, but each has its own peculiar way of configuring projects for editing, building, debugging, and executing C++ programs. The process of setting up a C++ project involving external libraries and other dependencies sometimes can become complicated, and it can be tedious to diagnose and correct configuration errors in a multitude of different development systems. Students using VSCode can be assured that they will receive timely support when things are not working as they should.

VSCode is a programming editor coupled with a lightweight project management system. VSCode itself does include the tools necessary for compiling and debugging C++. You must install the C++ development tools (compiler, linker, and debugger) separately and then configure VSCode to use these tools. Fortunately, installing the C++ tools and VSCode and configuring everything to work for our purposes is relatively easy on Windows, macOS, and Linux.

This document explains how to install and configure the necessary C++ development tools and VSCode on Windows, macOS, and Linux.

• Apple macOS

  We will use the Clang C++ compiler adapted by Apple for macOS. This is part of the Xcode build tools. Xcode is a sophisticated integrated development environment (IDE) that supports C++ in addition to other programming languages. While you are welcome to install the complete XCode package, it is not necessary to do so for this course. Its installation involves a 4 GB download, and when fully installed it occupies a significant amount of disk space. You need install only the Xcode build tools. This is a much lighter weight package that integrates well with VSCode and provides all you need for C++ development for this course.

  
  

  ---

  Setting Up VSCode for C++ Development

  
  

  The following describes the necessary steps to install the VSCode enviroment for C++ development:

  1. Install the Xcode build tools.
     1. Hold down the [Cmd] key and press the spacebar to activate Spotlight. In the text field type the word Terminal and press [Enter]. This launches the Terminal application which provides a command-line interface (CLI) to the macOS operating system.
     2. In the Terminal window type the command gcc. If the Xcode build tools are not present on your system, you should receive the dialog shown here:
        

        Choose the Install, not the Get Xcode option. (If you choose the Get Xcode option, it will install the full Xcode package with its IDE. This would work also, but be prepared for a very long download time and extra disk usage.)

     3. Test your Xcode build tools installation: Launch a Terminal window (press Cmd + Spacebar) and type Terminal) and in the resulting Terminal window type the command clang++ -v. You should receive a result similar to the following:
        Apple LLVM version 9.0.0 (clang-900.0.38) Target: x86_64-apple-darwin17.2.0 Thread model: posix InstalledDir: /Library/Developer/CommandLineTools/usr/bin

        If instead you see receive some error mesage, you should ask for help to fix it before continuing with the steps that follow.

     This completes the installation of the Xcode build tools.

  2. Install VSCode.

     Download the VSCode installer (https://code.visualstudio.com/), and install it as you would any other Mac application. You should place it into your Applications folder, and you can copy it to the dock for ready access. Launch VSCode to ensure that it installed correctly. VSCode should display a welcome.

     We are not quite ready to start C++ programming, but we almost are there.

     This completes the installation of VSCode.

  3. Work with the sample C++ project.
     1. Download the archived sample C++ project, firstprogram-m.zip. Unzip the firstprogram-m.zip file. This creates a folder named FirstProgram, and in that folder you will find two files and and subfolder:
        • starter.cpp contains the source code for a very simple C++ program.
        • Makefile is a configuration file that specifies how to build the executable program from the source file.
        • .vscode is a folder that contains several files that allow VSCode to work properly with the MinGW C++ toolset.

        The file starter.cpp contains the following C++ program:

        #include <iostream> int main() { std::cout << "Our first C++ program\n"; }

     2. Launch VSCode. In the File menu, select "Open Folder ..." and navigate to the FirstProgram folder you just downloaded and unzipped. Direct VSCode to open this FirstProgram folder.

     3. From the VSCode Explorer pane on the left you can open the starter.cpp source file in a editor by double-clicking on it.

     4. You can build and run the program as follows:
        1. In VSCode, hold down the Shift and Cmd keys and press the C key. This brings up a Terminal (console) window.
        2. In the Terminal window type the command make run. This command will attempt to build the executable program from the source file, and, if it is successful, it will run the program.

        3. The program should print
           Our first C++ program

  In summary, the following three steps set up VSCode for C++ development under Apple macOS:

  1. Install the Xcode build tools
  2. Install VSCode
  3. Obtain a copy of an existing working C++ VSCode project folder

  You need do these three set-up steps only once.

  That is all there is to setting up VSCode for C++ development. Next we examine the typical workflow for creating a new C++ project.

  
  

  ---

  Using VSCode

  
  

  After you have created your first C++ project, creating another one is very simple. To see how simple it is, let's create a new VSCode C++ project and supply our own C++ program.

  You will follow steps similar to the following each time you want to write a C++ program using VSCode:

  1. Copy an existing VSCode C++ project folder and its contents to a new folder with a different name. Since we currently have only one VSCode C++ project (FirstProgram), use Finder to make a copy of the FirstProgram folder. For the sake of this exercise, name the new folder SecondProgram.

  2. Open the copied folder in VSCode. In this case open the SecondProgram folder in VSCode. At this point it is an exact copy of the original project, FirstProgram.

  3. Rename the C++ source file. Since this is a new program it is a good idea to give the source file a different name. Right click on starter.cpp in VSCode's Explorer pane. Select "Rename" to change the file's name to secondprogram.cpp.

     (This step technically is not necessary. Since each C++ source file will be in its own project folder, the source files could all have the same name. For example, program.cpp in the project folder Project1 could be an entirely different program than in the file program.cpp in the Project2 project folder.)

  4. Edit the Makefile. The Makefile is designed to work with the original project, and we need to make a small change to adapt it to this new project. The Makefile is expecting a C++ source file named starter.cpp, but we just renamed it to be secondprogram.cpp. Open Makefile in the VSCode editor. Change the first line from
     PROGNAME = starter.cpp
     to
     PROGNAME = secondprogram.cpp

     (Note that this step is unnecessary if you did not rename the source file in the previous step.)

  5. Edit the C++ source file. We want our new program in this SecondProgram to behave differently from the one in our FirstProgram project. Edit the secondprogram.cpp file so that it will display the following output when executed:
     *** This is our second C++ program! ***

  6. Build and run the program. Bring up a VSCode terminal window (press Shift + Cmd + C) and type make run. If the program does not build properly or does run as expected, return to the VSCode editor and make changes to the source code to fix build errors and/or correct the program's errant behavior. It may take many edit-build-run cycles to achieve the finished product that runs correctly.

  
  

  ---

  Summary

  
  

  In summary, the following three steps set up VSCode for C++ development under Microsoft Windows:

  1. Install the Xcode build tools
  2. Install VSCode
  3. Obtain a copy of an existing working C++ VSCode project folder

  You need do these three set-up steps only once.

  Once set up, the following three steps create a new C++ project in VSCode:

  1. Copy an existing working C++ VSCode project
  2. Rename the C++ source file (optional but advisable)
  3. Edit the first line of the Makefile to reflect the C++ source file's new name (not necessary if you skipped Step 2)
  4. Edit the C++ source file to implement the desired program

  You perform these four steps every time you wish to write a new program using VSCode.

  To build and run a C++ program under VSCode, bring up a VSCode console window (press Shift + Cmd + C) and type make run. Repeat the edit-build-run sequence until the program behaves correctly.