> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/create-oem-controller-code/use-cigre-interface/set-up-an-ide-and-debug-a-dll-library-for-linux.md).

# Set up an IDE and Debug a Linux DLL Library

In this section, we explain how to debug a Linux CIGRÉ library while it is running. Two debugging methods are currently supported: Attach to Process and Standalone.

The **Standalone method** provides greater flexibility, particularly when debugging functions that are sensitive to timing. It automatically launches the simulation on the target and attaches the debugger at the start of execution. In contrast, the **Attach to Process method** requires you to manually start the simulation from the HYPERSIM user interface and then manually attach the debugger to the running process.

Keep in mind that Standalone mode is currently in beta and may have limitations.

Your target must have its **isolation disabled** in order to have **SSH communication** working while debugging.

## Common steps

### Build the .so in debug configuration

For a smoother debugging experience, it is recommended to build the library on the target machine used for execution.

Ensure that the library is compiled using a debug configuration rather than the default release configuration. Debug symbols should be enabled, and compiler optimizations should be disabled.

{% code overflow="wrap" lineNumbers="true" %}

```
fPIC -O0 -g -Wall
```

{% endcode %}

### Deploy the Debug .so in your HYPERSIM model

* Locate the newly built .so in your project’s Debug output folder.
* Replace the existing .so in your HYPERSIM model with this new Debug version via Edit CIGRÉ unit for the required CIGRÉ block(s).
* Make use of the new .so via Reload CIGRÉ Unit.

### HYPERSIM steps

1. To debug the library, the model containing the CIGRÉ debug .so file must be generated at least once in HYPERSIM by clicking the **Generate Code** button in the HYPERSIM ribbon.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d6a23177e9231a2fd8dab6b1c3636ee35b17828b%2Fide-windows-generate-code.png?alt=media" alt=""><figcaption></figcaption></figure>

   The code generation folder is specified in the **Simulation Settings** window, in the **Code Directory** field.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ed983592d5dc652ba696c957097d36f654b44537%2Fide-code-generated-folder.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Before a **sim.cfg file** can be generated, the simulation must be run locally at least once. The path to the file is then displayed in the **simout tab** in HYPERSIM.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-0c37a549e84846467327aba360745a66412db519%2Fide-dll-linux-sinfile.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Enable the simulation to run indefinitely for standalone mode or until you stop the debugger. To do so, open the sim.cfg file on your target and set StopTime to -1.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b0c315de4d6e3e671bf94c207611905ac552baa1%2Fide-dll-lnux-standalone-mode.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
When debugging, you should only need to edit **sim.cfg** once. The only time you would lose your changes is if you start the same simulation from HYPERSIM. In that case, you will need to edit sim.cfg again to enable standalone debugging.
{% endhint %}

## VS Code

### Setup tools requirements

The GDB version bundled with HYPERSIM is old and does not allow setting breakpoints at runtime. GDB on Cygwin and MinGW cannot attach to or break a running process. To pause the application being debugged or set breakpoints, press Ctrl+C in the application's terminal, refer to <https://github.com/Microsoft/vscode-cpptools/issues/595>

To have a better debugging experience with normal breakpoint support, it is recommended to install **msys** on your Windows system and use their latest gdb.

* Download the installer at <https://www.msys2.org/> and proceed with the default installation.
* Open the msys terminal and install gcc ang gdb with

  <pre data-overflow="wrap" data-line-numbers><code>  pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-gdb
  </code></pre>
* Edit your settings.json and set your **gdb\_path** variable to C:/msys64/ucrt64/bin/gdb.exe (adjust to your actual installation path).

### Setup VS code for SSH remote debugging

1. Install the **Remote - SSH** extension from Microsoft

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-910c3c164c2c477827eaec8de44e2b294bfc75cf%2Fide-linux-vscode-step1.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Add your opalrtx VM target

   CTRL+SHIFT+P or F1 and type SSH and select C/C++: Select an active SSH target

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-5e59efd0d2c694f5100ee105e6b5da78e452fa4b%2Fide-linux-vscode-step2.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Click add an SSH target

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-63d31d4a576f7e62d7daa4a2b479557cebbeb778%2Fide-linux-vscode-step3.png?alt=media" alt=""><figcaption></figcaption></figure>
4. Enter the name of your target followed by root@\<target ip>
5. Finally select the SSH configuration file in Users folder

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-9cbfadd062b8f89a5a8d8bb49a82abf9eadaf134%2Fide-linux-vscode-step4.png?alt=media" alt=""><figcaption></figcaption></figure>

   You should now be able to connect to your target via SSH

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7d790ca7f757796b95d240a0d249d30bf8bfc4fa%2Fide-linux-vscode-step5.png?alt=media" alt=""><figcaption></figcaption></figure>
6. Install the Native Debug extension on your newly added target.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-06b64bb9f57c68cc6ee92bb032944f2c2ba2394c%2Fide-linux-vscode-step6.png?alt=media" alt=""><figcaption></figcaption></figure>
7. Open VSCode
8. Connect to you Linux target via SSH
9. Open or create the files .vscode\settings.json and .vscode\launch.json in your workspace

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a0be86675d921daa84b8b04a092a92249cf67101%2Fide-vscode-code-json.png?alt=media" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example of a settings.json file</summary>

