> 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-windows.md).

# Set up an IDE and Debug a Windows DLL Library

## USe VS Code

### Build the DLL in debug configuration

Here is an example of the recommended compilation flags (For MinGW toolchain) to use when building a debug DLL for a CIGRÉ library. It is based on the SCRX9.c file distributed with the IEEE/CIGRÉ DLL Modeling Method V1.1 publication.

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

```
gcc -shared -g -O0 -Wall -fno-omit-frame-pointer SCRX9.c -o SCRX9.dll
```

{% endcode %}

<table data-search="false"><thead><tr><th width="180">Flags</th><th>Usage</th></tr></thead><tbody><tr><td><strong>-shared</strong></td><td>builds a DLL</td></tr><tr><td><strong>-g</strong></td><td>generate debug symbols</td></tr><tr><td><strong>-00</strong></td><td>no optimization</td></tr><tr><td><strong>-Wall</strong></td><td>basic warnings</td></tr><tr><td><strong>-fno-omit-frame-pointer</strong></td><td>improve debugging</td></tr></tbody></table>

### Deploy the debug DLL in your HYPERSIM model

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

### Run the HYPERSIM simulation

Start the simulation exactly as you normally would. Let it run until it reaches the point where your DLL will be executed.

### Setup VS Code to debug your DLL

To be able to use the debugger in VS Code you must create a launch.json file.

1. Launch Run and Debug (Ctrl+Shift+D)

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

2. Select create a launch.json file

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

3. Paste the following configuration **if your DLL has been built using MSVC**

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

```
{
"version": "0.2.0",
"configurations": [
    {
        "name": "Attach to Process (MSVC)",
        "type": "cppvsdbg",
        "request": "attach",
        "processId": "${command:pickProcess}"
    }
    ]
}
```

{% endcode %}

4. Save this configuration

### Attach VS Code to the simulation process

1. Click on Run icon (Attach to Process) or click Run → Start debugging

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

2. Find and select the HYPERSIM simulation executable.

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

{% hint style="info" %}
If unsure which process to attach to, look for the name of the model running.
{% endhint %}

### Debug your DLL code

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-4e8638e839dd45e0734cf6e80855a40c12b1e0d8%2Fide-dll-windows-result.png?alt=media" alt=""><figcaption></figcaption></figure>

### Terminate the Debugging Session

It is important to stop debugging in the correct order to avoid orphaned processes, locked files, or inconsistent simulation states.

* Stop the HYPERSIM Simulation

  Ensure that the debugger is not halted at a breakpoint, since this can cause a simulation timeout in HYPERSIM while trying to stop.
* Debugger should automatically detach.

## Visual Studio

### Build the DLL in debug configuration

1. Open your DLL project in Visual Studio.
2. Make sure that the debug build configuration has the following options:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-fe6f18ae5cc4e842ead40d5b225c93ff58dc8554%2Fide-dll-windows-VS-opt.png?alt=media" alt=""><figcaption><p>Optimization: Disabled (/Od)</p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8f4e7163e835131affb54353c7be546c07c299dd%2Fide-dll-windows-VS-prog.png?alt=media" alt=""><figcaption><p>Debug information format: Program Database (/Zi)</p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c6f34fa0e9b090805fa2b5b9b386e80c93965d3d%2Fide-dll-windows-VS-gen.png?alt=media" alt=""><figcaption><p>Generate Debug info: Generate Debug Information (/DEBUG)</p></figcaption></figure>

3. Select Build Configuration: Debug (from the toolbar or Build → Configuration Manager…).
4. Build the project.

{% hint style="info" %}
Visual Studio generates a **.pdb file** next to the DLL. This file contains debug symbols required for breakpoints and stepping through the code.
{% endhint %}

### Deploy the debug DLL in your HYPERSIM model

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

### Run the HYPERSIM simulation

1. Start the simulation exactly as you normally would.
2. Let it run until it reaches the point where your DLL will be executed.

