<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0">
    <title>Build Process FAQ / Tips and Tricks</title>
    <para>This section gives answers and hints to common build issues.</para>
    <qandaset defaultlabel="qanda">
        <qandaentry>
            <question>
                <para>After running a local product build, where do I find the generated product
                    zips and files?</para>
            </question>
            <answer>
                <para>The generated files are located in
                        <code>de.rcenvironment/target/de.rcenvironment.modules.repository.mainProduct/products</code>
                    .</para>
            </answer>
        </qandaentry>
            <qandaentry>
                <question>
                    <para>When running a product build, how can I change the server URL where p2
                    artifacts (e.g. the "target platform") are loaded from?</para>
                </question>
                <answer>
                    <para>To support typical build use cases, p2 server URLs are normally assembled
                    from two parts: a common URL "root" part, and a repository-specific URL segment.
                    The default values for these are defined in the build pre-processor script at
                        <code>/de.rcenvironment/maven/preprocessor/scripts/RCEBuildPreprocessor.groovy</code> .<note>
                        <para>For example, the default "target platform" repository URL for the
                            8.1.0 release is the concatenation of the default URL "root" part
                                <code>https://software.dlr.de/updates/rce/8.x/repositories/</code>
                            and the specific repository segment <code>releases/8.1.0</code>. The
                            same pattern using the same "root" URL, but different specific segments
                            would also be used for other repositories. However, as of 8.1.0, the
                            "platform" repository is the only one used during the default build. The
                            only other valid option is "intermediate", which is only used in special
                            builds.</para>
                    </note></para>
                    <para>There are three ways to change these URLs, depending on the build use case.<itemizedlist>
                        <listitem>
                            <para>If you want to switch to a different server that provides all of
                                the required repositories, you can simply override the URL "root"
                                part, and all p2 repositories will be loaded from there. This can be
                                done by setting the Maven property
                                    <code>rce.maven.repositories.default.rootUrl</code>.</para>
                        </listitem>
                        <listitem>
                            <para>To override the URL root path of a single repository, set the
                                Maven property
                                        <code>rce.maven.repositories.<replaceable>&lt;id></replaceable>.rootUrl</code>,
                                with <code><replaceable>&lt;id></replaceable></code> being
                                "platform" or "intermediate".</para>
                        </listitem>
                        <listitem>
                            <para>Alternatively, you can also override the complete URL of a
                                repository by setting the Maven property
                                        <code>rce.maven.repositories.<replaceable>&lt;id></replaceable>.url</code>
                                with the same ids as above.</para>
                        </listitem>
                    </itemizedlist></para>
                <para>All of these settings can be combined, with more specific settings overriding
                    the more general ones (e.g. a custom repository URL overrides a custom root
                    URL).</para>
                <para>Note that these approaches are only intended for adapting the build to your
                    build environment, or for local building and testing. To change the repository
                    paths permanently (e.g. when preparing a new release), edit the default values
                    in the build pre-processor script at
                        <code>/de.rcenvironment/maven/preprocessor/scripts/RCEBuildPreprocessor.groovy</code>.
                    Note that there are two sets of specific repository URL segments which are used
                    for snapshot and RC/release builds, respectively.</para>
                </answer>
            </qandaentry>
        <qandaentry>
            <question>
                <para>I created a new snapshot / RC / release build of the "platform" repository.
                    What do I have to edit to make the product build use it?</para>
            </question>
            <answer>
                <para>The default repository references are configured in the
                        <code>defaultRepositoryUrlSuffixes</code> map within the build pre-processor
                    script at
                        <code>/de.rcenvironment/maven/preprocessor/scripts/RCEBuildPreprocessor.groovy</code>.
                    Snapshot and RC/release references are configured separately to support
                    developing against snapshot builds. These references are the repository-specific
                    URL suffixes; see the question above for examples.</para>
                <para>Note that when preparing for a new major release, you may also have to adapt
                    the "root" URL part (e.g. changing it from
                        <code>&lt;...>/rce/8.x/repositories/</code> to
                        <code>&lt;...>/rce/9.x/repositories/</code>), and have to deploy the
                    referenced repository builds to that new location.</para>
            </answer>
        </qandaentry>
        <qandaentry>
            <question>
                <para>A package import in Eclipse fails with the error message "The import xxx
                    cannot be resolved" although the imports and exports are set correctly in the
                    respective Manifest files. What else can I try to solve the problem?</para>
            </question>
            <answer>
                <para>Go to the Project Explorer and select the affected bundle. Open the context
                    menu and select "Plug-in Tools > Update Classpath...". Select all affected
                    bundles (possibly including the Fragment-Host) from the dialog list provided and
                    finish.</para>
            </answer>
        </qandaentry>
        </qandaset>
</section>
