#1605 Added Documentation for Debugging Methods (#1655)

* Manual for debugging cobigen-eclipse

TODO: Add screenshots

* Rename cobigen-eclipse_debugging to cobigen-eclipse_debugging.asciidoc

* Manual for debugging cobigen-eclipse

TODO: Add screenshots

* Manual for debugging cobigen-maven-systemtest

TODO: Add screenshots

* Added Screenshots for cobigen-debugging

* Create test.md

* Delete documentation/images/CobiGen-Debugging directory

* Delete test.md

* Screenshots for Maven Test Debugging

* Added screenshots to cobigen-maven-systemtest_debugging.asciidoc

* Add files via upload

* Finished cobigen-cli_debugging.asciidoc

Added screenshots and made it look fancy

* Finished cobigen-eclipse_debugging.asciidoc

Added screenshots and structure

* Added Screenshots for Eclipse Debugging Guide

* Small Fix in wording

* Resolved some requested changes

* Fixed numbering

* Uploaded screenshot for cli debug configuration

* Delete cli-debug-configuration.png

* Uploaded screenshot of cli debug configuration

* Solved requested changes

* Fixed wrong formatting

* Resolved requested change

* Fixed requested changes

* Added screenshot for cli debugging guide

* Update cobigen-cli_debugging.asciidoc

* Update cobigen-eclipse_debugging.asciidoc

* Fixed Typo

* Added docs to sidebar

* Asciidoc extension needed

* Screenshots for other paths and source selection

* Added screenshot with other path example

* Added screenshot of example selection of core

* Update cobigen-eclipse_debugging.asciidoc

---------

Co-authored-by: jan-vcapgemini <[email protected]>

documentation/_Sidebar.asciidoc

@@ -43,6 +43,9 @@
 * link:mgmt_dependency-and-license-tracking[License tracking of dependencies]
 * link:guide_dev_troubleshooting[Troubleshooting]
 * link:setup-jre[Setup JRE in eclipse]
+* link:cobigen-cli_debugging.asciidoc[Debugging Cobigen-CLI]
+* link:cobigen-eclipse_debugging.asciidoc[Debugging Cobigen-Eclipse]
+* link:cobigen-maven-systemtest_debugging.asciidoc[Debugging Cobigen Maven Systemtest]
 
 ==== Implementation Docs
 * link:eclipse-plugin_development[Eclipse-Plugin Development]

documentation/cobigen-cli_debugging.asciidoc

