Skip to main content
  1. HyperX Support
  2. Analysis Plugins
  3. Getting Started

Developing Plugins

Use this tutorial to learn how to set up and run the Sample HyperX Analysis Plugin Package. You can download the final source code for this Sample Plugin from here.

System Requirements

It is highly recommended to use Microsoft Visual C++, although other compilers are also supported (see Compiler Support). This tutorial will be using Microsoft Visual C++. For help installing Visual C++ 2017 (or MinGW-w64 with Eclipse - not recommended), see Compiler Notes - System Requirements.

Step #1: Create a Project

  1. Open Visual Studio.

  2. Ensure that the Desktop Development with C++ workload is installed under Tools | Get Tools and Features.

    plug-tut-workloads.png

  3. On the Start Page click New Project.

    plug-tut-create_project.png

  4. In the "Installed" frame, select Visual C++ | Windows Desktop | Windows Desktop Wizard.

    plug-tut-project_select_cpp_2017.png

  5. Set the project and solution names to e.g. "Hs_Sample" and "Sample", respectively (any names can be used). Optionally, change the solution folder location if desired.

    plug-tut-name_project_cpp.png

  6. Click Create.

  7. Select Dynamic Link Library (.dll) from the application type dropdown, enable Empty Project, and disable Precompiled Header. If you are using VS 2019, the option to enable SDL checks is not available on the project form - this is fine, and should not have any impact on successfully importing the Sample Plugin.

    plug-tut-project_wizard_cpp_2017.png

  8. Click OK.

Step #2: Insert Source Code

  1. Copy/download the source code from the installation directory. E.g.: $(InstallDirectory)\Code\AnalysisPlugins_V{VERSION_NUMBER}.zip.

  2. Unzip the folder.

  3. Copy and paste all of the C++ source files (*.cpp, *.h) into the project directory, e.g.

    C:\HS-Plugins\Sample\Hs_Sample

    plug-tut-copy_src_cpp_2.png

  4. Copy and paste the plugin API folder (e.g. hs_7_3_53) into the solution directory, e.g.

    C:\HS-Plugins\Sample Plugin

    plug-tut-copy_api.png

  5. Return to Visual Studio. In the Solution Explorer right-click the project and select Add | Existing Item.

    plug-tut-add_existing.png

  6. Add all the *.cpp and *.h files in the project directory. Click OK.

    Important

    Do not add any files from the hs_#_#_# folder.

  7. The project files should be similar to the following. The default filters "Header Files", "Resource Files" and "Source Files" were deleted and manual filters "Core Analysis Code" and "HS Interface" were added. Modifying the filters is optional.

    plug-tut-vs-add_src_checkpt.png

  8. In case of using source control, you will need to manually add the Plugin API files to source control.

Step #3: Add Include Directory

The HyperX Plugin API must be included by the compiler.

  1. In the Solution Explorer, right-click the project name and select Properties.

  2. Select "All Configurations" from the Configuration: drop-down menu.

  3. In the settings tree browse to Configuration Properties | C/C++ | General.

  4. Set the include directory to corresponding hs_#_#_# folder. Here we are using the $(SolutionDir) macro to specify that we are using the solution directory.

    $(Solution_Dir)hs_7_3_53

    plug-tut-plugin_preferences_directory.png

  5. Click OK.

Step #4: Set Compiler Options

Here we will statically link to the C++ runtime to remove library dependencies when distributing the DLL to other users. See Library Dependencies. In addition to that, we will set the compiler up to be more strict about warnings to catch potential errors during compile time, instead of at runtime.

Tip

These steps are recommended to write more portable, safer code. However, they are not required by the Plugin API. If you need to link to an external library with different settings, you do not need to follow these steps.

  1. Right-click the project name in the solution explorer and select Properties.

  2. Set the Configuration to "Release".

  3. In Configuration Properties | C/C++ | Code Generation| Runtime Library set the value to: Multi-threaded /MT

    plug-tut-cpp-runtime_lib_release.png

  4. Click Apply.

  5. (Optional) In Debug mode, the equivalent option is: Multi-threaded Debug /MTd

    Using /MTd may reduce the amount of data that the debugger can display. Therefore, using this option is not recommended.

  6. The settings for warnings can be found under Configuration Properties | C/C++ | General. The following settings are recommended. Note that they are set for both Release and Debug modes.

    plug-tut-cpp-warning_level.png

  7. If compiling for an API version greater than or equal to 8.0.58, the language standard must be set to C++17. Navigate to Configuration Properties | General | C++ Language Standard and set the C++ Language Standard to ISO C++17 Standard (/std:c++17)

    plug-tut-cpp-lang-standard.png

Step #5: Set Build Configuration

