view Building.html @ 46:5de364cb2847

Doc tweaks.
author David Barts <davidb@stashtea.com>
date Mon, 04 May 2020 11:06:14 -0700
parents 6999afa6fff3
children fb407182ba76
line wrap: on
line source

<!DOCTYPE html>
<!-- Skeleton or template web page, in the standard style. -->
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Building JpegWasher</title>
    <style>
html { font-family: "TeX Gyre Schola", serif; }
h1, h2, h3, h4, h5, h6 { font-family: "Avenir Next", sans-serif; }
pre, code, kbd, samp { font-family: "Menlo", monospace; ; font-size: 85%; }
    </style>
  </head>
  <body>
    <h1>Building JpegWasher</h1>
    <h2>In General</h2>
    <p>Building JpegWasher is a bit more involved than building your
      run-of-the-mill Java application, because JpegWasher is not a pure Java
      application. The latter is for the simple reason that there are no pure
      Java libraries that allow one to both read <em>and modify</em> image
      metadata. (This deficiency is one of the reasons I put off writing
      JpegWasher for so long, despite my awareness of the need for such a
      utility.)</p>
    <p>At any rate, this has several implications:</p>
    <ol>
      <li>Building JpegWasher takes part in two phases: compiling and linking
        the native-mode code, then compiling the Kotlin code to JVM bytecodes.</li>
      <li>The result of a build will not be portable; it will only run on the
        same type of platform as you used to build it.</li>
    </ol>
    <p>The second point is not <em>strictly</em> true; it is possible, if you
      are careful, to build an executable jar that will run on multiple
      platforms, but the procedure for doing so is not automated and the results
      are not as satisfactory as applications bundled for a specific target. See
      “Building a (Somewhat) Universal Jar” below.<em></em></p>
    <h2>Prerequisites</h2>
    <ul>
      <li><a href="https://ant.apache.org/">Apache Ant</a></li>
      <li><a href="http://launch4j.sourceforge.net/">Launch4j</a>, if you are
        building on Windows</li>
      <li>Java JDK 1.8 or better (see notes).</li>
      <li><a href="https://kotlinlang.org/">Kotlin</a></li>
      <li><a href="https://www.exiv2.org/">Exiv2</a></li>
      <li>A C++ Compiler</li>
      <li>Make (Nmake on Windows)</li>
      <li>Osdep</li>
    </ul>
    <h2>Which Version of Java to Use?</h2>
    <p>In short, Java 1.8. Most systems don’t yet have OpenJDK 11 or greater
      installed, so using a compiler newer than 1.8 is asking for trouble. All
      code <em>should</em> build on OpenJDK 11 or greater, with the exception
      of the OS-dependent code for the Macintosh (which will have to be recoded
      to use the <code>java.awt.Desktop</code> class). The latter would be a
      net win, as it is portable, and would spell the death of the only bit of
      OS-dependent Kotlin code in this application.</p>
    <p>In another year or two, I will probably make OpenJDK 11 or greater the
      preferred version. It’s a little too early to do that right now, however,
      as not many systems have Java 11 present.</p>
    <h2>Build Procedure</h2>
    <h3>Install Prerequisites</h3>
    <p>See the “Prerequisites” section above for the details of what you will
      need.</p>
    <p>If you are building on Windows and are tempted to use a binary
      distribution of Exiv2, the MSVC version is preferred, as it will result in
      a fully native Windows application which does not require Cygwin or MinGW
      to be present. For the same reason, Visual Studio (the free-to-download
      “community” version suffices) is the preferred compiler to compile <code>src/name/blackcap/exifwasher/exiv2/native.cpp</code>
      with.</p>
    <h3>Define Environment Variables</h3>
    <p>The <code>build.xml</code> Ant script expects several environment
      variable to be set, and for your PATH to allow the command-line utilities
      for the prerequisites to be found. Look in <code>setup.sh</code> and/or <code>setup.cmd</code>
      for examples.</p>
    <h3>Compile C++ Source</h3>
    <p>This is done by running <code>make</code> (on Windows, <code>nmake</code>)
      on the appropriate Makefile (<code>Makefile.linux</code>, <code>Makefile.mac</code>,
      or <code>Makefile.win</code>). On Windows, make sure you are in the
      correct sort of command prompt window for the compiler you wish to run
      (these are found in the menu under Visual Studio; the standard command
      prompt will not work, because it won’t have the Visual Studio command-line
      tools in its PATH).</p>
    <h3>Compile Kotlin Source and Bundle an App</h3>
    <p>Just type <code>ant macapp</code>, <code>ant winapp</code>, or <code>ant
      deb</code> depending on whether you are building on a Mac, Windows, or
      Debian Linux (note that Ubuntu is a Debian variant).</p>
    <h3>That’s It!</h3>
    <p>If all went well, a system-specific bundle should be found in the <code>dist</code>
      directory.</p>
    <h2>Building a (Somewhat) Universal Jar</h2>
    <p>It is possible to build an executable jar that will run on both Windows
      and Linux systems, but the process for doing so is not automated. What you
      will have to do is build non-portable Jar files for both Windows and Linux
      by running ant jar on both types of system, then to combine files in both
      jars to create a jar whose <code>name/blackcap/exifwasher/binaries </code>contents
      are their superset and thus contains native-mode code for both systems.</p>
    <p>The drawback here is that the result is nowhere near as nice as the
      bundled applications the standard Ant tasks build. It won’t show up as a
      normal, native-mode application with a nice icon. It is also not possible
      to add the Macintosh to that list of systems, as for sake of human
      interface consistency, the Mac code must contain calls to proprietary
      classes which are not present on non-Mac systems.</p>
  </body>
</html>