doc/GettingStartedGuide/src/050_getAndBuildCode.adoc

== Get and build the code

=== Source Code Repositories
The application is split into several modules, each one dedicated to a certain scope of functions. All source code has been made available in git repositories hosted by the Eclipse Foundation +
https://eclipse.org/org/foundation/ +
The version control system used to track all changes is Git: https://git-scm.com/

==== Manually checkout

Change to the workspace directory.
Run the following command to checkout the source code:

  git clone <repository URL>

Get the clone URLs from the https://projects.eclipse.org/projects/automotive.mdmbl/developer[Project Page]

Checkout the following repositories for the openMDM Application:

* org.eclipse.mdm

There are additional openMDM tools:

* org.eclipse.mdm.openatfx.mdf.git
* org.eclipse.mdm.mdfsorter.git


==== Checkout in Eclipse IDE

Alternatively configure eGit in your Eclipse IDE and checkout there.

* Open the Git Perspective
* Open “Clone a Git Repository ….”
* Checkout with Username / Password

The password is the Gerrit Password, look there: +
https://git.eclipse.org/r/#/settings/http-password


**After cloning the repositories, your Git perspective:**

NOTE: If these "green symbols" are not present, it means that Gerrit has not yet been configured correctly. Follow the instructions in
<<git_gerrit_config, this chapter>>.

image::images/GitPerspective.png[]

=== Importing projects to the Eclipse IDE
Import the project to your Eclipse IDE via File -> Import -> Import as existing gradle project.

If the import is not working, check if the Gradle version is compatible with the Java Version your IDE is using. +
https://docs.gradle.org/current/userguide/compatibility.html[Gradle documentation to find the compatible combinations]

Tested for Eclipse IDE 2023-06:

* IDE runs with Java 17
* install Gradle 8.1.1
* import as existing gradle project -> import options
** select "Override worspace settings"
** check and configure "Local installation directory"

=== Building the projects
Run `./gradlew clean build` in the root directory of org.eclipse.mdm.
Execute `./gradlew clean build install` also generates the jars, and the war file.


Or you build the projects in the Eclipse IDE via a Run Configuration:

image::images/RunConfig.png[]

The following projects are build:

. apicopy
. application
. businessobjects
. connector
. filerelease
. freetextindexer
. preferences
. property
. webclient

If you do not see these projects after the build in your Eclipse IDE, just import the org.eclipse.mdm project again as “existing gradle project”.

==== Building the projects without the webclient

To build the application without the webclient, pass the argument headless to the gradle script of the `org.eclipse.mdm` project. The webclient is not included to the war file.

 ./gradlew clean build -Pheadless

In your console you get the message:

****
`Configure project :nucleus
Headless build! Webclient will not be included into web archive. To build and include the webclient remove the property headless or set -Pheadless=false. +
…. +
Task :nucleus:webclient:install SKIPPED`
****


image::images/RunConfig2.png[]

If there are still java errors after importing and building, right click on the project +
-> Gradle -> Refresh Gradle Project +
For other build problems, see  section
<<known_problems, Known (setup) problems and solutions>>.

If your problem is not listed there, create a Bugzilla Bug for it:

https://bugs.eclipse.org/bugs/enter_bug.cgi?product=MDMBL

==== Building the asciidoc documentation only

For generating the documentation, UserGuide and GettingStartedGuide, as pdf and html:

 ./gradlew asciidoctor asciidoctorPdf -Pheadless

[[git_gerrit_config]]
=== Configure Git and Gerrit

For checking in code to a repository you need to configure Gerrit in the Git perspective.

Additional informations:

* Gerrit can be found at https://git.eclipse.org/r/
* There is a tutorial, it also explains how to use Gerrit with Eclipse: http://www.vogella.com/tutorials/Gerrit/article.html
* See documentation from Eclipse: https://wiki.eclipse.org/Gerrit

Prerequisites:

* Get your Gerrit Password via: https://git.eclipse.org/r/#/settings/http-password
* Configure your Gerrit settings:
https://git.eclipse.org/r/#/settings/ +
-> Watched Projects -> Add the mdmbl projects.

==== Configure repositories

Go to your Eclipse IDE -> Git Perspective:

* Expand the project
* Remotes -> origin ->  Select “Configure Push” from context menu ->  OK
* URI -> click change button
* Configure URI window:
** URI: +

    https://<eclipse_username>@git.eclipse.org/r/a/mdmbl/<projectname>
    e.g.
    https://<eclipse_username>@git.eclipse.org/r/a/mdmbl/org.eclipse.mdm

** Protocol: choose HTTPS
** Fill in username and password (the Gerrit one from the settings above)
** Check the option “Store in secure store”
* Back to the “Configure Push” Window, section “Ref mapping” -> add
** Local Branch: HEAD
** Choose remote branch:
*** for the dev branch e.g. refs/for/dev
*** for the master branch: refs/heads/master
* Try the “Dry-Run” Button to test your configuration
* Save
* “Gerrit Configuration” (right click on the remote)
** URI: same as above
** Username: same as above
** Destination branch: dev (or another)
* Finish


==== Configure Push

To push code to Gerrit you can:

. As a committer:
.. The recommenden way: +
Push code to Gerrit for reviewing (in Git repositories view: Push to Gerrit)
.. Push code directly to Gerrit without any review
(in Git repositories view: Push to upstream)

. As a non-committer: +
Push code to Gerrit for reviewing (in Git repositories view: Push to Gerrit)

==== Commits to Gerrit

* Add Signed-Off-By when you commit to sign off the commit
* In the Eclipse IDE: +
open the git staging perspective, open the window "Commit message" and next to the label "Commit Message" there are 3 buttons. the middle button is the "Add signed-off-by" button. Click it.