## Debugging generated code

| This page is primarily intended for the developers of the CIF simulator, and not its end users.

The CIF simulator generates highly optimized code for the specification, to speed up the simulation. By enabling the Debug the generated code (by writing it to disk) option (Output category), the generated code can be written to disk, for further debugging.

### Output directory

If the simulation is performed from within Eclipse, and a project named `org.eclipse.escet.cif.simulator.debug` exists, is not closed, and has a `src` directory, the generated code will be written to that `src` directory. Otherwise, the generated code will be written to the directory containing the input specification file.

Regardless, the code is also always written to a `cifcode` sub-directory. If this sub-directory does not yet exist, it is created. If it already exists, all relevant existing files, such as `.java` files, are removed from the sub-directory first, before the newly generated code is written.

### Written files

This results in several files being written to the `cifcode` directory. One of these files is `DebugSimulator.java`, which contains the simulation options that were used and always shows the option dialog. The working directory for the simulation performed via `DebugSimulator.java` is the same working directory as the original simulation. This allows additional files, such as configuration files, to be found.

The `org.eclipse.escet.cif.simulator.debug` project contains a launch file (`debug-cif-simulator-generated-code.launch`) that can be used to reproduce the simulation implemented by the generated code. This launch configuration assumes that the code was generated in the `src` folder of the `org.eclipse.escet.cif.simulator.debug` project and was compiled to the `target/classes` folder of that project.

### How to use

To use this feature, follow these steps:

- Start an Eclipse ESCET development environment.

- Make sure your workspace is automatically rebuilt, by enabling the Build Automatically option in the Project menu.

- Start a sub-Eclipse application, by clicking Run Run Configurations… or Run Debug Configurations, and selecting escet-product and clicking Run.

- In the sub-Eclipse that opens, make sure the CIF specification (the `.cif` or `.cifx` file) that you like to simulate is available in the workspace.

- In the sub-Eclipse, import the `org.eclipse.escet.cif.simulator.debug` source project.

- Simulate the CIF specification, and make sure you enable the Debug the generated code (by writing it to disk) option.

- Continue simulation, if desired.

- Once the simulation has terminated, switch back to the main Eclipse.

- Refresh the `org.eclipse.escet.cif.simulator.debug` project.

- Set breakpoints in the generated Java code, or in the simulator code, as desired.

- Right click `debug-cif-simulator-generated-code.launch` in the `org.eclipse.escet.cif.simulator.debug` project, and choose Debug as debug-cif-simulator-generated-code.launch.

- Debug the simulation, with the generated code, as you would any Java program.

### Starting the simulator with generated code

The launch configuration that is used, uses the Load debug code option (Simulator category). Using this option, the classpath (directory) where the already generated code is located, is specified. By specifying it, the simulator knows from where to load it.

Simulations not started from this launch configuration, generally don’t use this option. They load the input specification, validate it, generate fresh code, and compile the code in-memory, or use compiled code files.

Simulations using the generated code ignore all options related to repeated simulations. That is, the Load debug code option takes priority over the Compile only option (Compiler category), and simulating with compiled code files.

A warning is printed to the console if the generated code was generated with a different version of the simulator than the one used to simulate it. Ignoring the warning may lead to unexpected simulation results, or even simulator crashes.