<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                         "http://docbook.org/xml/4.4/docbookx.dtd">
<sect1>
    <title>Getting Started with RCE development</title>
    <para>This section covers setting up a development environment for running, modifying and
        extending RCE on your local machine.</para>
    <sect2>
        <title>Preparing Eclipse</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para>Make sure you have a <ulink
                            url="http://www.oracle.com/technetwork/java/javase/downloads/index.html"
                            >Java Development Kit</ulink>, Version 8u161 or higher, installed on
                        your system.<note>
                            <para>If you are installing a JDK on a centrally administered computer
                                that already has Java installed, it is usually a good idea to
                                    <emphasis>uncheck</emphasis> the "Install public JRE" option
                                during installation.</para>
                        </note></para>
                    <para>Currently, Oracle JDK 8.x is the reference development platform. In the
                        near future, however, this will most likely be replaced by OpenJDK on both
                        Windows and Linux to simplify licensing issues. OpenJDK has already been
                        successfully tested in version 8 and 11, on Windows and Linux, for
                        development and building. Note that automated JUnit test execution as part
                        of the build process is currently only possible with 8.x versions of the
                        JDK; this will be extended to JDK 11 soon.</para>
                </listitem>
                <listitem>
                    <para>Download and run "Eclipse for RCP/RAP Developers", Version "Photon
                        (4.8.x)" or later from <ulink url="https://www.eclipse.org/downloads/"
                            >https://www.eclipse.org/downloads/</ulink>. Using the latest Eclipse
                        release instead is usually fine; however, there may be slight differences
                        between this guide and that version's UI.</para>
                </listitem>
                <listitem>
                    <para>Adapt your eclipse.ini file (see <ulink
                            url="http://wiki.eclipse.org/Eclipse.ini"
                            >http://wiki.eclipse.org/Eclipse.ini</ulink> for details):<itemizedlist>
                            <listitem>
                                <para>Set the proper path to your JDK installation (the
                                        <code>-vm</code> parameter; e.g. <code>&lt;your
                                        path>/jdk8/bin</code> immediately below the <code>-vm</code>
                                    line).</para>
                            </listitem>
                            <listitem>
                                <para>Change the maximum heap size to at least 2 GiB (adapt the
                                        <code>-Xmx</code> line somewhere below <code>-vmargs</code>,
                                    e.g. to <code>-Xmx2048m</code>, or add it if it does not exist
                                    yet)</para>
                            </listitem>
                        </itemizedlist></para>
                </listitem>
                <listitem>
                	<para>
                		In the eclipse preferences (avaible from "Window"-> "Preferences"), open the page 
                		"Plugin-Development" -> "DS Annotations" and check the box for "Generate descriptors
                		for annotated sources." Set the descriptor directory to "OSGI-INF/generated".
                	</para>
                </listitem>
                <listitem>
                    <para>Optionally, install these plugins (for example using "Help > Eclipse
                        Marketplace"): </para>
                    <itemizedlist>
                        <listitem>
                            <para><ulink
                                    url="https://code.google.com/a/eclipselabs.org/p/workspacemechanic/"
                                    >Workspace Mechanic</ulink> - used to apply common workspace
                                settings. Not strictly required, but convenient.</para>
                        </listitem>
                        <listitem>
                            <para><ulink url="http://eclipse-cs.sourceforge.net/">Checkstyle-CS
                                </ulink> - Eclipse integration for Checkstyle (version 6.19 or
                                above; see the note in section "Configuring CheckStyle" ). Not
                                required for local development, but mandatory before committing
                                changes into the central code base.</para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
    <sect2>
        <title>Importing and building RCE</title>
        <para>
            <itemizedlist>
                <listitem>
                    <para>If you already have other projects in your Eclipse workspace, it is
                        recommended to create a new workspace for RCE. There are some necessary
                        global settings that may interfere with the other projects (e.g. the
                        so-called "target platform").</para>
                </listitem>
                <listitem>
                    <para>Disable "Project > Build Automatically" in the main menu to speed up the
                        next steps.</para>
                </listitem>
                <listitem>
                    <para>There are currently three ways to properly import the complete RCE source
                        code: from the SVN repository, from provided zip files, or from GitHub. At
                        the moment, only the SVN approach provides access to the current development
                        tree; for the time being, the zip files and the GitHub repository are only
                        updated on release.</para>
                </listitem>
                <listitem>
                    <para>Option 1 - Importing from the RCE SVN repository, if you have access to it
                        (as the repository is currently hosted internally at DLR):</para>
                    <para>
                        <itemizedlist>
                            <listitem>
                                <para>Install <ulink url="http://subclipse.tigris.org/"
                                        >Subclipse</ulink> (or alternatively <ulink
                                        url="http://www.polarion.com/products/svn/subversive.php"
                                        >Subversive</ulink>) if you don't already have an Eclipse
                                    SVN plugin installed. Note that when using Subclipse, you may
                                    have to switch to the "SvnKit" SVN interface in the "Team > SVN"
                                    preferences; this is normal.</para>
                            </listitem>
                            <listitem>
                                <para>Open the "SVN Repositories" view (Window > Show View > Other >
                                    SVN). </para>
                            </listitem>
                            <listitem>
                                <para>Add
                                        <code>https://svn.sistec.dlr.de/svn/rce/new/rce/trunk</code>
                                    as a new SVN repository location.</para>
                            </listitem>
                            <listitem>
                                <para>Expand the location entry and select all projects (the entries
                                    starting with "de.rcenvironment") inside of it. </para>
                            </listitem>
                            <listitem>
                                <para>Right-click the selected projects, select "Checkout" and
                                    confirm if necessary. You should now see a long list of projects
                                    in the "Package Explorer" on the left.<note>
                                        <para>If the checkout was performed correctly, there should
                                            be a small "M" (for "Maven") on most projects' icons,
                                            and also a small "J" (for "Java") on most of
                                            them.</para>
                                    </note></para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
                <listitem>
                    <para>Option 2 - Importing from the zip files provided with each release:<itemizedlist>
                            <listitem>
                                <para>Browse to the "source" sub-folder of a release's download
                                    location, for example
                                        <uri>https://software.dlr.de/updates/rce/8.x/products/standard/releases/8.1.0/source/</uri>
                                    for the 8.1.0 release. Download both zip files, "source" and
                                    "additions"; the latter contains binary artifacts like the
                                    Dakota and TiGLViewer executables.</para>
                            </listitem>
                            <listitem>
                                <para>Extract both archives into the <emphasis>same</emphasis>
                                    target directory. You should see a list of more than 200
                                    sub-folders, all except one beginning with
                                    "de.rcenvironment".</para>
                            </listitem>
                            <listitem>
                                <para>In Eclipse, select "File > Import > General > Existing
                                    Projects into Workspace" and choose the directory that you
                                    unpacked the archives into. You should see a long list of
                                    projects, once again, all except one beginning with
                                    "de.rcenvironment". Select all projects confirm the import.<note>
                                        <para>Make sure not to change the "Search for nested
                                            projects" option in the import dialog; it must
                                                <emphasis>not</emphasis> be selected/checked.</para>
                                    </note></para>
                            </listitem>
                        </itemizedlist></para>
                </listitem>
                <listitem>
                    <para>Option 3 - Importing from GitHub:</para>
                    <itemizedlist>
                        <listitem>
                            <para>For successfully importing the RCE project, you need a Git client
                                with LFS support.</para>
                        </listitem>
                        <listitem>
                            <para>Clone <code>https://github.com/rcenvironment/rce</code> into a
                                directory of your choice.<note>
                                    <para>The clone settings of certain Git clients (e.g.
                                        TortoiseGit), have an "LFS" option. Make sure that this
                                        option is enabled before you clone.</para>
                                </note></para>
                        </listitem>
                        <listitem>
                            <para>Check out the <code>master</code> branch; by default, this points
                                to the source code of the latest release.</para>
                        </listitem>
                        <listitem>
                            <para>In Eclipse, select "File > Import > General > Existing Projects
                                into Workspace" and choose the directory that you unpacked the
                                archives into. You should see a long list of projects, once again,
                                all except one beginning with "de.rcenvironment". Select all
                                projects confirm the import.<note>
                                    <para>Make sure not to change the "Search for nested projects"
                                        option in the import dialog; it must
                                            <emphasis>not</emphasis> be selected/checked.</para>
                                </note></para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>After you have successfully imported the RCE projects using one of the
                        above methods, the next step is to set the RCE target platform in your
                        workspace. A target platform provides external artifacts like the Eclipse
                        RCP framework and various libraries. To get started with RCE development,
                        the easiest way is to use a precompiled target platform. For convenience,
                        there is a Eclipse .target file inside the code base that always points at
                        an appropriate precompiled target platform release. Follow these steps to
                        apply it:</para>
                    <para>
                        <itemizedlist>
                            <listitem>
                                <para>In the Project Explorer, navigate to the
                                        <code>de.rcenvironment/eclipse/tp/remote</code>
                                    folder.</para>
                            </listitem>
                            <listitem>
                                <para>Open the <code>default_release_or_snapshot.target</code> file
                                    by double-clicking it.</para>
                            </listitem>
                            <listitem>
                                <para>Select the "Locations" list entry starting with
                                        "<code>https://software.dlr.de/</code>" and click "Update".
                                    After a while, the list entry's description should end with
                                    something similar to "242 plugins available" (the exact number
                                    may vary). Save the file if necessary.</para>
                            </listitem>
                            <listitem>
                                <para>Click "Set as target platform" in the top right corner. You
                                    can close the .target file after this.</para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
                <listitem>
                    <para>If you previously changed the global Java compiler compliance level to 1.7
                        for previous RCE releases, it is recommended to revert this setting to
                        default, or explicitly set it to 1.8. This setting can be accessed by
                        opening "Window > Preferences" from the menu, and then navigating to the
                        "Java > Compiler" tab. If you never actively changed this setting, no action
                        is required.</para>
                </listitem>
                <listitem>
                    <para>Enable "Project > Build Automatically". Eclipse will start building all
                        projects against the new target platform, which provides all required
                        libraries and OSGi bundles.</para>
                </listitem>
                <listitem>
                    <para>At this point, most projects will have a red error marker. To fix this,
                        open the "Problems" view ("Window > Show View > Problems"). You should see a
                        lot of "Plugin execution not covered by lifecycle configuration" entries.
                        Right-click one of them, select "Quick Fix" from the context menu, select
                        "Discover new m2e connectors" and click "Finish". Eclipse should present one
                        or more installation options with "Tycho" in their name. Confirm their
                        installation and restart eclipse.<note>
                            <para>You only need to do this once per Eclipse installation.</para>
                        </note></para>
                </listitem>
                <listitem>
                    <para>After this, all RCE bundles should compile without errors (with the
                        exceptions noted below), and you are ready to start developing. If this is
                        not the case, try running "Project > Clean > Clean all projects" from the
                        main menu.<note>
                            <para>On Linux platforms, there will be compilation errors in some
                                Windows-only Excel and TiGLViewer bundles (5 and 3 projects,
                                respectively). We don't have an elegant solution for this problem
                                yet. You can simply close these projects to get rid of the errors,
                                as they won't be loaded at runtime anyway.</para>
                        </note></para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>
    <sect2>
        <title>Running RCE from Eclipse</title>
        <para>Before proceeding to the more detailled settings, try running RCE from Eclipse to
            verify your setup.</para>
        <itemizedlist>
            <listitem>
                <para>There are several pre-defined launch configurations for RCE. To find them,
                    navigate to <code>de.rcenvironment/eclipse/launch</code> in the "Project
                    Explorer" on the left.</para>
            </listitem>
            <listitem>
                <para>A good starting point is the "default" configuration. Expand the "default"
                    sub-folder, right-click the "rce.default.launch" file and choose "Run As >
                    rce.default.launch" from the context menu.</para>
            </listitem>
            <listitem>
                <para>RCE should now start and prompt for an RCE workspace location. Confirm the
                    default value or choose another empty folder.</para>
            </listitem>
        </itemizedlist>
    </sect2>
    <sect2>
        <title>Configuring Workspace Mechanic (optional)</title>
        <note>
            <para>The Workspace Mechanic project in its original form is not being maintained
                anymore, and the original project site is gone. However, it has been forked and is
                being continued by a new maintainer at <ulink
                    url="https://github.com/alfsch/workspacemechanic/">this location</ulink>. While
                this is not an "official" successor, it seems to be the de-facto location of this
                project now.</para>
        </note>
        <para>Workspace Mechanic (which can be installed via Eclipse Marketplace from <ulink
                url="https://marketplace.eclipse.org/content/workspace-mechanic">this
                location</ulink>) is an Eclipse plugin that automates common settings in local
            workspaces. For RCE, the most important settings are the Java code formatting rules and
            templates. Other settings are provided for convenience, like disabling the console
            output limit, or showing line numbers in the editor.</para>
        <para>Configuring Workspace Mechanic consists of copying a set of "rule" files to a location
            where the plugin can find them. There are two options for this:<itemizedlist>
                <listitem>
                    <para>If you want to apply the rules to all Eclipse installations on your
                        machine, use the <code>.eclipse/mechanic</code> subfolder in your home
                        directory; by default, this is <code os="windows"
                                >C:\Users\<replaceable>&lt;user
                            id></replaceable>\.eclipse\mechanic</code><code os="linux"
                                >/home/<replaceable>&lt;user
                            id></replaceable>/.eclipse/mechanic</code>.</para>
                </listitem>
                <listitem>
                    <para>To apply the rules to a single Eclipse installation only, use <code
                            os="windows"><replaceable>&lt;eclipse installation
                            folder></replaceable>\configuration\com.google.eclipse.mechanic\mechanic</code><code
                            language="" os="linux"><replaceable>&lt;eclipse installation
                                folder></replaceable>/configuration/com.google.eclipse.mechanic/mechanic</code>.
                    </para>
                </listitem>
            </itemizedlist>Using your system's file browser, navigate to the folder of your choice.
            Using any SVN tool, check out
                <code>https://svn.sistec.dlr.de/svn/rce/new/meta/eclipse/mechanic</code> into a
            sub-folder called "<code>checkout</code>" within it. (Note that the actual name of the
            sub-folder is not relevant; adapt if you like.) This sub-folder now contains common
            rules on its top level, and optional or experimental rules in sub-folders. Copy all
            common rules to the parent folder (the one you started in), and add any optional rules
            that you want to apply as well. (TODO add and describe batch/shell files for this.)<note>
                <para>These rule files will most likely be integrated into the main project at some
                    point, making this extra checkout step unnecessary. Please note that these rule
                    files are currently not available as part of the <ulink
                        url="https://github.com/rcenvironment/rce">GitHub source code mirror</ulink>
                    or the released source zip files either, which makes them inaccessible unless
                    you have access to the internal SVN server.</para>
            </note></para>
        <para>The next time you open a workspace, Workspace Mechanic should pick up these rule files
            and show a notice asking if it should apply them. See the plugin's <ulink
                url="https://github.com/alfsch/workspacemechanic/">web site</ulink> for further
            information.</para>
    </sect2>
    <sect2>
        <title>Configuring Code Formatting and CheckStyle Rules (optional)</title>
        <para>If you only plan to try out or modify RCE locally, you can safely skip this section.
            If you plan to commit your changes to the central code base, however, you need these
            settings to get your code accepted into the repository. Code that does not match the
            style guidelines will be refused on commit. The Checkstyle-CS plugin simplifies
            development by highlighting violations that need to be fixed.</para>
        <para>To configure Checkstyle-CS for RCE:</para>
        <itemizedlist>
            <listitem>
                <para>Open the Checkstyle preferences (Window > Preferences > Checkstyle). </para>
            </listitem>
            <listitem>
                <para>Click "New" on the right side. Enter "RCE" as the name of the configuration.
                </para>
            </listitem>
            <listitem>
                <para>Choose "Project relative configuration", click "Browse" and choose
                        <code>de.rcenvironment/checkstyle/checks.xml</code>. </para>
            </listitem>
            <listitem>
                <para>Click "Ok" in the main dialog. The list of configurations should now have
                    three entries; select "RCE" and click "Set as Default" on the right side.
                </para>
            </listitem>
            <listitem>
                <para>Close the preferences with "Ok" and confirm the rebuild. </para>
            </listitem>
        </itemizedlist>
        <para>
        <note>
            <para>We are currently using version 6.19 of the Eclipse CheckStyle plugin within the
                    development team. Using a newer version (e.g. 8.0) works as well, but you may
                    see error markers for constructs that do not actually violate the RCE code
                    guidelines. Versions > 8.0 do not work with current code guidelines. We will
                    most likely adapt/migrate the CheckStyle settings in the near future.</para>
        </note>
        </para>
        <para> To configure the Eclipse source code formatter:<itemizedlist>
                <listitem>
                    <para>Open the code formatter preferences (Window > Preferences > Java > Code
                        Style > Formatter). </para>
                </listitem>
                <listitem>
                    <para>Click "Import", browse to your <code>de.rcenvironment/eclipse/</code>
                        checkout folder and choose the "<code>eclipse-formatter.xml</code>"
                        file.</para>
                </listitem>
                <listitem>
                    <para>You should now see "RCE" as the "Active Profile".</para>
                </listitem>
                <listitem>
                    <para>Click "Apply and Close" to activate the settings. </para>
                </listitem>
            </itemizedlist>
            <note>
                <para>There are rare cases where these code formatter settings lead to source files
                    that are not being accepted by our CheckStyle rules. These inconsistencies are
                    being collected and tracked in issue #0005898, and will be fixed/addressed in a
                    future update.</para>
            </note>
        </para>
    </sect2>
    <sect2>
        <title>Building a standalone RCE version from Eclipse</title>
        <para>You can also build a standalone version of RCE from Eclipse using Maven.</para>
        <itemizedlist>
            <listitem>
                <para>There are several pre-defined build configurations for RCE. To find them,
                    navigate to <code>de.rcenvironment/eclipse/build</code> in the "Project
                    Explorer" on the left.</para>
            </listitem>
            <listitem>
                <para>To run a .launch file, right-click on it and choose the single entry in the
                    "Run As" submenu of the context menu that appears.</para>
            </listitem>
            <listitem>
                <para>Building a standalone RCE installation (which is called a "product" in Eclipse
                    RCP terms) generally consists of two steps: Providing a so-called "platform
                    repository", and then building the actual product on top of it. There are two
                    possible approaches for this:<itemizedlist>
                        <listitem>
                            <para>Using the .launch files in the "<code>using default remote
                                    repository builds</code>" sub-folder, it is possible to avoid
                                building your own platform repository, and fetch a pre-built one
                                from the main repository servers (currently hosted at DLR) instead.
                                One reason for this can be be to ensure that you are building
                                against the exact same platform repository as a certain RCE release.
                                Another reason is to simplify your local development setup if you
                                have no reason to customize the target platform setup (e.g. by
                                adding libraries).</para>
                        </listitem>
                        <listitem>
                            <para>The most flexible way to build RCE from source is to compile a
                                local platform repository yourself. This is simply done by
                                navigaring to the "<code>de.rcenvironment.platform/eclipse</code>
                                folder (from the root of your workspace) and executing the single
                                .launch file that is located there. On the first run, the build
                                process may download quite a few resources from Maven Central;
                                subsequent runs should be fairly quick. Once the build has finished
                                (there should be a "SUCCESS" message near the bottom of the console
                                output), you can build the main product using the .launch files in
                                the "<code>using local repository builds</code>" sub-folder of the
                                previously mentioned location.</para>
                        </listitem>
                    </itemizedlist></para>
            </listitem>
            <listitem>
                <para>Regardless of whether you use a pre-build platform repository or compile one
                    locally, running the "<code>RCE - build default product (snapshot, using
                        &lt;...>)</code> .launch file is the best way to produce a standard local
                    product build. The other .launch files are intended for more specific use
                    cases.</para>
            </listitem>
            <listitem>
                <para>The main product build takes several minutes to complete. Once it has
                    finished, you will find the .zip files containing the final product in the
                    folder
                        <code>de.rcenvironment/target/de.rcenvironment.modules.repository.mainProduct/products</code>
                    (You may have to refresh the de.rcenvironment project in the Project Explorer to
                    see it.)</para>
            </listitem>
        </itemizedlist>
    </sect2>
    <sect2>
        <title>Building from the command line</title>
        <para>Building RCE completely from the command line is somewhat complicated as it is a
            multi-step process in which later steps must reference the output artifacts of previous
            steps. To simplify this, the command-line build will be further encapsulated by
            front-end scripts, which will then be documented here. In the meantime, please use the
            steps described above to trigger the build process from Eclipse.</para>
        <para>Note that both the Eclipse-based and the command-line build trigger the same Maven
            steps in the background. Because of this, the build triggered from Eclipse produces the
            exact same artifacts as a command-line build (which is used in Continuous Integration
            and for releases).<note>
                <para>TODO document the new command-line build when ready</para>
            </note></para>
    </sect2>
</sect1>
