[[building]]
== Building jPOS

jPOS uses http://www.gradle.org/[Gradle] as its build system.
For a quick build, you don't even need to install Gradle, you
can use the handy +gradlew+ (or +gradlew.bat+ if you're on Windows)
Gradle 'wrapper' that automatically downloads Gradle for you, but
for daily development, it's a good idea to install it locally.

[NOTE]
======
Whenever we mention the +gradle+ command in this guide, you can
either use your locally installed Gradle, or the +gradlew+ wrapper
scripts mentioned above.
======

[TIP]
======
Gradle has the ability to run in background, dramatically reducing
the load time. In order to enable that feature, you can use its
+--daemon+ parameter or
------------
export GRADLE_OPTS=-Dorg.gradle.daemon=true
------------
======

=== Available tasks

Running +gradle tasks+ provides a list of available tasks.

Most of them are standard in the Gradle build system and have self-explanatory 
names (i.e. +jar+ to build the jPOS jar, +javadoc+ to build the javadoc 
documentation). A few deserve further explanation, though:

* *+installApp+* is a handy task defined in the +jpos+ module that can
  be used to create a runtime environment inside the +build/installs+
  directory. That runtime envirnoment copies all the scripts coming from
  the +src/dist+ directory and it's ready to execute the jPOS system 
  using the +bin/q2+ (or +bin\q2.bat+) scripts. The +installApp+ task
  is similar to running the +dist+ task to create a +tar.gz+ tarball
  and then extracting that tarball into a local directory, ready to run.

* *+version+* can be used to build jPOS and run it to query its own version.

[NOTE]
.Note about releases
======
jPOS stable releases (non SNAPSHOTS) are signed and published to Maven Central.
If you are trying to build a stable release, you'd have to hack +build.gradle+
to trick the +isSnapshot+ variable to be true, otherwise the build will fail
because you don't have the PGP private keys required to sign a build.

If you're making some changes to jPOS off a stable release, you should
change the version number to avoid confusion.

But remember, you don't have to build jPOS in order to use it, just add
it to your 'pom' as a dependency.

======

[TIP]
.The 'clean' task is your friend
=====
Out of all the available tasks, there's one that will keep you out
of trouble: *clean*. While Gradle is very smart when it comes to figuring
out which dependencies have been modified and need to be rebuilt, there's
nothing like the extra confidence that a good old +clean+ gives. When
in doubt, +gradle clean+.
=====

