Windows Terminal<\/a> from the Microsoft Store. If you’re using Windows Terminal it will default to PowerShell, so click the “v” at the top and select “Ubuntu” (or whichever distro you chose when installing).<\/p>\n\n\n\nCreate a directory for your project in WSL and launch Visual Studio Code. This will launch VS Code in a split client\/server mode: the front-end user interface running in Windows, but the back-end running in WSL. A little later we’ll switch to running the back end in a Docker container.<\/p>\n\n\n\n
I’ll call my project directory “clang-example” for this example. You can call it whatever you like.<\/p>\n\n\n\n
cd ~\nmkdir clang-example\ncd clang-example\ncode .<\/code><\/pre>\n\n\n\nCreate Your Dockerfile<\/h2>\n\n\n\n
In VS Code, create a new file and name it Dockerfile<\/code> (exactly like that: uppercase D, no file extension). The contents will be:<\/p>\n\n\n\nFROM alpine:latest\nRUN apk --no-cache add clang llvm llvm-dev llvm-static llvm-gtest lldb lldb-dev g++ git gcompat cmake make py3-lldb<\/code><\/pre>\n\n\n\nThe FROM<\/code> line tells it to start with a base image of Alpine Linux. Alpine is a minimalistic distribution that will keep your Docker container file sizes small, and is used as a base for many Docker projects.<\/p>\n\n\n\nThe next line tells it to run apk<\/code>, Alpine’s package manager (equivalent to yum<\/code>, apt<\/code>, etc.), and install several pages. The --no-cache<\/code> option prevents it from needlessly caching files and bloating the size of your container. I’ll explain why each package is required.<\/p>\n\n\n\n\nclang<\/code>: This should be obvious, it’s the C\/C++ compler.<\/li>\n\n\n\nllvm<\/code>: This is the “back end” for the Clang compiler.<\/li>\n\n\n\nllvm-dev<\/code>: This provides LLVMConfig.cmake<\/code> so you can compile tools that integrate directly with LLVM, ie. LLDB-MI.<\/li>\n\n\n\nllvm-static<\/code>: This provides libLLVMDemangle.a<\/code>, needed for compiling LLDB-MI.<\/li>\n\n\n\nllvm-gtest<\/code>: This provides libLLVMTestingAnnotations.a<\/code>, needed for compiling LLDB-MI.<\/li>\n\n\n\nlldb<\/code>: The debugger for LLVM.<\/li>\n\n\n\nlldb-dev<\/code>: This provides lib_lldb<\/code>, needed for compiling LLDB-MI.<\/li>\n\n\n\ng++<\/code>: Clang doesn’t actually provide standard headers such as iostream<\/code>, so you need to install g++<\/code> for these.<\/li>\n\n\n\ngit<\/code>: This provides an easy way to get LLDB-MI, and it will integrate with VS Code in your project.<\/li>\n\n\n\ngcompat<\/code>: The VS Code cpptools<\/code> extension needs this in order to run – it expects GCC’s standard library to be installed, but Alpine Linux uses the alternative Musl standard library. This package provides a compatibility shim between the two.<\/li>\n\n\n\ncmake<\/code>: This is needed for compiling LLDB-MI, and probably your own project as well.<\/li>\n\n\n\nmake<\/code>: CMake will produce a Makefile<\/code>, which make<\/code> will then use to build the project.<\/li>\n\n\n\npy3-lldb<\/code>: This is a Python module used in debugging. Without it, you will get the error “No module named ‘lldb'”<\/li>\n<\/ul>\n\n\n\nPhew, that was a lot of packages, and it took a few hours for me to discover all these dependencies…<\/p>\n\n\n\n
Build & Switch To the Container<\/h2>\n\n\n\n
In VS Code, press Ctrl + Shift + P<\/code> to bring up the task list, and select “Remote Containers: Open Folder in Container...<\/code>“, and press “OK<\/code>“, then select “From Dockerfile<\/code>“. This will start building your Docker container, which will take a few minutes. Click “(show log)<\/code>” on the popup to keep an eye on the progress. Between g++, llvm, and Clang, you can expect it to download a few hundred megabytes. Docker caches the result of each command in the Dockerfile, so if you want to add more packages later you can add a separate RUN<\/code> command instead of just appending it to the existing one, and then it won’t have to redownload all the compiler packages.<\/p>\n\n\n\nIf you make any changes to the Dockerfile later then you can rebuild your container then you can select “Remote Containers: Rebuild Container”.<\/p>\n\n\n\n
Install Extensions in the Container<\/h2>\n\n\n\n
Because the VS Code client is now running inside your Docker container, it needs to have extensions installed there as well. During the setup process it created a file .devcontainer\/devcontainer.json<\/code> – load that up and edit the extensions<\/code> key to add Microsoft C\/C++ Tools, CMake Tools, and any others you require:<\/p>\n\n\n\n{\n\t"extensions": [\n\t\t"ms-vscode.cpptools",\n\t\t"ms-vscode.cmake-tools"\n\t],\n}<\/code><\/pre>\n\n\n\nAfter editing the file, select “Remote Containers: Rebuild Container” from the task list.<\/p>\n\n\n\n
Building LLDB-MI<\/h2>\n\n\n\n
LLDB-MI provides the interface between VS Code and the LLDB debugger, allowing you to step through code, set breakpoints, and so on. This used to be part of LLDB but was spun off into a separate project. There is currently no package available for it in Alpine, so you have to build it yourself. Open a terminal window in VS Code (Ctrl + ‘). Make sure you are in your project directory, for example \/workspaces\/clang-example\/<\/code>, and execute the following commands to download and build the tool:<\/p>\n\n\n\ngit clone https:\/\/github.com\/lldb-tools\/lldb-mi.git\ncd lldb-mi\ncmake .\ncmake --build .<\/code><\/pre>\n\n\n\nConfiguring the Debugger with launch.json<\/h2>\n\n\n\n
VS Code has to be told which debugger to use, and this is done in the launch.json<\/code> configuration file. Click on the debugging panel in VS Code (the play button with a bug on the left), and select “create a launch.json file”. Select “C++ (GDB\/LLDB)” (if you do not see this, make sure the C++ extension is installed properly). You may get an error saying it is unable to open the file, in which case just try again and it should work. You’ll now need to make some edits to the launch.json<\/code> file:<\/p>\n\n\n\n{\n \/\/ Use IntelliSense to learn about possible attributes.\n \/\/ Hover to view descriptions of existing attributes.\n \/\/ For more information, visit: https:\/\/go.microsoft.com\/fwlink\/?linkid=830387\n "version": "0.2.0",\n "configurations": [\n {\n "name": "LLDB Launch",\n "type": "cppdbg",\n "request": "launch",\n "program": "${workspaceFolder}\/a.out",\n "args": [],\n "stopAtEntry": true,\n "cwd": "${fileDirname}",\n "environment": [],\n "externalConsole": false,\n "MIMode": "lldb",\n "miDebuggerPath": "${workspaceFolder}\/lldb-mi\/src\/lldb-mi",\n "logging": {"engineLogging": true, "trace": true, "traceResponse": true},\n "setupCommands": [\n {\n "text": "setting set target.disable-aslr false",\n "description": "Fix packet returned error 8",\n "ignoreFailures": false\n }\n ]\n }\n ]\n}<\/code><\/pre>\n\n\n\nThe things to change are:<\/p>\n\n\n\n
\n- Change
program<\/code> to your program’s executable path.<\/li>\n\n\n\n- Change
MIMode<\/code> to lldb<\/code>.<\/li>\n\n\n\n- Add
miDebuggerPath<\/code>.<\/li>\n\n\n\n- Modify the
setupCommands<\/code>.<\/li>\n<\/ul>\n\n\n\nAfter compiling your application, you can now use the “Play” button on the debugging tab to launch it under the debugger.<\/p>\n\n\n\n
That’s It!<\/h2>\n\n\n\n
That’s everything – you now have CMake, the Clang compiler, and the debugger – all in Docker and hooked up for remote developing with VS Code.<\/p>\n\n\n\n
If you have closed VS Code and want to resume development, go to WSL and navigate to your project directory, then run “code ."<\/code> When VS Code launches, you will get a dialog with a button to “Reopen in Container”. Press this and it will launch the Docker container and open the VS Code server within it.<\/p>\n\n\n\nTroubleshooting<\/h2>\n\n\n\nCMake Fails to find Build Tools<\/h3>\n\n\n\n\nCMake was unable to find a build program corresponding to “Unix Makefiles”. CMAKE_MAKE_PROGRAM is not set. You probably need to select a different build tool.<\/p>\n<\/blockquote>\n\n\n\n
CMake requires that the make<\/code> package is installed.<\/p>\n\n\n\nClang++ Fails to Find Standard Headers<\/h2>\n\n\n\n\n“fatal error: ‘iostream’ file not found”<\/p>\n<\/blockquote>\n\n\n\n
Clang requires that the g++<\/code> package is installed to provide standard headers.<\/p>\n\n\n\nCouldn’t start client cpptools<\/h3>\n\n\n\n
You get the error “Couldn’t start client cpptools”, and the Output windows shows:<\/p>\n\n\n\n
\n [Error – 6:15:14 PM] Starting client failed
Launching server using command \/root\/.vscode-server\/extensions\/ms-vscode.cpptools-1.7.1\/bin\/cpptools failed.<\/p>\n<\/blockquote>\n\n\n\n
Trying to run cpptools<\/code> from the terminal says File not found<\/code>.<\/p>\n\n\n\nThis occurs under Alpine Linux because cpptools<\/code> requires the g++<\/code> and gcompat<\/code> packages to be installed.<\/p>\n\n\n\nThe LLDB Debugger Hangs When Launched<\/h3>\n\n\n\n
When you view the Debug Console in VS Code, you see that the debugger is hung at Wait for connection completion.<\/code><\/p>\n\n\n\nLoad launch.json<\/code> and set "externalConsole": false<\/code>.<\/p>\n\n\n\nThe LLDB Debugger Immediately Exits<\/h3>\n\n\n\n
When you view the Debug Console in VS Code, you see:<\/p>\n\n\n\n
\nERROR: Unable to start debugging. Unexpected LLDB output from command “-exec-run”. ‘A’ packet returned an error: 8<\/p>\n<\/blockquote>\n\n\n\n
This is because the debugger is trying to disable ASLR (Address Space Layout Randomization), but cannot due to Docker’s default security settings. GDB ignores this failure, but it causes LLDB to exit.<\/p>\n\n\n\n
Load launch.json<\/code> and add the setupCommands<\/code> given in “Configuring the Debugger with launch.json”.<\/p>\n\n\n\nThe LLDB Debugger Gives “No module named ‘lldb'” or “‘run_one_line’ is not defined”<\/h2>\n\n\n\n
When you view the Debug Console in VS Code, you see:<\/p>\n\n\n\n
\nTraceback (most recent call last):
File “<string>”, line 1, in <module>
ModuleNotFoundError: No module named ‘lldb’
Traceback (most recent call last):
File “<string>”, line 1, in <module>
NameError: name ‘run_one_line’ is not defined<\/p>\n<\/blockquote>\n\n\n\n
This is caused by the LLDB Python module not being installed. Check the package list in the instructions above, and add py3-lldb<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"Getting Clang to run inside a Visual Studio Code remote container on Docker is surprisingly difficult, but I’ll take you through all the steps you need.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[12,13,15],"class_list":["post-76","post","type-post","status-publish","format-standard","hentry","category-cpp","tag-clang","tag-docker","tag-wsl"],"_links":{"self":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/76","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/comments?post=76"}],"version-history":[{"count":16,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/76\/revisions"}],"predecessor-version":[{"id":241,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/posts\/76\/revisions\/241"}],"wp:attachment":[{"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/media?parent=76"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/categories?post=76"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/zebra-north.com\/code\/wp-json\/wp\/v2\/tags?post=76"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}