### Attach Visual Studio to the simulation process

1. In Visual Studio, go to **Debug → Attach to Process…**

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

2. Find and select the HYPERSIM simulation executable.

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

3. Click **Attach**.

{% hint style="info" %}
If unsure which process to attach to, look for the name of the model running.
{% endhint %}

### Debug your DLL code

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-83c60e438929b42fed3cf413f84ff546703720f1%2Fide-dll-windows-VS-result.png?alt=media" alt=""><figcaption></figcaption></figure>

### Terminate the debugging session

It is important to stop debugging in the correct order to avoid orphaned processes, locked files, or inconsistent simulation states.

1. Stop the HYPERSIM Simulation

   Ensure that the debugger is not halted at a breakpoint, since this can cause a simulation timeout in HYPERSIM. Be sure to resume DLL execution before issuing a stop command in HYPERSIM.
2. Stop the Visual Studio Debugger

   Press **Shift + F5** or choose **Debug → Stop Debugging**.

## HYPERSIM standalone debugging on Windows

This section explains how to debug a CIGRÉ DLL directly in VS Code **without having to start the simulation in HYPERSIM** beforehand.

* **Build the DLL** in debug configuration as described in the VS Code section.
* **Deploy the debug DLL** in your HYPERSIM model as described in the VS Code section.

### Setup the HYPERSIM standalone mode

1. To run in standalone mode, the model must have been 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.
3. Open VS Code
4. Open or create the files .vscode\settings.json and .vscode\launch.json

   <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>
5. In settings.json define the following variables:

   * hyp\_model\_name (the name of the model ex: standalone\_demo)
   * hyp\_model\_code\_path (the generated code folder name from step 2 ex: C:\Users\JonathanVillani\HYPERSIM\code\master.o3826\your\_username\13ddb4d57d5a071a667df374e9ef66b52b536a32)
   * hyp\_install\_path (the folder Windows from your installed HYPERSIM ex: C:\OPAL-RT\HYPERSIM\hypersim\_master.o3826\Windows)
   * hyp\_gdb\_path (GDB executable to use)

   Example of a settings.json file:

   <pre data-overflow="wrap" data-line-numbers><code> {
    "hyp_model_name": "standalone_demo",
    "hyp_model_code_path": "C:\\Users\\JonathanVillani\\HYPERSIM\\code\\master.o3826\\your_username\\13ddb4d57d5a071a667df374e9ef66b52b536a32",
    "hyp_install_path": "C:\\OPAL-RT\\HYPERSIM\\hypersim_master.o3826\\Windows",
    "hyp_gdb_path": "C:\\msys64\\mingw64\\bin\\gdb.exe
    }
   </code></pre>
6. In launch.jsondefine a new configuration:

   <pre data-overflow="wrap" data-line-numbers><code> {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Launch Model",
                "type": "cppdbg",
                "request": "launch",
                "program": "${config:hyp_model_code_path}\\exec\\rt\\Windows\\bin\\${config:hyp_model_name}.exe",
                "args": ["--cfg", "${config:hyp_model_code_path}\\exec\\rt\\Windows\\cfg\\sim.cfg"],
                "cwd": "${config:hyp_install_path}\\HyServer\\rt\\bin",
                "miDebuggerPath": "${config:hyp_gdb_path}",
                "environment": [
                    {
                        "name": "PATH",
                        "value": "%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"
                    }
                ]
            }
        ]
    }
   </code></pre>

### Debug

Once the setup is complete, set breakpoints in the desired CIGRÉ functions. Since the application is running in standalone mode, you do not need to attach the debugger to the process manually. Execution will stop automatically when a breakpoint is reached.

<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 VSCode **Run and Debug tab** (Ctrl+Shift+D), select **Launch Model** in the upper right corner and click **Start Debugging**(F5).

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

Once execution starts, the breakpoint should be hit, allowing you to trace the execution flow 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>


---

# 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-windows.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.
