getdown/src/getdown/README.md

   1 ## What is it?
   2
   3 Getdown (yes, it's the funky stuff) is a system for deploying Java applications to end-user
   4 computers, as well as keeping those applications up to date.
   5
   6 It was designed as a replacement for [Java Web Start](https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/)
   7 due to limitations in Java Web Start's architecture which are outlined in the
   8 [rationale](https://github.com/threerings/getdown/wiki/Rationale) section.
   9
  10 Note: Getdown was designed *in 2004* as an alternative to Java Web Start, because of design choices
  11 made by JWS that were problematic to the use cases its authors had. It is _not_ a drop-in
  12 replacement for JWS, aimed to help the developers left in the lurch by the deprecation of JWS in
  13 Java 9. It may still be a viable alternative for developers looking to replace JWS, but don't
  14 expect to find feature parity with JWS.
  15
  16 ## How do I use it?
  17
  18 A tutorial and more detailed specification are available from the [Documentation] page. Questions
  19 can be posted to the [OOO Libs Google group].
  20
  21 Note that because one can not rely on users having a JRE installed, you must create a custom
  22 installer for each platform that you plan to support (Windows, macOS, Linux) that installs a JRE,
  23 the Getdown launcher jar file, a stub configuration file that identifies the URL at which your real
  24 app manifest is hosted, and whatever the appropiate "desktop integration" is that provides an icon
  25 the user can click on. We have some details on the
  26 [installers](https://github.com/threerings/getdown/wiki/Installers) documentation page, though it
  27 is unfortunately not very detailed.
  28
  29 ## How does it work?
  30
  31 The main design and operation of Getdown is detailed on the
  32 [design](https://github.com/threerings/getdown/wiki/Design) page. You can also browse the
  33 [javadoc documentation] and [source code] if you're interested in implementation details.
  34
  35 ## Where can I see it in action?
  36
  37 Getdown was originally written by developers at [OOO] for the deployment of their Java-based
  38 massively multiplayer games. Try out any of the following games to see it in action:
  39
  40   * [Puzzle Pirates](https://www.puzzlepirates.com/) - OOO
  41   * [Spiral Knights](https://www.spiralknights.com/) - OOO
  42
  43 Getdown is implemented in Java, and is designed to deploy and update JVM-based applications. While
  44 it would be technically feasible to use Getdown to deploy non-JVM-based applications, it is not
  45 currently supported and it is unlikely that the overhead of bundling a JVM just to run Getdown
  46 would be worth it if the JVM were not also being used to run the target application.
  47
  48 ## Release notes
  49
  50 See [CHANGELOG.md](CHANGELOG.md) for release notes.
  51
  52 ## Obtaining Getdown
  53
  54 Getdown will likely need to be integrated into your build. We have separate instructions for
  55 [build integration]. You can also download the individual jar files from Maven Central if needed.
  56 Getdown is comprised of three Maven artifacts (jar files), though you probably only need the first
  57 one:
  58
  59   * [getdown-launcher](http://repo2.maven.org/maven2/com/threerings/getdown/getdown-launcher)
  60     contains minified (via Proguard) code that you actually run to update and launch your app. It
  61     also contains the tools needed to build a Getdown app distribution.
  62
  63   * [getdown-core](http://repo2.maven.org/maven2/com/threerings/getdown/getdown-core) contains the
  64     core logic for downloading, verifying, patching and launching an app as well as the core logic
  65     for creating an app distribution. It does not contain any user interface code. You would only
  66     use this artifact if you were planning to integrate Getdown directly into your app.
  67
  68   * [getdown-ant](http://repo2.maven.org/maven2/com/threerings/getdown/getdown-ant) contains an Ant
  69     task for building a Getdown app distribution. See the [build integration] instructions for
  70     details.
  71
  72 You can also:
  73
  74   * [Check out the code](https://github.com/threerings/getdown) and build it yourself.
  75   * Browse the [source code] online.
  76   * View the [javadoc documentation] online.
  77
  78 ## JVM Version Requirements
  79
  80   * Getdown version 1.8.x requires Java 7 VM or newer.
  81   * Getdown version 1.7.x requires Java 7 VM or newer.
  82   * Getdown version 1.6.x requires Java 6 VM or newer.
  83   * Getdown version 1.5 and earlier requires Java 5 VM or newer.
  84
  85 ## Migrating from Getdown 1.7 to Getdown 1.8
  86
  87 See [this document](https://github.com/threerings/getdown/wiki/Migrating-from-1.7-to-1.8) on the
  88 changes needed to migrate from Getdown 1.7 to 1.8.
  89
  90 ## Building
  91
  92 Getdown is built with Maven in the standard ways. Invoke the following commands, for fun and
  93 profit:
  94
  95 ```
  96 % mvn compile  # builds the classes
  97 % mvn test     # builds and runs the unit tests
  98 % mvn package  # builds and creates jar file
  99 % mvn install  # builds, jars and installs in your local Maven repository
 100 ```
 101
 102 ## Discussion
 103
 104 Feel free to pop over to the [OOO Libs Google Group] to ask questions and get (and give) answers.
 105
 106 [Documentation]: https://github.com/threerings/getdown/wiki
 107 [OOO Libs Google group]: http://groups.google.com/group/ooo-libs
 108 [source code]: https://github.com/threerings/getdown/tree/master/src/main/java/com/threerings/getdown/launcher
 109 [javadoc documentation]: https://threerings.github.com/getdown/apidocs/
 110 [OOO]: https://en.wikipedia.org/wiki/Three_Rings_Design
 111 [build integration]: https://github.com/threerings/getdown/wiki/Build-Integration