cjdb/amcpp-stdlib repository overview

⁠Applied Modern C++ Docker Container

⁠Table of Contents

1. Introduction
   1. Libraries
   2. Tools
      1. Compilers
      2. Linkers
      3. Runtime analysis
      4. Build tools
      5. Other
2. Installing Docker (please read)
3. Running a Docker container
   1. Hello, world!
   2. Mounting a volume
      1. Initial steps for Windows 10 with Azure Active Directory only
      2. Initial steps for all Windows 10 users
   3. Interactive mode
   4. Compiling a program
   5. Debugging a program
   6. Using this container on Windows

⁠Introduction

This is a Docker image that aims to have up-to-date C++ libraries and tools for use. Regard for backwards-compatibility is not considered.

⁠Libraries

• Boost⁠
• range-v3⁠
• cmcstl2⁠
• Catch2⁠
• GSL⁠

⁠Tools

⁠Compilers

• GCC 8
• Clang 7
  • clang-tidy
  • clang-format
  • clang-tools

⁠Linkers

• ld
• gold
• lld 7

⁠Runtime analysis

• GDB
• LLDB 7
• Valgrind
• AddressSanitizer
• ThreadSanitizer
• LeakSanitizer
• UndefinedBehaviorSanitizer
• Valgrind

⁠Build tools

• CMake
• Conan (profiles included are default (GCC) and clang (uses libc++ and libc++abi))
• Ninja
• Make

⁠Other

• Git
• Python 3
• Binutils

⁠Installing Docker (please read)

To install Docker, please be sure to choose the link to the operating system that best suits your laptop. Please be sure to install Docker by following the instructions provided: Docker can often be out-of-date on Linux systems, which exposes security vulnerabilities and can make removing the Docker packages a nightmare.

• Mac⁠
• Windows⁠
• Ubuntu⁠
• Debian⁠
• CentOS⁠
• Fedora⁠
• Other⁠

Note that while I can try to assist, I am not an expert with Docker, and you might be required to post your questions to a forum (please link me if you do so that we both learn).

⁠Running a Docker container

⁠Hello, world!

This is a first Docker program.

1. Open a terminal. If you're using Windows, please use PowerShell, not Command Prompt or WSL (this will be important later).

1. Enter the command docker run --rm hello-world into the terminal and press Enter. The following text should appear.

What we've done here is instruct to the Docker that we'd like to run the container called hello-world. The --rm flag tells the Docker daemon to clean up the Docker container once we finish using it, so that it's not hanging around, consuming resources.

Because we didn't have the Docker image already downloaded, the Docker daemon will attempt to download the image from the DockerHub server.

⁠Mounting a volume

In this section, we'll look at exposing a single directory on your computer to the Docker image so that you can interact with the real world. We'll also use this section to download and run amcpp-stdlib for the first time. If you're using Windows, you'll need to do a few extra steps, and if you're using Windows 10 with Azure Active Directory, you'll need to do a few more steps before that.

⁠Initial steps for Windows 10 with Azure Active Directory only

If you don't use Windows 10 with Azure Active Directory, you can skip this step. If you're not sure whether you've got an Active Directory setup, skip this section for now, and if you run into problems

1. Open Start Menu.
2. Type 'Add user' and press Enter.
3. Press 'Add someone else to this PC'.
4. Press 'I don't have this person's sign-in information'.
5. Press 'Add a user without a Microsoft account'.
6. Add a user called 'docker_user', and give them a password that meets your AD password requirements, and save.
7. Press the newly created 'docker_user', and then select 'Change account type'.
8. Change 'docker_user' from a Standard User to an Administrator and press OK.
9. When asked for credentials regarding Docker, you'll need to provide this user and password.
10. Carry on to 'Initial steps for Windows'.

Note that if you ever delete docker_user or demote docker_user to a standard user, you'll experience problems.

⁠Initial steps for all Windows 10 users

1. Right-mouse click on the Docker icon in your system tray.
2. Press 'Settings'.
3. Select 'Shared Drives'.
4. Select the drive you wish to share, and press Apply.
5. You'll likely be asked for credentials (you need to be an administrator to do this step). Provide your user credentials and press OK. If you run into problems trying to authenticate yourself, this means you're either not an admin or you are on an Azure Active Directory installation. If you aren't an administrator, you'll probably just need to have an admin grant you permission. If an admin is having difficulty authenticating, then try the steps above.

⁠Steps for all users

1. Create a directory called amcpp-stdlib.
2. Enter the command docker run --rm -v <absolute-path-to-amcpp-stdlib>:/data cjdb/amcpp-stdlib /bin/bash -c 'echo "hello" > /data/hello.txt' You'll see a long list of images being downloaded, and then the prompt should return.
3. Type cat amcpp-stdlib/hello.txt. The word hello should appear on the line above your prompt.

What we've done here is downloaded and run the container cjdb/amcpp-stdlib, which is the container used in Applied Modern C++. The -v <absolute-path-to-amcpp-stdlib>:/data tells Docker to mount (expose) the directory amcpp-stdlib under the directory /data in the Docker image.

When normally we write something to disk in a Docker container, it's not actually written to disk, and will disappear when we exit the Docker environment. Anything written to this /data directory will be written to your physical disk, and persist until you delete it.

Finally, /bin/bash -c 'echo "hello" > /data/hello.txt' is the command we provide to the Docker container to do work. In this case, we start a shell and write to a file called hello.txt in the special /data directory (which is really an access point to our amcpp-stdlib directory).

