This post builds on using multi-stage containers for C++ development. That post showed how to use a single Dockerfile to describe a build stage and a deployment stage resulting in a container optimized for deployment. It did not show you how to use a containers with your development environment. Here we will show how to use those containers with VS Code. The source for this article is the same as that of the previous article: the findfaces GitHub repo.
Creating a container for use with VS Code
VS Code has the capability to target a remote system for debugging. Couple that with a custom build task for compiling in your container and you will have an interactive containerized C++ development environment.
We’ll need to change our container definition a bit to enable using it with VS Code. These instructions are based on some base container definitions that David Ducatel has provided in this GitHub repo. What we’re doing here is taking those techniques and applying them to our own container definition. Let’s look at another Dockerfile for use with VS Code, Dockerfile.vs.
FROM findfaces/build
LABEL description="Container for use with VS"
RUN apk update && apk add --no-cache
gdb openssh rsync zip
RUN echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config &&
echo 'PermitEmptyPasswords yes' >> /etc/ssh/sshd_config &&
echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config &&
ssh-keygen -A
EXPOSE 22
CMD ["/usr/sbin/sshd", "-D"]
In the FROM statement we’re basing this definition on the local image we created earlier in our multi-stage build. That container already has all our basic development prerequisites, but for VS Code usage we need a few more things enumerated above. Notably, we need SSH for communication with VS Code for debugging which is configured in the RUN command. As we are enabling root login, this container definition is not appropriate for anything other than local development. The entry point for this container is SSH specified in the CMD line. Building this container is simple.
docker build -t findfaces/vs -f Dockerfile.vs .
We need to specify a bit more to run a container based on this image so VS Code can debug processes in it.
docker run -d -p 12345:22 --security-opt seccomp:unconfined -v c:/source/repos/findfaces/src:/source --name findfacesvscode findfaces/vs
One of the new parameters we haven’t covered before is –security-opt. As debugging requires running privileged operations, we’re running the container in unconfined mode. The other new parameter we’re using is -v, which creates a bind mount that maps our local file system into the container. This is so that when we edit files on our host those changes are available in the container without having to rebuild the image or copy them into the running container. If you look at Docker’s documentation, you’ll find that volumes are usually preferred over bind mounts today. However, sharing source code with a container is considered a good use of a bind mount. Note that our build container copied our src directory to /src. Therefore in this container definition we will use interactively we are mapping our local src directory to /source so it doesn’t conflict with what is already present in the build container.
Building C++ in a container with VS Code
First, let’s configure our build task. This task has already been created in tasks.json under the .vscode folder in the repo we’re using with this post. To configure it in a new project, press Ctrl+Shift+B and follow the prompts until you get to “other”. Our configured build task appears as follows.
{
"version": "2.0.0",
"tasks": [
{
"label": "build",
"type": "shell",
"command": "ssh",
"args": [
"root@localhost",
"-p",
"34568",
"/source/build.sh"
],
"problemMatcher": [
"$gcc"
]
}
]
}
The “label” value tells VS Code this is our build task and the type that we’re running a command in the shell. The command here is ssh (which is available on Windows 10). The arguments are passing the parameters to ssh to login to the container with the correct port and run a script. The content of that script reads as follows.
cd /source/output && cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=/tmp/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux-musl && make
You can see that this script just invokes CMake in our output directory, then builds our project. The trick is that we are invoking this via ssh in our container. After this is set up, you can run a build at any time from within VS Code, as long as your container is running.
Debugging C++ in a container with VS Code
To bring up the Debug view click the Debug icon in the Activity Bar. Tasks.json has already been created in the .vscode folder of the repo for this post. To create one in a new project, select the configure icon and follow the prompts to choose any configuration. The configuration we need is not one of the default options, so once you have your tasks.json select Add Configuration and choose C/C++: (gdb) Pipe Launch. The Pipe Launch configuration starts a tunnel, usually SSH, to connect to a remote machine and pipe debug commands through.
You’ll want to modify the following options in the generated Pipe Launch configuration.
"program": "/source/output/findfaces",
"args": [],
"stopAtEntry": true,
"cwd": "/source/out",
The above parameters in the configuration specify the program to launch on the remote system, any arguments, whether to stop at entry, and what the current working directory on the remote is. The next block shows how to start the pipe.
"pipeTransport": {
"debuggerPath": "/usr/bin/gdb",
"pipeProgram": "C:/Windows/system32/OpenSSH/ssh.exe",
"pipeArgs": [
"root@localhost",
"-p",
"34568"
],
"pipeCwd": ""
},
You’ll note here that “pipeProgram” is not just “ssh”, the full path to the executable is required. The path in the example above is the full path to ssh on Windows, it will be different on other systems. The pipe arguments are just the parameters to pass to ssh to start the remote connection. The debugger path option is the default and is correct for this example.
We need to add one new parameter at the end of the configuration.
"sourceFileMap": {
"/source": "c:/source/repos/findfaces/src"
}
This option tells the debugger to map /source on the remote to our local path so that our sources our properly found.
Hit F5 to start debugging in the container. The provided launch.json is configured to break on entry so you can immediately see it is working.
IntelliSense for C++ with a container
There are a couple of ways you can setup IntelliSense for use with your C++ code intended for use in a container. Throughout this series of posts we have been using vcpkg to get our libraries. If you use vcpkg on your host system, and have acquired the same libraries using it, then your IntelliSense should work for your libraries.
System headers are another thing. If you are working on Mac or Linux perhaps they are close enough that you are not concerned with configuring this. If you are on Windows, or you want your IntelliSense to exactly match your target system, you will need to get your headers onto your local machine. While your container is running, you can use scp to accomplish this (which is available on Windows 10). Create a directory where you want to save your headers, navigate there in your shell, and run the following command.
scp -r -P 12345 root@localhost:/usr/include .
To get the remote vcpkg headers you can similarly do the following.
scp -r -P 12345 root@localhost:/tmp/vcpkg/installed/x64-linux-musl/include .
As an alternative to scp, you can also use Docker directly to get your headers. For this command the container need not be running.
docker cp -L findfacesvs:/usr/include .
Now you can configure your C++ IntelliSense to use those locations.
Keeping up with your containers
When you are done with your development simply stop the container.
docker stop findfacesvscode
The next time you need it spin it back up.
docker start findfacesvscode
And of course, you need to rerun your multi-stage build to populate your runtime container with your changes.
docker build -t findfaces/run .
Remember that in this example we have our output configured under our source directory on the host. That directory will be copied into the build container if you don’t delete it (which you don’t want), so delete the output directory contents before rebuilding your containers (or adjust your scripts to avoid this issue).
What next
We plan to continue our exploration of containers in future posts. Looking forward, we will introduce a helper container that provides a proxy for our service and to deploy our containers to Azure. We will also revisit this application using Windows containers in the future.
Give us feedback
We’d love to hear from you about what you’d like to see covered in the future about containers. We’re excited to see more people in the C++ community start producing their own content about using C++ with containers. Despite the huge potential for C++ in the cloud with containers, there is very little material out there today.
If you could spare a few minutes to take our C++ cloud and container development survey, it will help us focus on topics that are important to you on the blog and in the form of product improvements.
As always, we welcome your feedback. We can be reached via the comments below or via email (visualcpp@microsoft.com). If you encounter other problems or have a suggestion for Visual Studio please let us know through Help > Send Feedback > Report A Problem / Provide a Suggestion in the product, or via Developer Community. You can also find us on Twitter (@VisualC).