@@ -4,7 +4,7 @@ A VSCode C++ development environment for Linux, richly populated with
44quality-oriented tools.
55
66
7- ## Motivation
7+ ## Introduction
88
99VSCode users know that the application is highly expandable and flexible. They
1010also know that discovering all the tools and techniques to configure VSCode is
@@ -23,43 +23,16 @@ in pieces from this project. For example, the custom build tasks for mutation
2323testing and code sanitizers are powered by scripts easily transferred to other
2424C++ development environments.
2525
26-
27- ## Overview
28-
29- The developmment enviroonment is provided via two directories:
30-
31- - .devcontainer
32-
33- A VSCode containerized development installlation based on Ubuntu.
34- The developer works in the environment under their own account.
35-
36- - .vscode
37-
38- VSCode settings, CMake variants, and custom tasks for C++ development.
39-
40- The directories complement each other. The .vscode files provide settings
41- for the .devcontainer tools.
42-
43- The resulting VSCode session has many integrated tools available from the
44- IDE's GUI:
45-
46- - CMake tools with configuration pre-sets and build-target selection
47- - Auto-format on save (C++ and CMake files)
48- - Inline linter hints and git blame
49- - Test explorer and code coverage annotation
50- - Mutation testing
51- - Valgrind reports and code sanitizer reports
52-
53- Read on below for detailed instructions in using the environment.
26+ Try the environment by following the step-by-step instructions below.
5427
5528![ VSCode screenshot showing the C++ developer environment] ( docs/VSCode.jpeg )
5629
5730
5831## Use The Environment
5932
60- These instructions assume you are working on Linux with VSCode, git, and
61- docker installed. They also assume you have a GitHub account with a registered
62- SSH key so you can clone this repository and open it in VSCode.
33+ These instructions assume you are working on Linux with VSCode, git, docker.io
34+ and docker-compose installed. They also assume you have a GitHub account with a
35+ registered SSH key so you can clone this repository and open it in VSCode.
6336
6437```
6538git clone git@github.com:ian-fisher-developer/vscode-cpp-dev-tools.git
@@ -69,10 +42,22 @@ cd vscode-cpp-dev-tools
6942code .
7043```
7144
72- VSCode recognizes the .devcontainer directory and offers to re-open the project
73- in the container. Or, click on ` Open a Remote Window ` (at the very left of the
74- status bar) and choose ` Reopen in Container ` . Note that, for the first time
75- only, it may take quite a while for VSCode to create the docker images.
45+ ### Reopen In Container
46+
47+ The environment uses VSCode's DevContainer feature. Choose ` Command Palette `
48+ from the ` View ` menu and search for the ` Reopen in Container ` command. Note
49+ that, for the first time only, it may take a while for VSCode to build its
50+ Docker image. Check that you have correctly entered the DevContainer
51+ environment:
52+
53+ - The Remote Window indicator in the bottom left should be lit up in blue and
54+ say, "Dev Container: STATS"
55+ - The vertical list of extensions at the left should contain extra items
56+ specified by the environment, such as GitLens and CMake Tools
57+ - The status bar across the bottom should show several extension controls,
58+ especially for CMake.
59+
60+ ### Get To Work
7661
7762When the DevContainer session is ready, follow these steps to exercise the
7863environment's C++ development features.
@@ -85,14 +70,20 @@ environment's C++ development features.
8570
8671- Build all and use the test explorer
8772
88- Choose the ` all ` build target (in the status bar selector) and build it to
89- create the library, the unit-test program, and the example programs.
90- Open the test explorer side pane to view and run the unit tests.
73+ Choose the ` all ` build target (in the status bar selector).
74+ Be careful of a trap...the status bar may have both ` default build target `
75+ and ` default launch target ` selectors. They are easy to confuse. Here, we
76+ want to set the build target.
9177
92- The test explorer has controls to run all the tests or a single test. Or, set
93- ` Start Continuous Run ` (at the top of the test explorer) to automatically run
94- the tests when they are rebuilt. Note that in the screen-shot above, the test
95- explorer is moved to VSCode's secondary side bar, on the right.
78+ Push the build button to create the library, the unit-test program, and the
79+ example programs. Open the test explorer side pane to view and run the unit
80+ tests.
81+
82+ The test explorer has controls to run all the tests, subgroups of tests, or
83+ individual tests. It can automatically re-run all/subgroups/individual tests
84+ when the test program is rebuilt via its Continuous Run feature. Note that
85+ in the screen-shot above, the test explorer is moved to VSCode's secondary
86+ side bar, on the right.
9687
9788- Try the code editor
9889
@@ -107,40 +98,48 @@ environment's C++ development features.
10798
10899 The clangd extension from the LLVM project provides a full C++ code model,
109100 enabling many code editing helpers such as code completion options. Note
110- that VSCode tends to install GitHub CoPilot by default. The AI's slop
111- suggestions get in the way. Turn off GitHub CoPilot to return to accurate
112- information from the code model.
101+ that VSCode tends to install GitHub Copilot by default. The AI's
102+ non-deterministic inline suggestions can get in the way. Copilot's menu (in
103+ the status bar, bottom-right) has toggles to turn them off so you can return
104+ to accurate information from the code model.
113105
114106 Ctrl-S auto-formats C++ and CMake files according to the project standards.
115107
116108- Examine code coverage
117109
118110 Switch from ` all ` to the ` statistics_coverage_report ` target and build it.
119111
120- Turn on the Coverage Gutters extension's ` Watch ` function (in the status bar)
112+ Select Coverage Gutters: Preview Coverage Report from the editor's
113+ right-click context menu to browse the [ HTML report] [ 1 ] .
114+
115+ Select Coverage Gutters: Watch from the editor's right-click context menu
121116 to add coverage annotation to the C++ code editor in the form of colored bars
122117 by the line numbers.
123118
124- Select ` Coverage Gutters: Preview Coverage Report ` from the editor's context
125- menu to browse the [ HTML report] [ 1 ] .
126-
127119- Test the tests
128120
129121 A custom build task provides [ mutation testing] [ 2 ] for the project, helping
130122 find gaps in the tests, even when code coverage is all green.
131- Select ` Run Build Task ` from VSCode's ` Terminal ` menu to create either a
132- [ full mutation testing report] [ 3 ] , or an analysis for only the branch diffs.
123+
124+ Select ` Run Build Task ` from VSCode's ` Terminal ` menu to create a
125+ [ full mutation testing report] [ 3 ] by applying no diff filter.
133126
134127- Look for memory leaks
135128
136129 A custom build task runs the unit-test program under valgrind and logs the
137130 results to a [ valgrind report] [ 4 ] .
138131
139- - Use the compiler's code sanitizers
132+ Select ` Run Build Task ` from VSCode's ` Terminal ` menu to execute the task.
133+
134+ - Use the code sanitizers
135+
136+ A custom build task creates a sanitizer testing report using the compiler's
137+ sanitize flag. It has options for the address sanitizer and the
138+ undefined-behavior sanitizer.
140139
141- Two custom build tasks generate reports from the compiler's
142- [ address sanitizer] [ 5 ] and [ undefined-behavior sanitizer] [ 6 ] .
143- Each task builds the project's code with the corresponding sanitizer flag,
140+ Select ` Run Build Task ` from VSCode's ` Terminal ` menu to execute the task.
141+ Create an [ address sanitizer] [ 5 ] report and an [ undefined-behavior sanitizer] [ 6 ]
142+ report. It builds the project's code with the corresponding sanitizer flag,
144143 then runs the unit-test program. The instrumented code writes to a log file
145144 if it finds any issues.
146145
0 commit comments