[[downloadAndRunTheExamples]]
= Download and run the examples
:imagesdir: ../..


[[getTheReleaseZipAndRunTheExamples]]
== Get the release ZIP and run the examples

To try it now:

. Download a release zip of OptaPlanner from https://www.optaplanner.org[the OptaPlanner website] and unzip it.
. Open the directory [path]_examples_ and run the script.
+
Linux or Mac:
+
[source,sh,options="nowrap"]
----
$ cd examples
$ ./runExamples.sh
----
+
Windows:
+
[source,sh,options="nowrap"]
----
$ cd examples
$ runExamples.bat
----

image::PlannerIntroduction/DownloadAndRunTheExamples/distributionZip.png[align="center"]

The Examples GUI application will open.
Pick an example to try it out:

image::PlannerIntroduction/DownloadAndRunTheExamples/plannerExamplesAppScreenshot.png[align="center"]

[NOTE]
====
OptaPlanner itself has no GUI dependencies.
It runs just as well on a server or a mobile JVM as it does on the desktop.
====


[[runTheExamplesInAnIDE]]
== Run the examples in an IDE (IntelliJ, Eclipse, VSCode)

To run the examples in your favorite IDE:

* In IntelliJ IDEA, VSCode or a non-vanilla Eclipse:
+
. Open the file [path]_examples/sources/pom.xml_ as a new project, the maven integration will take care of the rest.
. Run the examples from the project.

* In a vanilla Eclipse (which lacks the M2Eclipse plugin):
. Open a new project for the directory [path]_examples/sources_ .
. Add all the jars to the classpath from the directory [path]_binaries_ and the directory [path]_examples/binaries_ , except for the file [path]_examples/binaries/optaplanner-examples-*.jar_ .
. Add the Java source directory [path]_src/main/java_ and the Java resources directory [path]_src/main/resources_ .
. Create a run configuration:
** Main class: `org.optaplanner.examples.app.OptaPlannerExamplesApp`
** VM parameters (optional): `-Xmx512M -server`
.. To run a specific example directly and skip the example selection window, run its `App` class (for example ``CloudBalancingApp``) instead of ``OptaPlannerExamplesApp``.
. Run that run configuration.


[[useWithMavenGradleEtc]]
== Use OptaPlanner with Maven, Gradle, or ANT

The OptaPlanner jars are available in http://search.maven.org/#search|ga|1|org.optaplanner[the central maven repository]
(and the snapshots in pass:macros[https://repository.jboss.org/nexus/index.html#nexus-search;gav~org.optaplanner~~~~[the JBoss maven repository\]]).

If you use Maven, add a dependency to `optaplanner-core` in your `pom.xml`:

[source,xml,options="nowrap"]
----
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
      <version>...</version>
    </dependency>
----

Or better yet, import the `optaplanner-bom` in `dependencyManagement` to avoid duplicating version numbers
when adding other optaplanner dependencies later on:

[source,xml,options="nowrap"]
----
<project>
  ...
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.optaplanner</groupId>
        <artifactId>optaplanner-bom</artifactId>
        <type>pom</type>
        <version>...</version>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
    </dependency>
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-persistence-jpa</artifactId>
    </dependency>
    ...
  </dependencies>
</project>
----

If you use Gradle, add a dependency to `optaplanner-core` in your `build.gradle`:

[source,groovy,options="nowrap"]
----
dependencies {
  implementation 'org.optaplanner:optaplanner-core:...'
}
----

If you're still using ANT, copy all the jars from the download zip's `binaries` directory in your classpath.

[NOTE]
====
The download zip's `binaries` directory contains far more jars then `optaplanner-core` actually uses.
It also contains the jars used by other modules, such as ``optaplanner-benchmark``.

Check the maven repository `pom.xml` files to determine the minimal dependency set of `optaplanner-core` etc.
====


[[buildFromSource]]
== Build OptaPlanner from source


*Prerequisites*

* Set up https://git-scm.com/[Git].
* Authenticate on GitHub using either HTTPS or SSH.
** See https://help.github.com/articles/set-up-git/[GitHub] for more information about setting up and authenticating Git.
* Set up http://maven.apache.org/[Maven].

Build and run the examples from source.

. Clone `optaplanner` from GitHub (or alternatively, download https://github.com/kiegroup/optaplanner/zipball/main[the zipball]):
+
[source,sh,options="nowrap"]
----
$ git clone https://github.com/kiegroup/optaplanner.git
...
----

. Build it with Maven:
+
[source,sh,options="nowrap"]
----
$ cd optaplanner
$ mvn clean install -DskipTests
...
----
+
[NOTE]
====
The first time, Maven might take a long time, because it needs to download jars.
====

. Run the examples:
+
[source,sh,options="nowrap"]
----
$ cd optaplanner-examples
$ mvn exec:java
...
----

. Edit the sources in your favorite IDE.
