Developer Environment

Integrated Development Environments (IDEs) can help you develop your own custom delegates much more easily and error-free than if you were to use a simple text editor and Command Prompt. If you choose to use an IDE, you can configure it however you like, and with whatever build tool you like. To get you started, here are some recommendations for configuring the following IDEs to use Gradle:

You should have already installed Java, Gradle, and your IDE before following these steps.

Project organization

Regardless of what IDE you use, you should set up your project directory first. You can put the directory for your delegate source code anywhere, but it typically makes sense to keep it alongside your No Magic project file, the location you want to deploy your built delegate module to, and any other project-related files like an STK scenario. Figure 1 shows this organization for the completed tutorial sample included in the Behavior Execution Engine installation.

Figure 1: The tutorial sample project directory

Inside your delegate source code directory, you should also follow the pattern used by the samples:

Figure 2: The tutorial sample delegate source code directory

  1. To set up an environment for development, you can copy the contents of the samples\build directory from the Behavior Execution Engine installation into your delegate source code directory. After you later create a delegate provider for your module, copy its fully qualified name into the \resources\META-INF\services\com.agi.moxie.spi.DelegateProvider file.
  2. Import your project into your IDE, using the instructions in the next sections, and then return here to finish configuring Gradle.
  3. In your IDE, open the gradle.properties file.
  4. Set the com.agi.moxie.installDir property to the path to your Behavior Execution Engine installation (e.g., C:/Users/<username>/Documents/Behavior Execution Engine).
  5. Set the com.agi.moxie.delegateModuleDir property to the location you want to deploy your delegate module to. This should be a project-relative directory (e.g., ../delegates) or your delegate module home directory (e.g., C:/BehaviorExecutionEngine/DelegateHome).
  6. If you plan to use STK classes in your delegates, set the com.agi.moxie.stkInstallDir property to the path to your STK installation (C:/Program Files/AGI/STK 12 by default); otherwise, you can ignore this property.

    STK-related features are only available if you acquired Behavior Execution Engine as part of STK Enterprise or otherwise have a valid license for STK. If you acquired Behavior Execution Engine as part of ModelCenter Enterprise but have access to a valid STK license, contact us for access to the STK-related features.

  7. Set the com.agi.moxie.noMagicInstallDir and com.agi.moxie.noMagicPropFileName properties to the corresponding values for your No Magic modeling tool. The default values for the tools are already listed in the file for reference.
  8. Save the file, if your IDE does not do that automatically, and close it.
  9. Open the settings.gradle file.
  10. Set the rootProject.name property to the name of your delegate module project.
  11. Save the file, if your IDE does not do that automatically, and close it.

You should now be ready to start writing delegates. The Gradle build script provides two tasks in particular that you should be aware of:

  • You can use the install task to build and deploy your delegate module.
  • You can use the launchNoMagicWithDebugging task to open your No Magic modeling tool in a way that enables you to attach your IDE's debugger to examine your delegates during a simulation.

Eclipse

