From 307ad0401b754d4dcb18f65cb10dd2ea914b32c8 Mon Sep 17 00:00:00 2001 From: "Ryan M. Richard" Date: Tue, 7 Oct 2025 13:25:32 -0500 Subject: [PATCH 1/3] notes on debugging CI --- .../continuous_deployment/debugging.rst | 80 +++++++++++++++++++ docs/source/continuous_deployment/index.rst | 1 + 2 files changed, 81 insertions(+) create mode 100644 docs/source/continuous_deployment/debugging.rst diff --git a/docs/source/continuous_deployment/debugging.rst b/docs/source/continuous_deployment/debugging.rst new file mode 100644 index 0000000..61312ec --- /dev/null +++ b/docs/source/continuous_deployment/debugging.rst @@ -0,0 +1,80 @@ +.. Copyright 2025 NWChemEx-Project +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +############################## +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 `__. 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 +===== + +1. 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. + +2. Run the image: ``docker run -it ghcr.io/nwchemex/nwx_buildenv:latest``. +3. 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`` + +3. 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. + +4. (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 nwchemex_debug_image`` to create the + image. + +**** +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 < https://github.com/docker/for-mac/issues/5191#issuecomment-821319621>`__). diff --git a/docs/source/continuous_deployment/index.rst b/docs/source/continuous_deployment/index.rst index a345841..bf3ca10 100644 --- a/docs/source/continuous_deployment/index.rst +++ b/docs/source/continuous_deployment/index.rst @@ -28,3 +28,4 @@ deploying the master branch (continuous deployment). ci_maintainer_notes documentation + debugging From 20c16fdc77a947178298ded59079b7c936d2b216 Mon Sep 17 00:00:00 2001 From: "Ryan M. Richard" Date: Tue, 7 Oct 2025 13:39:51 -0500 Subject: [PATCH 2/3] fix whitespace --- .../continuous_deployment/debugging.rst | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/continuous_deployment/debugging.rst b/docs/source/continuous_deployment/debugging.rst index 61312ec..a675c56 100644 --- a/docs/source/continuous_deployment/debugging.rst +++ b/docs/source/continuous_deployment/debugging.rst @@ -31,8 +31,8 @@ Prerequisites ============= - Have Docker installed. - - We recommend using - `Docker Desktop `__. + - We recommend using + `Docker Desktop `__. - Have the Docker daemon running. - If you are using Docker Desktop, just make sure the app is open. @@ -53,18 +53,18 @@ Steps - ``git checkout your_branch_name`` 3. You now need to manually run the commands that are in the workflow - you want to debug. Workflows can be found in the ``.github`` + 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. + - If you are building a library that uses CMake follow the + ``test_nwx_library.yaml`` workflow. 4. (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. + container is stopped/closed for whatever reason. - - From another terminal run + - From another terminal run ``docker commit nwchemex_debug_image`` to create the image. @@ -72,9 +72,9 @@ Steps FAQs **** -- When trying to run an executable in a Docker container under lldb, I get an +- 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 + + - 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 < https://github.com/docker/for-mac/issues/5191#issuecomment-821319621>`__). From 6ce5b6e8517aaa6eae22116121ecf11d37d3e11d Mon Sep 17 00:00:00 2001 From: "Ryan M. Richard" Date: Tue, 7 Oct 2025 13:47:08 -0500 Subject: [PATCH 3/3] fix typos --- docs/source/continuous_deployment/debugging.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/source/continuous_deployment/debugging.rst b/docs/source/continuous_deployment/debugging.rst index a675c56..e4f6ab8 100644 --- a/docs/source/continuous_deployment/debugging.rst +++ b/docs/source/continuous_deployment/debugging.rst @@ -31,8 +31,7 @@ Prerequisites ============= - Have Docker installed. - - We recommend using - `Docker Desktop `__. + - We recommend using `Docker Desktop `__. - Have the Docker daemon running. - If you are using Docker Desktop, just make sure the app is open. @@ -55,7 +54,7 @@ Steps 3. 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. + ``.github/workflows`` directory. - If you are building a library that uses CMake follow the ``test_nwx_library.yaml`` workflow. @@ -77,4 +76,4 @@ FAQs - 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 < https://github.com/docker/for-mac/issues/5191#issuecomment-821319621>`__). + (`source `__).