@@ -0,0 +1,49 @@
+= Debugging Cobigen-CLI:
+
+1. Open Debug Configurations by clicking on "Run > Debug Configurations" in Eclipse.
+
+2. Click on "Java Application" and then click on "New".
+
+3. Select the "cli" project and set the Main class to "com.devonfw.cobigen.cli.CobiGenCLI". +
+image:images/debugging/cli-debug-configuration.png[]
+
+4. Add any arguments that you would normally use when running the CLI.
+
+5. Make sure that every CLI command is valid. You can find an overview of possible commands [here](https://github.com/devonfw/cobigen/wiki/howto_Cobigen-CLI-generation#commands-and-options).
+
+6. Under the Arguments tab, set the Working Directory to the path, where CLI is being executed (uses destination of call as root). +
+image:images/debugging/other-path.png[]
+
+The following steps are only required for debugging tests or remote debugging of CLI. Commands added to arguments can be directly debugged already.
+
+==== Warning:
+Without those steps the active cobigen home will be used for the tests! +
+With them the tests use a temporary folder instead.
+
+7. Open cobigen.bat and add the following flag +
+*-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=1044* +
+to the command before "-cp": +
+image:images/debugging/cobigen-bat.png[]
+
+8. Now wait for the console to show "listing for port 1044" and attach the debugger.
+
+9. Go to the Remote Java Application tab in Debug Configurations and click on "New".
+
+10. Select the "cli" project and set the Connection Type to "Standard (Socket Attach)".
+
+11. Set the Host to "localhost" and the Port to the value shown in the screenshot (1044).
+
+12. Save the configuration and start the debugger.
+
+
+=== Debug System Tests for CLI ===
+To debug system tests for the CLI,... 
+
+1. Open the file "cg" located in "Cli > src > main > assembly > resources > bin".
+
+2. Add the marked flag from the screenshot (*-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=1044*) to the file before "-cp".
+
+3. Repeat step 2 for "cg.bat".
+
+4. If you have changed files in core, rebuild the core by running "mvn clean install -f cobigen/ -DskipTests". +
+Rebuild the CLI by running "mvn clean install -f cobigen-cli/ -DskipTests" or "./build.sh -dpCcore,cli" in your favorite shell so the files are included in the jar.

documentation/cobigen-eclipse_debugging.asciidoc

@@ -0,0 +1,49 @@
+= Debugging Cobigen-Eclipse
+
+=== To debug Cobigen-Eclipse, follow the steps below: ===
+
+==== Previous procedure for adding the plugins: ====
+Install Cobigen-Plugins via "Help > Install New Software > Add > cobigen-plugins > target/repository" and add it.
+
+==== Current procedure for adding the plug-ins: ====
+1. Open the target file "Eclipse.test.targets.2018-12.target" and add the target/repository of each plugin by clicking "Add > Directory > ...": +
+image:images/debugging/addDirToTarget.png[]
+
+2. Click on "Reload" and save. +
+ Sidenote: Change your eclipse target platform by clicking on "Window > Preferences > ..." +
+ image:images/debugging/target-platform.png[] +
+ (Use Eclipse 2018-12 as it is also used in maven. Running Platform will use your installed Eclipse version.)
+
+3. To run Eclipse in the runtime, right-click on "cobigen.eclipse" and select "Debug As > Eclipse Application". +
+ Sidenote: Plugins will not be displayed under installed software of the new Eclipse. Open the OSGi Console (arrow at the top right in console) and type "ss" to show all loaded plugins.
+ image:images/debugging/osgi-console.png[]
+
+4. In the new Eclipse you can now execute Cobigen commands while setting breakpoints and classicly debugging in the original Eclipse.
+
+5. For example, in CobiGenPaths.class > attach source > select project folder "cobigen". Class files cannot be modified, so you need to find the equivalent java file. Breakpoints are better placed in the equivalent Java files rather than in the class files. Here is an example selection of core.
+image:images/debugging/source-location-selection.png[]
+Workaround: Use the eclipse plug-in "Open .java file for .class file" +
+Sources can be attached to a class (f.e. core.jar) using right click on the eclipse project Properties/Java Build Path/Libraries/Classpath and adding a source to core.jar (unfold core.jar and add a Source Attachment from Workspace location).
+
+6. Click "Terminate" in the top left to close the environment. +
+
+
+== Debugging (SWTBot-)Tests ==
+
+=== To debug tests in Cobigen-Eclipse, follow these steps: ===
+
+1. Right-click on the test you want to debug and select "Debug As" and then "Debug Configurations".
+
+2. In the "Debug Configurations" window, select "JUnit Plug-in Test" and click on "New Configuration" to create a new test configuration.
+
+3. Make sure that "Run in UI thread" is not selected.
+
+4. Click "Apply" to save the new configuration.
+
+5. Click "Debug" to start the test in debug mode.
+
+6. SWTBot will perform the test and you can use classic debugging to debug any issues that may arise.
+
+7. If the test is aborted and the cleanup function doesn't work, it is recommended to delete the "junit-workspace" folder in the workspace, as this folder may contain information about what happened during the test and tests copy their resources (template-set project and input project) there.
+
+*Extra:* You can also use the "Debug Configurations" window to add the current debug session to your favorites menu. This allows you to easily access the debug session history later by selecting "Debug" and then the name of the debug session from the favorites menu.

documentation/cobigen-maven-systemtest_debugging.asciidoc

@@ -0,0 +1,23 @@
+= Debugging Cobigen Maven Systemtest =
+
+==== To debug Cobigen Maven Systemtest, follow these steps: ====
+
+1. Open the file AbstractMavenTest +
+image:images/debugging/locOfAbstractMavenTest.png[]
+
+2. Append the command: +
+*-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=1044* +
+to the end of line 148 in the string. +
+image:images/debugging/locInAbstractMavenTest.png[] +
+image:images/debugging/locInAbstractMavenTest-command.png[]
+
+2. Start the test normally.
+
+3. Wait until you are prompted to attach in the console.
+
+4. Go to Run > Debug Configurations.
+
+5. Select "Remote Java Application."
+
+6. Select the appropriate test and make sure the correct port - in this case 1044 - and localhost are selected. +
+image:images/debugging/debug-configurations.png[]