The settings above start Tomcat in debug mode. This means that you can debug the Java and Scala code from IntelliJ. Select the "Tomcat" configuration in IntelliJ, then "Run" → "Debug". IntelliJ opens the debugging window and connects to Tomcat. You can then set breakpoints and do the usual things one does with a debugger!
If you modify Java or Scala files, you need to recompile. You do this from the command-line with sbt, which can let run the compile task incrementally with:
TODO: document making changes to resources or assets.
The following runs only tests within FormBuilderFunctionsTest which contain the string my test and show full stack traces in case of exception:
testOnly *FormBuilderFunctionsTest -- -z "my test" -oF
About building Orbeon Forms PE
Orbeon does not provide public instructions or code to build Orbeon Forms PE, which is a commercial, supported build of the product. If you are a PE customer, contact Orbeon at [email protected]
The idea is just that we want to ensure that something called "Orbeon Forms PE" in fact comes from Orbeon.
With sbt from the command-line
As of 2016-06-02:
To compile the Scala and Java files from the command-line the first time, run:
To incrementally compile Scala and Java files during further development, run:
~copyJarToExplodedWar: to only update server-side classes
~fastOptJSToExplodedWar: to only update the Form Builder Scala.js artifacts
~ ;copyJarToExplodedWar;fastOptJSToExplodedWar: to update both
The copyJarToExplodedWar command in the root project incrementally:
builds all the sub-projects depended by root
orbeon-form-builder-shared (empty currently on master)
copies the following resulting JAR files to build/orbeon-war/WEB-INF/lib
To run tests from IntelliJ:
from sbt, first run test:compile
run "Unit Tests" from IntelliJ
there are issues, with the following tests failing:
Note that the debugging and profiling settings above are different: you either run in debug mode, or in profiling mode.
If you modify Java or Scala files, you need to recompile. Go to menu "Build" → "Make Module 'Orbeon Forms'", or use the keyboard shortcut (F7).
If you are connected to Tomcat via the debugger AND you are lucky, changed classes will reload in the JVM via HotSwap. See also the IntelliJ doc on Reloading Classes. Otherwise, you need to restart Tomcat to see your changes.
NOTE: HotSwap has limitations, especially with Scala code which produces and modifies more class files. It is not a silver bullet and there will be cases where you will need to redeploy the web application or restart the application server. But you will spare yourself a redeployment or restart in the cases where your modification to the Java or Scala code does not significantly change the structure of classes.
If you modify resource files, re-run the ant orbeon-war target from IntelliJ.
If you make changes to .less files and want those recompiled automatically, you need the "File Watchers" IntelliJ plugin, as well as the less compiler. You can install it with:
brew install lessc
This installs the less compiler to /usr/local/bin/lessc, which is where the included IntelliJ "File Watchers" configuration points to. If it's in a different location, you'll need to adjust the path.
Running the tests
Select the "Unit Tests" configuration in IntelliJ, and run it. This should take about a minute.
IntelliJ then shows : "Done: 723 of 731 Failed: 8"
The tests that fail are the following:
CombinedClientTest: this requires Selenium to be setup.
DDLTest and RestApiTest: these require a database setup.
We hope to provide instructions to run these in the future.
From the command line
From the command line, you need ant installed. Building should work with ant 1.8.x or 1.9.x.
You can then run, from the orbeon-forms directory:
Currently, there is no incremental compilation when running from the command line. We hope to move to sbt in the future, see #1585. Because of this, Orbeon developers tend to build from IntelliJ, and build with ant on continuous integration build servers only.
A related known issue, from the command-line, is that running ant classes twice in a row fails with errors. You must remove classes under build/classes before running ant classes again.
NOTE: With ant, class files are produced under build/classes, but with IntelliJ they are produced under build/orbeon-war/WEB-INF/classes. You should be aware of this is you switch between building from IntelliJ and building with ant.
Building a distribution
WARNING: ant clean deletes everything under the build directory. This includes the data for the embedded eXist database. If you have some test data, including form definitions and data in there, backup build/orbeon-war/WEB-INF/exist-data first!
run ant clean
run ant orbeon-dist-war to build the WAR files
run ant teamcity-release to clean, test, and build the entire release