⁠Compiling a program

1. Enter the command docker run --rm -i -t -v <absolute-path-to-amcpp-stdlib>:/data cjdb/amcpp-stdlib.
2. Instead of getting back your usual prompt, you'll see something like root@b87288407b4a:/#. The -i -t flags have enabled us to enter an interactive mode with pseudo-TTY⁠, so that we can provide many commands to the Docker container, and interleave them with actions such as reading output before making the next command, or more regularly interacting with a program.
3. Enter the command cd /data && ls && rm hello.txt && ls. You should see hello.txt appear exactly once.
4. Type the following in, then press Ctrl + D on your keyboard. Mind the newline after the closing brace.

cat > hello.cpp
#include <iostream>

int main()
{
   std::cout << "Hello, world!\n";
}

1. Enter the command c++ -Wall -Wextra -Werror -std=c++17 -o hello hello.cpp.
2. Enter the command ./hello. The message Hello, world! should appear on its own line.
3. Enter the command clang++ -Wall -Wextra -Werror -std=c++17 -o hello2 hello.cpp.
4. Enter the command ./hello2. The message Hello, world! should appear on its own line again.
5. Enter the command exit to return you to your original terminal.

⁠Debugging a program

Docker has certain security mechanisms in place, which make it impossible to run a debugger over a program. In this section, we'll look at how to enable debugging, profiling, and other forms of run-time analysis.

1. Enter the command docker run --rm --cap-add=SYS_PTRACE -i -t -v <absolute-path-to-amcpp-stdlib>:/data cjdb/amcpp-stdlib. This lets us add the Linux capability of using ptrace⁠, which is used on Linux systems for runtime analysis. Once again, we're in an interactive pseudo-TTY session.
2. Enter the command cd /data.
3. Enter the command g++ -Wall -Wextra -Werror -g -o hello hello.cpp.
4. Enter the command gdb -q hello.
5. Type r and press Enter to run the program hello.
6. The text Hello, world! should appear on its own line.
7. Type q and press Enter to exit GDB.
8. Enter the command valgrind ./hello. The following should appear.

⁠Using this container on Windows

Docker creates a virtual machine that talks with Windows via the SMB protocol. By default, SMBv3 is used, but unfortunately, there's a bug in the Windows 10 SMBv3 driver that makes it impossible to enact certain developer tools, such as parallel builds and link-time optimisation. This is because when one process is reading a file, it suddenly disappears from the perspective of the entire container. Fortunately, there's a workaround, and that's to get Docker and Windows to communicate via SMBv2. What we'll need to do is create a shared network drive, and share the amcpp-stdlib directory with said network drive.

To enact this workaround, open PowerShell (this is PowerShell-specific), and enter the following commands. There are a few variables that you'll need to set, so don't just copy and paste!

Note: this workaround unfortunately requires that Docker take the password of an administrator and store it as plaintext. This is not ideal. While care has been taken to ensure that your password is not visible in the terminal, no guarantees are made regarding how Docker will handle this data. Follow with caution.

$username = # the user who shared access to the drive in Docker settings
$path = # path to exposed directory
$volume = # name you want your volume to have

# Share a path across a network.
$volume_name = "amcpp-$volume" # do this to make sure it's more likely to be unique
New-SmbShare -Name "$volume_name" `
	-Path "$path" `
	-FullAccess "$username"

# Get your password (secure)
$secure_password = Read-Host "Enter a password for user account" -AsSecureString

# Convert your password to plaintext
$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure_password)
$password = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

$BSTR = $null
$secure_password = $null

# Apply the permission changes to Docker.
docker volume create `
	--driver local `
	--opt type=cifs `
	--opt device="\\$env:computername\$volume_name" `
	--opt o="rw,relatime,vers=2.0,sec=ntlmsspi,cache=strict,username=$username,pass=$password,domain=$env:computername,uid=0,noforceuid,gid=0,noforcegid,addr=10.0.75.1,file_mode=0777,dir_mode=0777,iocharset=utf8,nounix,serverino,mapposix,nobrl,mfsymlinks,noperm,rsize=65536,wsize=65536,echo_interval=60,actimeo=1" `
	"$volume_name"

# Delete the plaintext password
$password = $null

From here-on, provided that $username's password doesn't change, you'll be able to use Docker as though it were a bare-metal machine running Ubuntu 18.04. You should also be able to switch to WSL, if that is your preferred terminal. Now, when you run Docker, you'll need to run it like so: docker run --rm --cap-add=SYS_PTRACE -i -t -v $volumne_name:/data cjdb/amcpp-stdlib. The difference between this and the previous command is that we've replaced the absolute path to the directory with the name of the volume we're sharing.

If you'd like to undo the above, you can run this:

# Un-apply the permission changes to Docker.
docker volume remove "$volume_name"

# Close the network share
Remove-SmbShare -Name "$volume_name" -Force

Packaging this into a script will reduce the amount of time that you expose your password in plaintext, consider wrapping both segments into a PowerShell script, and running Docker in-between. If you choose to do this, you'll need to use PowerShell at all times.

⁠Acknowledgements

I'd like to thank Morris Hafner for helping debug issues surrounding Conan.io and David Wood for helping me to evaluate the effectiveness of this Docker image. Duncan McBain also provided valuable feedback.