{% code overflow="wrap" lineNumbers="true" %}

```
{
    "hyp_model_name": "circuit1",
    "hyp_model_code_path": "/export/local/ssr/sandbox/code/master.o3826/your_username/596decac6f625e68b5511ff168fec289a8db4f0a",
    "hyp_install_path": "/export/local/ssr/hypersim-target_master.o3826/linux-oprtlinux3-64",
 }
```

{% endcode %}

</details>

<details>

<summary>Example of a launch.json file</summary>

{% code overflow="wrap" lineNumbers="true" %}

```
{
"version": "0.2.0",
"configurations": [
    {
        "name": "(gdb) Launch model oprtlx",
        "type": "gdb",
        "request": "launch",
        "target": "${config:hyp_model_code_path}/exec/rt/linux-oprtlinux3-64/bin/${config:hyp_model_name}",
        "arguments": "--cfg ${config:hyp_model_code_path}/exec/rt/linux-oprtlinux3-64/cfg/sim.cfg",
        "cwd": "${config:hyp_install_path}/HyServer/rt/bin",
        "env": {
            "HYPERSIM_DIR": "${config:hyp_install_path}/..",
            "LD_LIBRARY_PATH": "${config:hyp_install_path}/HyServer/rt/lib:${config:hyp_install_path}/HyServer/rt/lib/Services:${config:hyp_install_path}/HyServer/rt/bin:${config:hyp_install_path}/bin:${config:hyp_install_path}/lib:/opt/intel/compilers_and_libraries_2019.3.199/linux/compiler/lib/intel64_lin/",
            "PATH": "${config:hyp_install_path}/HyServer/rt/lib:${config:hyp_install_path}/HyServer/rt/lib/Services:${config:hyp_install_path}/HyServer/rt/bin:${config:hyp_install_path}/bin:${env:PATH}"
        },
        "stopAtEntry": false,
        "valuesFormatting": "parseText",
        "debugger_args": [
        "-iex", "set follow-fork-mode child",
        ],
        {
            "name": "Attach to oprtlx process",
            "type": "gdb",
            "request": "attach",
            "target": "insert_your_pid_here",
            "cwd": "${config:hyp_install_path}/HyServer/rt/bin"
        }            
    }
]
}
```

{% endcode %}

</details>

### Debug in Standalone mode

Once the setup is complete, you can set breakpoints in any of your CIGRÉ functions. Because the simulation is running in Standalone mode, there is no need to manually attach the debugger to the process. Any breakpoints you set will be hit automatically.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-28211aba8d36ff66989699a0bd7cf0469a315441%2Fide-VScode-debug.png?alt=media" alt=""><figcaption></figcaption></figure>

In VS Code **Run and Debug tab** (Ctrl+Shift+D), select **Launch model oprtlx** in the upper right corner and click **Start Debuggin** (F5)

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-611c50bc8a6542aecffc0e6f328fef36ec2ae663%2Fide-linux-vscode-step9.png?alt=media" alt=""><figcaption></figcaption></figure>

Once started, your breakpoint should be hit, and you should be able to trace the execution and inspect variables.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1305e3a6b1159812d59794a1bc5b2b8144b2d449%2Fide-VScode-result.png?alt=media" alt=""><figcaption></figcaption></figure>

### Terminate the debugging session

To terminate your debugging session, simply click Stop or press Shift+F5. This will also automatically stop the HYPERSIM simulation.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-35a06a529ca33223521e8f17884bc60a95c19911%2Fide-linux-vscode-step11.png?alt=media" alt=""><figcaption></figcaption></figure>

**Make sure to stop the simulation** in HYPERSIM once you have disconnected and are done debugging. {% hint &}

## Visual Studio

### Install requirements

To debug Linux executables from Visual Studio on a Windows system, ensure that the following components are installed as part of your Visual Studio setup:

* C++ for Linux and Mac Development
* C++ CMake tools for Linux and Mac
* Remote File Explorer for Linux and Mac

To validate this simply run Visual Studio Installer and click on modify.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-10ecc6091e9a10af3d793addb953ea73cc478b2d%2Fide-linux-visualstudio-step1.png?alt=media" alt=""><figcaption></figcaption></figure>

