Mercurial > cgi-bin > hgweb.cgi > JpegWasher

diff Building.html @ 44:6999afa6fff3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update Building instructions; minor build system bug fixes.
author David Barts <davidb@stashtea.com>
date Sun, 03 May 2020 16:15:10 -0700
parents 89d7f4d91f67
children 5de364cb2847
line wrap: on
line diff
--- a/Building.html	Sat May 02 10:48:17 2020 -0700
+++ b/Building.html	Sun May 03 16:15:10 2020 -0700
@@ -12,46 +12,40 @@
   </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>, with the following
-        extensions (note that the extensions are already present in the lib
-        subdirectory, but you will need to install Ant).</li>
-      <ul>
-        <li><a href="http://ant-contrib.sourceforge.net/">Ant-Contrib</a></li>
-        <li><a href="https://github.com/UltraMixer/JarBundler">JarBundler</a>
-          (if building on a Mac)</li>
-        <li><a href="http://launch4j.sourceforge.net/">launch4j</a> (if building
-          on Windows)</li>
-      </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>Kotlin</li>
-      <li>Exiv2</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>JpegWasher Is Not Pure Java</h2>
-    <p>This means two things: </p>
-    <ol>
-      <li>You need a C++ compiler in addition to a Kotlin compiler (and a Java
-        one) to build&nbsp; JpegWasher.</li>
-      <li>The result of a build will run only on the architecture you built it
-        on.</li>
-    </ol>
-    <p>It <em>is</em> possible to create a semi-portable JAR that runs on both
-      Linux and Windows (it contains both <code>*.so</code> libraries and <code>*.dll</code>
-      ones, and loads the correct ones at run time, see <code>linwin.jar</code>),
-      but the process for doing so is not totally automated. It is alas not
-      possible to support the Macintosh in the same JAR as well, because a Mac
-      app in Java 1.8 requires making a few nonportable, Apple-only API calls,
-      whose presence will cause <code>ClassNotFoundException</code> to be
-      thrown at runtime on non-Macintosh systems.</p>
-    <p>As to why, the answer is simple: Try as I could, I could not find any
-      pure Java libraries that could read <em>and write</em> image metadata.
-      Therefore I had to use a C++ library.</p>
     <h2>Which Version of Java to Use?</h2>
-    <p>In short, Java 1.8. Most systems don't yet have OpenJDK 11 or greater
+    <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
@@ -59,6 +53,50 @@
       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.</p>
+      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>