Import your delegate project

  1. In Eclipse, select File > Import.
  2. If the Welcome page pops up, you can just click Next >.
  3. Select Gradle > Existing Gradle Project and then click Next >.
  4. Browse... to your delegate source code directory and click Next >.
  5. If this is the first time you are importing a Gradle project, click Configure Workspace Settings....

    Figure 3: Importing a Gradle project into Eclipse

    Follow these substeps to configure Gradle:
    1. If you are familiar with using a Gradle wrapper then you can select it and configure your Gradle project accordingly. Otherwise, you should just Browse... to your Local installation directory of Gradle (the top-level gradle-#.# directory, not the bin directory).
    2. Leave your Gradle user home empty to use the default (C:\Users\<username>\.gradle).
    3. Browse... to your Java home (e.g. C:\Program Files\Java\jdk1.8.0_202).

      Figure 4: Recommended Gradle configuration in Eclipse

    4. Click Apply and Close.
  6. Click Finish.

Configure content assist

If you would like to modify Eclipse's default Java code suggestions, follow these steps:

  1. Select Window > Preferences.
  2. In the left sidebar, select Java > Editor > Content Assist > Advanced.
  3. Select your preferred options. You probably want to select both Java Proposals and Java Type Proposals.
  4. Click Apply and Close.

Create a debug configuration

If you run the launchNoMagicWithDebugging Gradle task, you can attach the Eclipse debugger by creating a debug configuration.

  1. Select Run > Debug Configurations....
  2. In the left sidebar, select Remote Java Application and click the New Configuration button in the upper left.
  3. Name the configuration and Browse... to your delegate module project.
  4. Leave the Host as localhost and set the Port to 5005.
  5. Click Debug.

After you have created the configuration and attached with it once, you can attach in the future by just clicking the Debug button again.

IntelliJ IDEA

Import your delegate project

  1. In IntelliJ IDEA, select File > Open or, if IntelliJ IDEA opens to a Welcome page, just click Open.
  2. Select your delegate source code directory and click OK.
  3. Click Trust Project and, if given the choice, choose a window to open your project in.
  4. If IntelliJ IDEA reported a Sync error when opening your project, follow these substeps to configure Gradle:
    1. Select File > Settings.
    2. In the left sidebar, select Build, Execution, Deployment > Build Tools > Gradle.
    3. Leave your Gradle user home empty to use the default (C:\Users\<username>\.gradle).
    4. If you are familiar with using a Gradle wrapper, then you can Use Gradle from a 'gradle-wrapper.properties' file, but you will need to configure your Gradle project for that. Otherwise, you should just Use Gradle from the Specified location of your Gradle installation (the top-level gradle-#.# directory, not the bin directory).
    5. Select your Gradle JVM, adding a new JDK if necessary (e.g., C:\Program Files\Java\jdk1.8.0_202).

      Figure 5: Recommended Gradle configuration in IntelliJ IDEA

    6. Click OK.

Configure code completion

If you would like to modify IntelliJ IDEA's default Java code suggestions, follow these steps:

  1. Select File > Settings.
  2. In the left sidebar, select Editor > General > Code Completion.
  3. Select your preferred options. You probably want to select both Basic Completion and Type-Matching Completion.
  4. Click OK.

Attach the debugger

In IntelliJ, you do not need to set up any debug configurations. If you run the launchNoMagicWithDebugging Gradle task, you can attach by following these steps:

  1. Select Run > Attach to Process....
  2. Select com.nomagic.launcher.Launcher (5005).

VS Code

Install required extensions

  1. In VS Code, click the Extensions icon on the left.
  2. Using the search bar, find and install the following extensions:
    1. Language Support for JavaTM by Red Hat
    2. Debugger for Java
    3. Gradle for Java
  3. Restart VS Code.

Import your delegate project

  1. In VS Code, select File > Open Folder.
  2. Select your delegate source code directory and click Select Folder.
  3. Click Yes, I trust the author.
  4. Select View > Command Palatte... (or press CtrlShiftP).
  5. Search for and select Preferences: Open User Settings (JSON).
  6. Add the following lines to the JSON file, replacing the paths to your Java or Gradle homes if necessary (make sure to use forward slashes in these paths): 
    "java.jdt.ls.java.home": "C:/Program Files/Java/jdk1.8.0_202",
    "java.import.gradle.home": "C:/Gradle/gradle-7.2",
    "java.import.gradle.wrapper.enabled": false,
  7. Restart VS Code.

Create a debug configuration

VS Code requires a separate debug configuration for each project.

  1. In VS Code, select the Run and Debug icon on the left.
  2. Click create a launch.json file.
  3. In the Select Debugger shortcut menu, select Java.

    Figure 6: Creating a debug configuration in VS Code

  4. Select Run > Add Configuration.
  5. In the list of available configurations, select Java: Attach to Process.
  6. Delete the Launch Current File configuration settings from launch.json.

    Figure 7: Recommended debug configuration in VS Code

  7. Save launch.json.

Attach the debugger

If you run the launchNoMagicWithDebugging Gradle task, you can attach the VS Code debugger by following these steps:

  1. Select Run > Start Debugging.
  2. Select the process with debug port: 5005.