Make sure that the required components are installed. If not, select them and click Modify.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-31a96f9396b3f432087b9a5fcea77736b155a02a%2Fide-linux-visualstudio-step2.png?alt=media" alt=""><figcaption></figcaption></figure>

### Setup Visual Studio for SSH remote debugging

To connect to your Linux target from Visual Studio, you must first add it to the **Connection Manager**.

1. In Tools, select Options.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-cdb278d29d6911bc5388f205cf2116c957bdf297%2Fide-linux-visualstudio-step3.png?alt=media" alt=""><figcaption></figcaption></figure>
2. In the options, select **Connection Manager** from the Cross Platform section and click Add.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c5f45f5ab19c543f0b66b192ad63742830753f95%2Fide-linux-visualstudio-step4.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Enter your target information

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-a376f33398bad97ad3e7a73c56f924a33f39a94d%2Fide-linux-visualstudio-step5.png?alt=media" alt=""><figcaption></figcaption></figure>
4. If the connection is valid, it should appear in the Connection Manager list.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d3442b88697ea665af7cc6ce575079775046b629%2Fide-linux-visualstudio-step6.png?alt=media" alt=""><figcaption></figcaption></figure>

### Debug in Standalone mode

In **Standalone mode**, Visual Studio automatically launches the HYPERSIM simulation and attaches the debugger when the simulation starts. This makes it possible to debug the initialization code of your CIGRÉ libraries. The following section assumes that all CIGRÉ libraries have been built in debug mode, refer to [Create a Linux MSBuild C++ project in Visual Studio](https://learn.microsoft.com/en-us/cpp/linux/create-a-new-linux-project?view=msvc-170).

1. Create a new Visual Studio project

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-85ef337124333e5eddaf1b1a1471fa4918e8c4e3%2Fide-linux-visualstudio-step7.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Filter for Linux and select Empty Project

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7bf2988846e304f402b4c0cc2abbe3ddd093a6dd%2Fide-linux-visualstudio-step8.png?alt=media" alt=""><figcaption></figcaption></figure>
3. In the newly added project, add the source files for all CIGRÉ libraries that you want to debug.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ce1e5d33ea61ef2a0fe8ead3c57187eb8d295bbf%2Fide-linux-visualstudio-step9.png?alt=media" alt=""><figcaption></figcaption></figure>
4. Configure the Debug properties for your target

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-9894ca30818983aff0c57be190517cabe3a80a50%2Fide-linux-visualstudio-step10.png?alt=media" alt=""><figcaption></figcaption></figure>
5. Set the **Pre-Launch Command** in Configuration Properties → Debugging

   <pre data-overflow="wrap" data-line-numbers><code> export HYPERSIM_DIR=/export/local/ssr/hypersim;export LD_LIBRARY_PATH=$HYPERSIM_DIR/linux-oprtlinux3-64/HyServer/rt/lib/:$HYPERSIM_DIR/linux-oprtlinux3-64/HyServer/rt/lib/Services/:$HYPERSIM_DIR/linux-oprtlinux3-64/HyServer/rt/bin/:$HYPERSIM_DIR/linux-oprtlinux3-64/bin/:$HYPERSIM_DIR/linux-oprtlinux3-64/lib
   </code></pre>
6. Set the simulation executable as the program to be launched by the debugger.

   <pre data-overflow="wrap" data-line-numbers><code> /export/local/ssr/sandbox/code/your_hypersim_version/your_username/your_id/exec/rt/linux-oprtlinux3-64/bin/your_simulation_executable_name
   </code></pre>
7. Set the program arguments

   <pre data-overflow="wrap" data-line-numbers><code> --cfg /export/local/ssr/sandbox/code/your_hypersim_version/your_username/your_id/exec/rt/linux-oprtlinux3-64/cfg/sim.cfg
   </code></pre>
8. Set working directory

   <pre data-overflow="wrap" data-line-numbers><code> -/export/local/ssr/sandbox/code/your_hypersim_version/your_username/your_id/exec/rt/linux-oprtlinux3-64/bin
   </code></pre>
9. Set Debugging Mode to gdb
10. Set Debug Child Processes to Yes.
11. Set the debugger path (the VM image or Linux target should already have it deployed at this location—adjust if needed).

    <pre data-overflow="wrap" data-line-numbers><code>/usr/bin/gdb
    </code></pre>
12. Set Remote Debugger Type to gdb

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-abfaa9445a6b205542f3db333b8f924907bfa4f9%2Fide-linux-visualstudio-step11.png?alt=media" alt=""><figcaption></figcaption></figure>
13. Configure Startup Projects…

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-476a720c0e2fe4eb37333e569355b1404d8af67f%2Fide-linux-visualstudio-step12.png?alt=media" alt=""><figcaption></figcaption></figure>
14. Uncheck the Build and Deploy options, as we are only debugging prebuilt CIGRÉ libraries and do not need to build or deploy anything.

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-1989e5ac0d3113744d8c45dd85fd89c9c2efde12%2Fide-linux-visualstudio-step13.png?alt=media" alt=""><figcaption></figcaption></figure>
15. Open source file(s) and add breakpoints

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-50e3c0c839e24e611f1527b8ec613de755596f87%2Fide-linux-visualstudio-step14.png?alt=media" alt=""><figcaption></figcaption></figure>
16. Press Start Debugging button or F5

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-d9059823ae2681d067beaf7af35963535c087784%2Fide-linux-visualstudio-step15.png?alt=media" alt=""><figcaption></figcaption></figure>

    Once attached, you can: \* Set breakpoints \* Step through lines of code \* Inspect local and global variables \* View call stacks \* Watch memory / registers if needed Execution will pause whenever it reaches your breakpoints.

    <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-2c1485c2d7ae60fcd199ce4ddef064c4a26b9ae4%2Fide-linux-visualstudio-step16.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Terminate the debugging session

To terminate the debugging session, click **Stop** button or press **Shift+F5**. The HYPERSIM simulation will then close automatically.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c2fa3ada3b8ea9f74f08d10dd106fbebed14f367%2Fide-linux-visualstudio-step17.png?alt=media" alt=""><figcaption></figcaption></figure>

### Debug using attach to process

To debug properly, you must give the debugger access to the source code used to compile your CIGRÉ library. To do this, go to File → Open → Folder and select the folder containing the code. You can use the code located on your Windows machine.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-2e4c0064589617269b114f459d8b8c8f29aac4b3%2Fide-linux-visualstudio-step18.png?alt=media" alt=""><figcaption></figcaption></figure>

It is also possible to use the source code located on your Linux machine. To do so, simply go to View → Remote File Explorer.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c5df2f2049f8a1b10002b56ce338fe4ec90bd208%2Fide-linux-visualstudio-step19.png?alt=media" alt=""><figcaption></figcaption></figure>

Select your target, connect to it, and open the source files you want to debug.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c1b65482d55d85a2b9bc7274ef1aba8aafba175a%2Fide-linux-visualstudio-step20.png?alt=media" alt=""><figcaption></figcaption></figure>

You are now ready to start your simulation in HYPERSIM. Once it is launched, connect to the target and run the following command:

{% code overflow="wrap" lineNumbers="true" %}

```
ps -auxf
```

{% endcode %}

You should see a process with the same name as your simulation file. For example, here we have circuit1.ecf.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-5b801c50d6591b7ac7bcbbb7168edfcb2228aabf%2Fide-linux-visualstudio-step21.png?alt=media" alt=""><figcaption></figcaption></figure>

The PID to use for debugging should always be the child process (RLl status).

1. In Visual Studio select Debug and click on **Attach to Process…** or press **CTRL+ALT+P**

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-ddcaa5ef2fe3ff87d59f245419a4240c043369b8%2Fide-linux-visualstudio-step22.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Select SSH as connection type, then type the name of your executable and select the proper PID
3. Select Native (GDB) code and click on Attach.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-01efc9c907773ea477c9aa2335eac31bfa4450b5%2Fide-linux-visualstudio-step23.png?alt=media" alt=""><figcaption></figcaption></figure>

   Once attached, you can:

   * Set breakpoints
   * Step through lines of code
   * Inspect local and global variables
   * View call stacks
   * Watch memory / registers if needed
   * Execution will pause whenever it reaches your breakpoints.

   <figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-80f12e3c0af7a1ed1f6e83cb5e092f348742962e%2Fide-linux-visualstudio-step24.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Unfortunately, when using the **Attach to Process** debugging method, the only way to debug the initialization functions of a CIGRÉ library is to introduce a sufficiently long delay in the code. This provides enough time to manually attach the debugger to the process before the initialization code executes.
{% endhint %}

#### Terminate the debugging session

To terminate your debugging session, simply click **Stop** or press **Shift+F5**. You can reconnect at any time, as long as the simulation has not been stopped in HYPERSIM.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8318e194b6bbe6182edd5116535eb1049047838f%2Fide-linux-visualstudio-step25.png?alt=media" alt=""><figcaption></figcaption></figure>

**Make sure to stop the simulation** in HYPERSIM once you have disconnected and are done debugging.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/create-oem-controller-code/use-cigre-interface/set-up-an-ide-and-debug-a-dll-library-for-linux.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
