From a7962d8a9d846d6a6c6fee261c5d6b3c21e6a8c0 Mon Sep 17 00:00:00 2001 From: Andrew Byrd Date: Mon, 8 Jun 2015 12:11:04 +0200 Subject: [PATCH] generate both shaded and non-shaded JARs #1986 also updated documentation and scripts that reference JAR file --- docs/Basic-Usage.md | 8 ++++---- docs/Developers-Guide.md | 2 +- docs/Getting-OTP.md | 26 ++++++++++++++++---------- docs/Scripting.md | 10 +++++----- docs/Version-Notes.md | 2 +- pom.xml | 6 ++++-- src/scripts/otp | 2 +- src/scripts/otp-batch-analyst | 2 +- 8 files changed, 33 insertions(+), 25 deletions(-) diff --git a/docs/Basic-Usage.md b/docs/Basic-Usage.md index 70e7f46de1c..fa6fb046106 100644 --- a/docs/Basic-Usage.md +++ b/docs/Basic-Usage.md @@ -6,9 +6,9 @@ This page will get you up and running with your own OTP server. If all goes well OpenTripPlanner is written in Java and distributed as a single runnable JAR file. These JARs are published [here](http://dev.opentripplanner.org/jars/). Grab one of these JARs for the -[latest released version](http://dev.opentripplanner.org/jars/otp-0.18.0.jar) +[latest released version](http://dev.opentripplanner.org/jars/otp-0.18.0-shaded.jar) or if you're feeling adventurous try the -[bleeding edge development code](http://dev.opentripplanner.org/jars/otp-0.19.0-SNAPSHOT.jar). +[bleeding edge development code](http://dev.opentripplanner.org/jars/otp-0.19.0-SNAPSHOT-shaded.jar). You may also want to get your own copy of the OTP source code and [build the JAR from scratch](Getting-OTP), especially if you plan to do some development yourself. @@ -59,7 +59,7 @@ If you do not you will need to install a recent OpenJDK or Oracle Java package f GTFS and OSM data sets are often very large, and OTP is relatively memory-hungry. You will need at least 1GB of memory when working with the Portland TriMet data set, and several gigabytes for larger inputs. A typical command to start OTP -looks like `java -Xmx1G -jar otp-0.18.0.jar `. The `-Xmx` parameter sets +looks like `java -Xmx1G -jar otp-0.18.0-shaded.jar `. The `-Xmx` parameter sets the limit on how much memory OTP is allowed to consume. If you have sufficient memory in your computer, set this to a couple of gigabytes; when OTP doesn't have enough "breathing room" it can grind to a halt. @@ -67,7 +67,7 @@ It's possible to analyze the GTFS, OSM and any other input data and save the res network (what we call a ['graph'](http://en.wikipedia.org/wiki/Graph_%28mathematics%29)) to disk. For simplicity we'll skip saving this file and start up an OTP server immediately after the graph is built. The command to do so is: - java -Xmx2G -jar otp-0.18.0.jar --build /home/username/otp --inMemory + java -Xmx2G -jar otp-0.18.0-shaded.jar --build /home/username/otp --inMemory where `/home/username/otp` should be the directory where you put your input files. The graph build operation should take about one minute to complete, and then you'll see a `Grizzly server running` message. At this point you can open diff --git a/docs/Developers-Guide.md b/docs/Developers-Guide.md index 52b3ab86b27..595eafd2d75 100644 --- a/docs/Developers-Guide.md +++ b/docs/Developers-Guide.md @@ -271,7 +271,7 @@ Release checklist: - cp -R target/site/enunciate /usr/share/nginx/html/apidoc/x.y.0 - check that all docs in /usr/share/nginx/html/javadoc/ have o+r permissions (they should be by default) - mvn release:perform -- cp target/checkout/target/otp-x.y.0.jar /usr/share/nginx/html/jars/ +- cp target/checkout/target/otp-x.y.0-shaded.jar /usr/share/nginx/html/jars/ - rm /usr/share/nginx/html/jars/otp-x.y.0-SNAPSHOT* - check http://dev.opentripplanner.org/jars/ and http://dev.opentripplanner.org/javadoc/ in a browser - update the version numbers that appear in Basic-Usage, Developers-Guide, Getting-OTP, and index.md and check them in diff --git a/docs/Getting-OTP.md b/docs/Getting-OTP.md index 790418d2d7a..0c631a875ba 100644 --- a/docs/Getting-OTP.md +++ b/docs/Getting-OTP.md @@ -3,10 +3,7 @@ ## Pre-built JARs OpenTripPlanner is now distributed as a single stand-alone runnable JAR file. The JAR file for each release is -published [here](http://dev.opentripplanner.org/jars/). In addition, whenever new changes are made to the master branch -of the main OTP repository on Github, the resulting JAR is published to the - [same location](http://dev.opentripplanner.org/jars/otp-latest-master.jar). - +published [here](http://dev.opentripplanner.org/jars/). ## Building from Source @@ -53,14 +50,16 @@ If all goes well you should see a success message like the following: [INFO] ------------------------------------------------------------------------ ``` -This build process should produce a JAR file called `otp.jar` in the `target/` directory which contains all the -compiled OTP classes and their dependencies. The shell script called 'otp' in the root of the cloned repository will +This build process should produce a JAR file called `otp-x.y.z-shaded.jar` in the `target/` directory which contains +all the compiled OTP classes and their dependencies (the external libraries they use). The shell script called 'otp' +in the root of the cloned repository will start the main class of that JAR file under a Java virtual machine, so after the Maven build completes you should be -able to run `./otp --help` and see an OTP help message including command line options. +able to run `./otp --help` and see an OTP help message including command line options. Due to the way Maven works, this +script is not executable by default, so you will need to do `chmod u+x ./otp` before you run it to mark it as executable. The words "clean package" are the build steps you want to run. You're telling maven to clean up any extraneous junk in - the directory, then perform all the build steps including compilation up to "package", which bundles the compiled program - into a single JAR file for distribution. + the directory, then perform all the build steps, including compilation, up to and including "package", + which bundles the compiled program into a single JAR file for distribution. If you have just cloned OTP you will be working with the default "master" branch, where most active development occurs. This is not the most stable or deployment-ready code available. To avoid newly minted bugs or undocumented behavior, @@ -77,6 +76,13 @@ git clean -df mvn clean package -DskipTests ``` +Please note that the build process creates two distinct versions of the OTP JAR file. The one ending in `-shaded.jar` +is much bigger because it contains copies of all the external libraries that OTP uses. +It serves as a stand-alone runnable distribution of OTP. The one with a version number but without the word `shaded` +contains only OTP itself, without any external dependencies. This JAR is useful when OTP is included as a component in +some other project, where we want the dependency management system to gather all the external libraries automatically. + + ## Maven Repository OpenTripPlanner is a Maven project. Maven is a combined build and dependency management system: it fetches @@ -86,7 +92,7 @@ can be automatically included in other Java projects. This repository is machine-readable (by Maven or other build systems) and for the moment does not include any human readable indexes. You can nonetheless fetch an OTP JAR from this repository by constructing the proper URL for the release -you want. For example, release 0.13.0 will be found at `http://maven.conveyal.com/org/opentripplanner/otp/0.13.0/otp-0.13.0.jar` +you want. For example, release 0.13.0 will be found at `http://maven.conveyal.com/org/opentripplanner/otp/0.13.0/otp-0.13.0-shaded.jar`. To make use of OTP in another project, you must first specify our Maven repository in the Project Object Model (POM): diff --git a/docs/Scripting.md b/docs/Scripting.md index 1d89c032c3b..ffe62dd2557 100644 --- a/docs/Scripting.md +++ b/docs/Scripting.md @@ -14,20 +14,20 @@ There are currently 3 different modes for using scripting: - Launching OTP with the `--script` command-line parameter, providing the script filename as an option. - Starting an OTP server with the `--enableScriptingWebService` command-line parameter, and posting a script to execute to the `/ws/scripting/run` API end-point. -- Launching a Jython script with `otp.jar` in the classpath and creating the scripting entry-point bean in the script itself. +- Launching a Jython script with `otp-x.y.z-shaded.jar` in the classpath and creating the scripting entry-point bean in the script itself. ### Launching a script from OTP The main advantage of this method is its simplicity. The drawback is that you need to start OTP everytime you run a script, which can be slow to startup for large graphs. The second drawback is that you can't import custom packages from within the script, you are limited to the "plain basic" Jython. -__Note__: The Jython (or Groovy) JAR are *not* included in the OTP.jar. You thus have to add one of them (depending on your script) to the java classpath (see command below). Jython jar can be [downloaded here](http://www.jython.org/downloads.html). Make sure you select the "standalone" version of jython, otherwise some classes will be missing. +__Note__: The Jython (or Groovy) JAR are *not* included in the OTP shaded JAR. You thus have to add one of them (depending on your script) to the java classpath (see command below). Jython jar can be [downloaded here](http://www.jython.org/downloads.html). Make sure you select the "standalone" version of jython, otherwise some classes will be missing. __Note__: Due a guava bug, there is an incompatibility between Jython 2.3 / 2.5 and OTP. To solve it, make sure otp.jar is added *before* jython-standalone.jar in the classpath. This bug should be solved in jython starting 2.7. Start OTP specifying the classpath and adding the `--script` option: ```Bash -$ java -cp otp.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --script myscript.py +$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --script myscript.py ``` This will start OTP with a default graph in the current directory and execute the script `myscript.py`. @@ -40,7 +40,7 @@ The main advantage of this method is that you do not need to start a new OTP ser Start an OTP server as usual, adding the `--enableScriptingWebService` option: ``` Bash -$ java -cp otp.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --server --enableScriptingWebService +$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --server --enableScriptingWebService ``` The API end-point `/ws/scripting/run` now accepts script content to be run, posted as multi-part form data. @@ -76,7 +76,7 @@ otp = OtpsEntryPoint.fromArgs([ "--graphs", "." ]) ``` ```Bash -$ java -cp otp.jar:jython-standalone.jar org.python.util.jython myscript.py +$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.python.util.jython myscript.py ``` Note that contrary to java custom the jython "main" class is all lowercase, this is not a typo. diff --git a/docs/Version-Notes.md b/docs/Version-Notes.md index 59a5988ff05..30967078669 100644 --- a/docs/Version-Notes.md +++ b/docs/Version-Notes.md @@ -1,7 +1,7 @@ ## The *master* branch (Version 0.x.0-SNAPSHOT) This is the most up-to-date branch where all new development occurs and is the basis for an upcoming x.y release of OTP. It does not support WAR deployment as it has a built-in HTTP layer, the same one used in the Glassfish application server. -If you run `target/otp-VERSION.jar` with the `--server` option (use `--help` for a list of available options), +If you run `target/otp-x.y.z-shaded.jar` with the `--server` option (use `--help` for a list of available options), resources will be available at the following URLs: - The JavaScript map-based trip planner is at [[http://localhost:8080/]] - The OTP API base path is [[http://localhost:8080/otp/]] diff --git a/pom.xml b/pom.xml index 3edf53097e0..e5b318b8396 100644 --- a/pom.xml +++ b/pom.xml @@ -232,8 +232,10 @@ - - false + + true + shaded diff --git a/src/scripts/otp b/src/scripts/otp index 5158036325c..bc90629140b 100755 --- a/src/scripts/otp +++ b/src/scripts/otp @@ -2,4 +2,4 @@ # Run OTP in standalone mode with the supplied arguments. # Standalone OTP can build a graph, visualize a graph, run an OTP API server, # or any combination of these. -java -Xmx6G -Xverify:none -jar `dirname $0`/target/${project.build.finalName}.jar "$@" +java -Xmx6G -Xverify:none -jar `dirname $0`/target/${project.build.finalName}-shaded.jar "$@" diff --git a/src/scripts/otp-batch-analyst b/src/scripts/otp-batch-analyst index bd9ad1ae574..a7aaa1da96f 100755 --- a/src/scripts/otp-batch-analyst +++ b/src/scripts/otp-batch-analyst @@ -15,4 +15,4 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . -java -Xmx6G -cp `dirname $0`/otp-core/target/otp.jar org.opentripplanner.analyst.batch.BatchProcessor $1 +java -Xmx6G -Xverify:none -cp `dirname $0`/target/${project.build.finalName}-shaded.jar org.opentripplanner.analyst.batch.BatchProcessor $1