Ensure you have Docker Desktop running first or at least before "Reopen in Container" !
Let's use the HelloHarbour sample application from the Harbour_Samples repo
The idea of developing in Windows while running/debugging in Linux can be implemented by using VSCode from our host Windows and telling VSCode how to create/use Docker Containers.
For Microsoft Windows developers, if we want to also develop in Linux, Ubuntu in this case, your choices was to install a Virtual Machine application like VMware Workstation, Virtualbox (Oracle) or Microsoft Hyper-V (Windows Pro), or to remote control inside another Linux machine (VNC or other).
With the introduction by Microsoft of WSL2, and the use of Docker via Docker Desktop, the process can be completely transparent.
Additionally your source code does not even have to be copied into the Docker container. The folder from where you opened VSCode will be "mounted" inside the running docker "container" as a folder /workspaces/<"name" property inside devcontainer.json>/. So in the example below the R:\Harbour_Samples\HelloHarbour Windows folder will appear as /workspaces/HelloHarbour/
If you bash inside the Docker container created by the "Dev Containers" VSCode extension, you will be running as "root", which is kind of the Windows administrator account. No need to prefix Linux commands with "sudo" (super user do).
Any folder or workspace accessed via VSCode can have a ".vscode" folder where we usually see a "launch.json" and "tasks.json" files. Those files are respectively use to configure the debugger and create tasks that can be execute on demand.
The "Dev Containers" extension needs a ".devcontainer" folder where you need a "devcontainer.json" file and at least one Dockerfile.
The "devcontainer.json" will have a list of settings letting the "Dev Containers" extension know how to create a docker image and run it as a docker container.
Currently only one of those settings can exists at one time. We can create multiple Dockerfiles. But only one of those can be referred to/used by when creating a docker image.
To see a complete list of attributes you can use in a devcontainer.json file go here
. We will review the attributes used in our Harbour_Samples.
Line 6: The "dockerfile" attribute will specify the name of a Dockerfile to use. In the samples all come with two Dockerfiles, one to build from scratch, and another one to get a pre-built image available from DockerHub.
Line 7: When Docker builds an image if use a "Dockerfile" file, and a "context". The "context" is the starting folder where COPY and ADD commands will use files from.
In Dev Containers, we actually don't need to COPY or ADD files, therefore the "context" (line 7 below) will be ignored
Line 11-17: The following are settings to be used while inside the container. The Harbour extension install locally had its path local to Windows, here we need to make them local ton inside the container.
Line 20: It is possible to mount additional local folder to appear as it they are local to the container. In the Harbour_Samples, we placed all the build and debug tools in a parallel folder named "BuildTools".
- "postStartCommand": In the HelloHarbour sample we wanted to use the Linux syslog as an equivalent to Microsoft Windows DebugView. To capture syslog messages and write them to a log file a service had to be started. "service rsyslog start". In Dev Containers there is no support for Dokerfile instructions CMD and ENTRYPOINT. But it is possible to execute one or many commands once the container is running, and before you can access it.
- "extensions": This is the list VSCode extensions that should be used while in container mode.
For a complete reference of all the options in devcontainer.json visit here
Use the pseudo button at the left bottom corner to go in Container mode.
Select "Reopen in Container". If you are already inside the container and you edit the devcontainer.json or the related Dockerfile, you could also select "Rebuild Container".
If you want to see the progress for building the docker image and starting the container, use the "(show log)" link.
Initial build, or rebuild after changes in configuration, can take many minutes.
Example of a build log.
Also monitor the status in the running threads list (lower right area).
The "+" icon can also be used to open a bash terminal inside the container for example.
You will be logged in as "root" sitting on the mount of your local development folder. The path will be /<workspaces/devcontainer.json.name>.
Remember, this folder only exists in the container, not the image.
In the HelloHarbour sample, you can also view a "DebugView" like log. Use the "tail" linux command in a new bash terminal. The -n50 will specify to see the last 50 log entries.
During your execution in debug mode (for now), you will be able to see tracing messages.
Use the <Compile and Debug> button to start execution in debug mode. If you are using a new version of the Harbour Debugger, also update ../BuildTools/vscode_debugger.prg from the Harbour VSCode extension.
In this example we can see we are paused right after the Altd() function call, and see the line 6 message appear in the "tail" bash terminal.
Review the Dockerfile (in .devcontainer folder) and HelloHarbour.prg (bottom area of file) to see what was needed for syslog to work.