How to Debug CI Issues Locally

Note: When you try to Google “how to debug Github Actions locally” you will find a tool called Act <https://github.com/nektos/act>__. In our experience, we seem to always be in th 10% of edge cases that Act cannot faithfully reproduce locally, i.e., feel free to try it, but it probably won’t work.

Building the Docker Image

Prerequisites

Have Docker installed.
- We recommend using Docker Desktop.
Have the Docker daemon running.
- If you are using Docker Desktop, just make sure the app is open.

Steps

In a terminal run docker pull ghcr.io/nwchemex/nwx_buildenv:latest.
- This will download the Docker image we use in our CI workflows.
- It’s somewhat big and will probably take a while to download.
Run the image: docker run -it ghcr.io/nwchemex/nwx_buildenv:latest.
Clone the branch you want to debug.
- git clone https://url/of/repo/your/branch/is/part/of.git
- cd /directory/where/repo/was/cloned
- git fetch
- git checkout your_branch_name
You now need to manually run the commands that are in the workflow you want to debug. Workflows can be found in the .github repository in the .github/workflows directory.
- If you are building a library that uses CMake follow the test_nwx_library.yaml workflow.
(Optional) After you are done building we recommend saving the state of the container as a new image. This way you don’t have to repeat steps 2-3 if the container is stopped/closed for whatever reason.
- From another terminal run docker commit <container_id> nwchemex_debug_image to create the image.
(Optional) If you would like to debug the code in VSCode you can install the “Dev Container” extension and then attach to the running container.

FAQs

When trying to run an executable in a Docker container under lldb, I get an lldb error: lldb error: 'A' packet returned an error: -1.
- This means lldb was not allowed to start debugging the executable.
- If you have Apple silicon you may not be able to debug x86_64 binaries (source).