Updated documentation in general, and specifically on specifying loca…

…tion of `ant-javafx.jar`.

Added debug logging messages during search for `ant-javafx.jar`.

src/main/scala/com/typesafe/sbt/packager/jdkpackager/JDKPackagerAntHelper.scala

@@ -16,7 +16,7 @@ import scala.xml.Elem
 object JDKPackagerAntHelper {
 
   /** Attempts to compute the path to the `javapackager` tool. */
-  private[jdkpackager] def locateAntTasks(javaHome: Option[File]): Option[File] = {
+  private[jdkpackager] def locateAntTasks(javaHome: Option[File], logger: Logger): Option[File] = {
     val jarname = "ant-javafx.jar"
 
     // This approach to getting JDK bits is borrowed from: http://stackoverflow.com/a/25163628/296509
@@ -46,7 +46,10 @@ object JDKPackagerAntHelper {
     }
 
     // Now search for the tool
-    entryPointsSpecialCaseWindows.map(_ / "lib" / jarname).find(_.exists)
+    entryPointsSpecialCaseWindows
+      .map(_ / "lib" / jarname)
+      .find { f ⇒ logger.debug(s"Looking for '$jarname' in  '${f.getParent}'"); f.exists() }
+      .map { f ⇒ logger.debug(s"Found '$f'!"); f }
   }
 
   type PlatformDOM = Elem
@@ -163,7 +166,8 @@ object JDKPackagerAntHelper {
     if (antTaskLib.isEmpty) {
       sys.error(
         "Please set key `antPackagerTasks in JDKPackager` to `ant-javafx.jar` path, " +
-          "which should be find in the `lib` directory of JDK 8 installation.")
+          "which should be find in the `lib` directory of the Oracle JDK 8 installation. For example (Windows):\n" +
+          """(antPackagerTasks in JDKPackager) := Some("C:\\Program Files\\Java\\jdk1.8.0_45\\lib\\ant-javafx.jar")""")
     }
 
     val taskClassPath = Seq(sourceDir.getAbsolutePath, antTaskLib.get, ".")

src/main/scala/com/typesafe/sbt/packager/jdkpackager/JDKPackagerKeys.scala

@@ -73,7 +73,9 @@ trait JDKPackagerKeys {
 
   val jdkPackagerAssociations = settingKey[Seq[FileAssociation]](
     """Set of application file associations to register for the application.
+      |Example: `jdkPackagerAssociations := Seq(FileAssociation("foo", "application/x-foo", Foo Data File", iconPath))
       |Default: `Seq.empty`
+      |Note: Requires JDK >= 8 build 40.
       |Details:
       |  http://docs.oracle.com/javase/8/docs/technotes/guides/deploy/javafx_ant_task_reference.html#CIAIDHBJ
     """.stripMargin
@@ -87,7 +89,7 @@ trait JDKPackagerKeys {
   // ------------------------------------------
 
   val antPackagerTasks = settingKey[Option[File]](
-    "Path to `ant-javafx.jar` library in JDK.")
+    "Path to `ant-javafx.jar` library in JDK. By plugin attempts to find location based on `java.home` property. Specifying `JAVA_HOME` or `JDK_HOME` can help.")
 
   val antBuildDefn = taskKey[xml.Node](
     "Generates a Ant XML DOM defining package generating build for JDK provided Ant task."

src/main/scala/com/typesafe/sbt/packager/jdkpackager/JDKPackagerPlugin.scala

@@ -51,7 +51,7 @@ object JDKPackagerPlugin extends AutoPlugin {
       packageSummary := packageSummary.value,
       packageDescription := packageDescription.value,
       mappings := (mappings in Universal).value,
-      antPackagerTasks := locateAntTasks(javaHome.value),
+      antPackagerTasks := locateAntTasks(javaHome.value, sLog.value),
       antBuildDefn := makeAntBuild(
         antPackagerTasks.value,
         name.value,

src/sphinx/formats/jdkpackager.rst

@@ -1,9 +1,11 @@
 JDKPackager Plugin
 ==================
 
-JDK 8 from Oracle includes the tool `javapackager` (née `javafxpackager`), which generates native application launchers and installers for MacOS X, Windows, and Linux. This plugin complements the existing `sbt-native-packager` formats by taking the settings and staged output from `JavaAppPackaging` and passing them through `javapackager` to create native formats per Oracle's defined mechanisms.
+JDK 8 from Oracle includes the tool ``javapackager`` (née ``javafxpackager``), which generates native application launchers and installers for MacOS X, Windows, and Linux. This plugin complements the existing `sbt-native-packager` formats by taking the settings and staged output from ``JavaAppPackaging`` and passing them through ``javapackager`` to create native formats per Oracle's provided features.
 
-This plugin's most relevant addition to the core `sbt-native-packager` capabilities is the generation of MacOS X App bundles, and associated `.dmg` and `.pkg` package formats. With this plugin complete drag-and-drop installable application bundles are possible, including the embedding of the JRE. It can also generate Windows `.exe` and `.msi` installers provided the requisite tools are available on the Windows build platform.
+The actual mechanism used by this plugin is the support provided by the ``lib/ant-javafx.jar`` Ant task library, which provides more capabilities than the ``javapackager`` command line version, but the idea is the same.
+
+This plugin's most relevant addition to the core `sbt-native-packager` capabilities is the generation of MacOS X App bundles, and associated ``.dmg` and ``.pkg`` package formats. With this plugin complete drag-and-drop installable application bundles are possible, including the embedding of the JRE. It can also generate Windows ``.exe`` and ``.msi`` installers provided the requisite tools are available on the Windows build platform (see below). While Linux package formats are also possible via this plugin, it is likely the native `sbt-native-packager` support for ``.deb`` and ``.rpm`` formats will provide more configurability.
 
 .. contents::
   :depth: 2
@@ -12,16 +14,16 @@ This plugin's most relevant addition to the core `sbt-native-packager` capabilit
 
   <div class="alert alert-info" role="alert">
     <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span>
-    The JDKPackagerPlugin depends on the Universal and JavaAppPackaging plugins. For inherited settings read the <a href="../archetypes/java_app/index.html">Java Application Plugin Documentation</a>
+    The <tt>JDKPackagerPlugin</tt> depends on the <tt>Universal</tt>, <tt>JavaAppPackaging</tt> and <tt>LauncherJarPlugin</tt> plugins. For inherited settings read the <a href="../archetypes/java_app/index.html">Java Application Plugin Documentation</a>
   </div>
 
 
 Requirements
 ------------
 
-The `javapackager` tool comes with JDK 8, and found in the `bin` directory along with `javac` and friends. (An earlier form of the tool was introduced in later forms of JDK 7 as `javafxpackager`.)  If `sbt` is running under the JVM in JDK 8, then the plugin should be able to find the path to `javapackager`. If `sbt` is running under a different JVM, then the path to the tool will have to be specified via the ``jdkPackagerTool`` setting.
+The ``ant-javafx.jar`` library comes with *Oracle* JDK 8, found in the ``lib`` directory along with ``tools.jar`` and friends. If `sbt` is running under the JVM in Oracle JDK 8, then the plugin should be able to find the path to ``ant-javafx.jar``. If `sbt` is running under a different JVM, then the path to the tool will have to be specified via the ``jdkPackager:antPackagerTasks`` setting.
 
-This plugin must be run on the platform of the target installer. The `javapackager` tool does not provide a means of creating, say, Windows installers on MacOS, etc.
+This plugin must be run on the platform of the target installer. The Oracle tooling does *not* provide a means of creating, say, Windows installers on MacOS, or MacOS on Linux, etc.
 
 To use create Windows launchers & installers, the either the WIX Toolset (``msi``) or Inno Setup (``exe``) is required:
 
@@ -43,13 +45,13 @@ The plugin is enabled via the ``AutoPlugins`` facility:
 Build
 -----
 
-To use, first get your application working per `JavaAppPackaging` instructions (including the ``mainClass`` setting). Once that is working, run
+To use, first get your application working per ``JavaAppPackaging`` instructions (including the ``mainClass`` setting). Once that is working, run
 
 .. code-block:: scala
 
   sbt jdkPackager:packageBin
 
-By default, the plugin makes the installer type that is native to the current build platform in the directory `target/jdkpackager`. The key `jdkPackageType` can be used to modify this behavior. Run `help jdkPackageType` in sbt for details. The most popular setting is likely to be `jdkAppIcon`.
+By default, the plugin makes the installer type that is native to the current build platform in the directory ``target/jdkpackager/bundles``. The key ``jdkPackageType`` can be used to modify this behavior. Run ``help jdkPackageType`` in `sbt` for details. The most popular setting is likely to be ``jdkAppIcon``.
 
 Settings
 --------
@@ -110,7 +112,9 @@ Settings
 
 ``jdkPackagerAssociations``
   Set of application file associations to register for the application.
-  Default: ``Seq.empty``
+  Example: `jdkPackagerAssociations := Seq(FileAssociation("foo", "application/x-foo", Foo Data File", iconPath))
+  Default: `Seq.empty`
+  Note: Requires JDK >= 8 build 40.
   `Oracle associations docs <http://docs.oracle.com/javase/8/docs/technotes/guides/deploy/javafx_ant_task_reference.html#CIAIDHBJ>`_
 
 Example
@@ -163,8 +167,15 @@ Here's what the build file looks like:
         FileAssociation("barbaz", "application/barbaz", "Barbaz file type", jdkAppIcon.value)
     )
 
+    // Example of specifying a fallback location of `ant-javafx.jar` if plugin can't find it.
+    (antPackagerTasks in JDKPackager) := (antPackagerTasks in JDKPackager).value orElse {
+      for {
+        f <- Some(file("/usr/lib/jvm/java-8-oracle/lib/ant-javafx.jar")) if f.exists()
+      } yield f
+    }
+
 
 Debugging
 ---------
 
-If you are having trouble figuring out how certain features affect the generated package, you can find the Ant-based build definition file in ``target/jdkpackager/build.xml``. You should be able to run Ant directly in that file assuming `jdkPackager:packageBin` has been run at least once.
+If you are having trouble figuring out how certain features affect the generated package, you can find the Ant-based build definition file in ``target/jdkpackager/build.xml``. You should be able to run Ant directly in that file assuming ``jdkPackager:packageBin`` has been run at least once.

test-project-jdkpackager/build.sbt

@@ -42,3 +42,10 @@ jdkPackagerAssociations := Seq(
   FileAssociation("foobar", "application/foobar", "Foobar file type"),
   FileAssociation("barbaz", "application/barbaz", "Barbaz file type", jdkAppIcon.value)
 )
+
+// Example of specifying a fallback location of `ant-javafx.jar` if plugin can't find it.
+(antPackagerTasks in JDKPackager) := (antPackagerTasks in JDKPackager).value orElse {
+  for {
+    f <- Some(file("/usr/lib/jvm/java-8-oracle/lib/ant-javafx.jar")) if f.exists()
+  } yield f
+}