[[building]]


===Building jPOS

 In order to build jPOS you need  link:$$http://ant.apache.org$$[Apache Ant] version 1.6.5 or higher installed. 

 In order to run jPOS a JRE 1.5+ is required. 

 As an initial sanity check, you want to run: 
----

   ant -projecthelp
  
----

 

 You should see an output like this: 
----

Buildfile: build.xml

Main targets:

 clean      clean up build and dist directories
 compile    compile all
 dist       Builds source distribution
 jar        creates jpos.jar
 javadoc    generate javadocs
 run        invoke jPOS under Ant's JVM
 singlejar  creates a single jpos.jar including all supporting jars
 srcjar     creates jpos-src.jar
 test       perform unit tests
 zip        create zip distribution
Default target: compile
  
----

 

 A typical jPOS application has several runtime directories such as the +deploy+ directory that is scanned by the Q2 application in order to start and stop its services, the +cfg+ directory used to store runtime configuration and property files, +lib+ directory containing supporting jars as well as other directories used for specific applications (such as the +webapps+ used by web-enabled applications). 

 In addition, they have an +src+ directory where the source code java files are located as well as a +test+ directory which is the place for unit tests. 

 To recap, we have: 
----

   src
   test
   deploy
   cfg
  
----

 

 jPOS build subsystem *merges* these directories off the available modules and *flattens* them inside the automatically created *build* directory. 

 If we have the files: 
----

   module/mymoduleA/src/org/jpos/MyClassA.java
   module/mymoduleA/lib/mydep1.jar
  
----

 
----

   module/mymoduleB/src/org/jpos/MyClassB.java
   module/mymoduleB/lib/mydep2.jar
  
----

 and we call +ant+ in order to build a jPOS application, as a first step ant will copy the files to the +build/src+  directory and +build/lib+ directory in order to  end up with a directory structure like this: 
----

   build/src/org/jpos/MyClassA.java
   build/src/org/jpos/MyClassB.java
   build/lib/mydep1.jar
   build/lib/mydep2.jar
  
----

 Same goes for other directories such as  +cfg+, and +webapps+. 


.Build Merge Process
image::[]


[TIP]
====

  If you want to create a local copy of jPOS' javadocs, you can
  easily issue the following command:
----

   ant javadoc
  
----


  You can also browse the javadocs online at 
  link:$$http://jpos.org/doc/javadoc/index.html$$[]
====


[[using_ide_xyz]]

=== Using jPOS from your IDE

 jPOS is IDE-agnostic. If you want to use it in your favorite IDE we recommend that you create the +jpos.jar+ using Ant once and then import it to it. 

 In order to be able to access the source code from your IDE, we recommend you to move the merged source tree in +build/src+ into a directory accesible to your IDE. 

 If you are using Eclipse, you can create jpos-src.jar by running  +ant srcjar+ in the jPOS project.  Then add the jpos-src.jar as the source attachment for the jpos.jar            Then you can browse into jPOS code whenever you want. 

[[running]]

=== Running jPOS

 Depending on how you get to use jPOS, you can consider it a Library, a Framework or an Application. 

 While using it as a library, running jPOS boils down to running your application, which in turns will use jPOS. 

 When you use it as an Application/Framework what you are actually running is *Q2*, jPOS' container. (we cover Q2 in <<q2>>. 

 Running Q2 is as simple as calling: 
----


     java -jar jpos.jar

   
----

 which produces output like this: 
----

<log realm="Q2.system" at="Fri Nov 30 09:09:10 GMT-03:00 2007.775">
  <info>
    Q2 started, deployDir=/home/jpos/svn/jpos/jpos6/build/deploy
  </info>
</log>
   
----

 

 You can run Q2 off the "build" directory (for testing purposes) but you want to move it to another destination for a production setup. 


[TIP]
====

   You may consider using the jPOS-EE SDK where jPOS becomes just
   another jPOS-EE module and so does your own application.
====


 There's a unix shell script (that you can run in Windows inside Cygwin or you can use as a sample to create your own .BAT file) called +bin/q2+ that can be used to start Q2. (it basically +cd build; java -jar jpos.jar+). 

 In addition, there's an Ant task called "run" that you can use to run Q2 under Ant's control. See +ant -projecthelp+ for details. 