The DLL has to be compiled using the 64-bit build configuration.

  • In the Solution Platforms drop-down, select "x64".

    plug-tut-vs-set_x64_platform.png

Tip

It is recommended to delete the x86 (32-bit) configuration in the Configuration Manager dialog to avoid confusion. Select "Edit" in the "Active solution platform:" drop-down menu. Similarly, select "Edit" in the "Platform" dropdown menu for the Hs_Sample project (also in the Configuration Manager).

Step #6: Set Post-Build Event

In order to automatically install Hs_Sample.dll in the proper folder, we can set a post-build event to copy the DLL from the solution folder to whichever folder we desire.

  1. Right-click the project name in the solution explorer and select Properties.

  2. Set the Configuration to "All Configurations" and the Platform to "x64".

  3. In Configuration Properties | Build Events | Post-Build Event | Command Line, enter the following macro:

    xcopy "$(OutDir)$(TargetName).dll" "C:\HyperX\Plugins\Sample\" /Y

    Note

    Remember to use quotes. Remember to end the target directory with a slash so that a new directory is created if necessary. The /Y parameter suppresses the overwrite prompt when copying the file.

  4. Click OK.

Step #7: Compile

  1. In the file menu go to Build | Build Solution or press CTRL + SHIFT + B.

    plug-tut-build_solution_update.png

  2. Verify that a new Hs_Sample.dll has been added to the output directory.

Step #8: Verify DLL Exports

Before testing the DLL in HyperX, you can verify that the proper methods are exposed by following the steps outlined in DLL Exports, Dependencies and Symbols.

Note

If the Sample Plugin loads into HyperX and runs without error, this step is not necessary.

Step #9: Run in HyperX

  1. Open a Project in a HyperX Database.

  2. Select Plugins from the Analysis tab of the Ribbon.

    plug-tut-ribbon.png

  3. On the proceeding Plugin form, browse to the Plugin Package DLL file by clicking the ellipsis or Add button.

    dbx-analysis_plugins_form.png

    If the configuration passes validation, you will see configuration data for the Package, Plugins, and Analysis Settings.

    Note

    Multiple Plugin Packages can be installed by clicking Add.

  4. Click OK. The Plugin Package configuration data is installed in the Database.

  5. Create a Failure Mode for this Plugin Package and add it to an Analysis Property.

  6. Activate the user defined analyses for the skin and stringer segments. See Viewing Plugin Results.

  7. Analyze the Structure. View results in the Analysis Watch Window.

    plug-tut-failure_tab-stringer_ms.png

Step #10: Debug

The Plugin can be debugged interactively by pointing the Visual Studio debugger to the main HyperX Sizing Executable and the HyperX Project input file.

  1. In the Solution Explorer, right-click the Plugin Project and select Properties.

  2. Make sure that the configuration is set to Debug.

  3. In Configuration Properties | Debugging, set the command and command arguments fields.

    Note

    Make note of the quotes surrounding the command arguments and the lack of quotes in the command.

    • Command: $(InstallationDirectory)\Executable\Hs_V205.exe

      Note

      Do not surround with quotes.

    • Command Arguments: “[ProjectWorkingFolder]\Input\InputData.INI”

      Note

      Remember to surround the command argument with quotes.

      • [ProjectWorkingFolder]: The name of the folder containing the active project

      • C:\HyperX\Projects\Temp is the default HyperX Project working folder base path. The location of the folder may vary depending on your installation location.

        Tip

        You can quickly find your Project working folder by using ”Database | Project | Open Project Working Folder" function from the Database tab of the Ribbon.

        plug-tut-ShowProjectOpenFolder.png

      Important

      Be sure that you have previously Analyzed the Structure with panel user analyses active. This will write the proper input file (*.ini) for the HyperX Sizing Executable.

    The C++ settings are shown below.

    Note

    This screenshot assumes that the project name is "SamplePluginDemo".

    plug-tut-property_pages.png

  4. Set a breakpoint in the HsAnalysis.cpp source file by left-clicking in the left margin.

  5. Press F5 to begin debugging, or click the green "Local Windows Debugger" in the top middle of Visual Studio.

    1. Check the spelling of the command and the command arguments. You can run the Hs_V205.exe in the command line to verify the spelling.

      • In the project properties, be sure that the command field is not surrounded by quotes.

      • In the project properties, be sure that the command arguments field is surrounded by quotes.

    2. Be sure that you have previously Analyzed the Structure with panel user analyses active. This will write the proper input file (*.ini) for the HyperX Sizing Executable.

  6. View the Local Variables window using Debug | Windows | Locals. You can add a variable to the Watch window by right-clicking a variable in the source code and selecting Add Watch.

    plug-tut-breakpoint_cpp.png

Recently Viewed

Didn’t find what you’re looking for?

Submit a Request

Didn’t find what you’re looking for?

Create a New Post