<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="debugging">
	<title>Tips, Tricks, and Good Practices</title>
	<para> Here, we document tips, tricks, and good practices for debugging RCE. Since RCE is written
		in Java, many of the standard good practices for debugging Java code apply to debugging RCE
		as well, such as getting comfortable with the debugger integrated in Eclipse. As there are
		good general-purpose tutorials out there, our aim in this section is not to repeat already
		existing general advice. Instead, we discuss tools and techniques that experience shows are
		not as well known.</para>
	<section>
		<title>Finding Resource Leaks in the UI using S-Leak</title>
		<para>Recall that SWT resources (such as <code>Composite</code>, <code>Button</code>, or
				<code>Label</code>) are not cleaned up completely by the garbage collector. Instead,
			they must be manually cleaned up by the developer via their <code>dispose</code> method
			(cf. <ulink url="https://www.eclipse.org/articles/swt-design-2/swt-design-2.html">this
				article</ulink> for more information on managing SWT objects). Since this behavior
			differs from virtually all other Java objects, it is easy for developers to overlook
			this cleanup. This leads to "leaked" SWT resources, i.e., to resources that are created,
			but never disposed of afterwards.</para>
		<para>S-Leak is a tool that aids in finding leaked SWT resources. It allows developers to
			take snapshots of the currently allocated SWT resources and to create the diff between
			two such snapshots. Thus, the developer can determine which resources have been
			allocated during certain user actions and compare these allocations with their
			expectations.</para>
		<para>In order to use S-Leak, you have to start RCE with the system property
				<code>rce.debug.sleak</code> defined. When starting RCE via Eclipse, you can do so
			by editing your preferred run configuration (Run <code>-></code> Run Configurations
				<code>-></code> Arguments <code>-></code> VM Arguments <code>-></code> Add
				<code>-Drce.debug.sleak</code>). When starting RCE as a standalone application, edit
			the file <code>rce.ini</code> to include the line <code>-Drce.debug.sleak</code> at some
			point after <code>-vmargs</code>. The class
				<code>de.rcenvironment.core.start.gui.GUIInstanceRunner</code> interprets this
			system property and starts S-Leak during startup of RCE.</para>
	</section>
	<section>
		<title>Profiling RCE using VisualVM</title>
	</section>
	<section>
	<title>Debugging GUI layouts using SWT Spy</title>
		<para>When developing GUIs using Eclipse SWT, one often wants to have more information about how
			the GUI of the running software is composed and what properties are set. One of the
			tools giving such an overview is SWT spy (<ulink
				url="https://eclipsesource.com/de/blogs/2018/01/10/swt-spy-debugging-swt-layouts/"
				>https://eclipsesource.com/de/blogs/2018/01/10/swt-spy-debugging-swt-layouts/</ulink>).
			In order to use this tool to debug the GUI of RCE started from Eclipse, follow these
			steps:</para>
		<para>
			<orderedlist>
				<listitem>
					<para>Add the plug-in "SWT Tools" available from <ulink
							url="https://download.eclipse.org/eclipse/updates/4.7/"
							>https://download.eclipse.org/eclipse/updates/4.7/</ulink> to the target
						platform
							(<code>de.rcenvironment/eclipse/tp/remote/default_release_or_snapshot.target</code>
						<code>-></code> Add <code>-></code> Software Site <code>-></code> Work with
							<ulink url="https://download.eclipse.org/eclipse/updates/4.7/"
							>https://download.eclipse.org/eclipse/updates/4.7/</ulink>
						<code>-></code> Check the plug-in "SWT Tools", located in the folder
						"Eclipse Tests, Tools, Examples and Extras" <code>-></code> Finish). We show
						the wizard for adding this plug-in below.</para>
				</listitem>
				<listitem>
					<para>Reload the target platform.</para>
				</listitem>
				<listitem>
					<para>Add the newly available feature <code>org.eclipse.swt.tools.feature</code> to the product
						definition of RCE
							(<code>de.rcenvironment/maven/modules/repository.mainProduct/rce_default.product</code>
						<code>-></code> Contents <code>-></code> Add).</para>
				</listitem>
			</orderedlist>
		</para>
		<para><mediaobject xreflabel="figure:add_swt_tools"><imageobject>
			<imagedata fileref="images/add_swt_tools.png" format="PNG"/>
		</imageobject><caption>The wizard for adding new plug-ins to the target platform. Select the plug-in "SWT Tools"
					in order to add SWT spy to RCE.</caption></mediaobject> </para>
		<para>After rebuilding and restarting RCE from Eclipse, you should now have the view "SWT Spy"
			available in RCE. When clicking the spy-icon in its upper menu bar, this view will show
			information about the SWT construct that the cursor is currently pointing at. Using the
			shortcut <code>Ctrl+Alt+Shift+.</code> you can toggle the SWT spy to keep the
			information about the currently selected element in the view of the SWT spy to allow for
			further investigation about the information.</para>
	</section>
</section>
