changeset 44:6999afa6fff3

Update Building instructions; minor build system bug fixes.
author David Barts <davidb@stashtea.com>
date Sun, 03 May 2020 16:15:10 -0700
parents 8aada13933c6
children c9cf2b01c91c
files Building.html build.xml make-debian-package setup.cmd setup.sh
diffstat 5 files changed, 76 insertions(+), 35 deletions(-) [+]
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>
--- a/build.xml	Sat May 02 10:48:17 2020 -0700
+++ b/build.xml	Sun May 03 16:15:10 2020 -0700
@@ -17,6 +17,7 @@
   </macrodef>
   <env-require name="JRE_HOME"/>
   <env-require name="KOTLIN_HOME"/>
+  <env-require name="OSDEP_HOME"/>
 
   <!-- cribbed from https://stackoverflow.com/questions/7129672/uppercase-lowercase-capitalize-an-ant-property -->
   <scriptdef language="javascript" name="toLowerCase">
@@ -150,7 +151,7 @@
   <target name="osdep">
     <exec executable="${env.JRE_HOME}/bin/java" failonerror="true">
       <arg value="-jar"/>
-      <arg value="../Osdep/osdep.jar"/>
+      <arg file="${env.OSDEP_HOME}/osdep.jar"/>
       <arg value="${src.home}"/>
     </exec>
   </target>
--- a/make-debian-package	Sat May 02 10:48:17 2020 -0700
+++ b/make-debian-package	Sun May 03 16:15:10 2020 -0700
@@ -45,7 +45,7 @@
 
 # Process data
 cd data
-find . -type f -print0 | xargs -0 md5sum > ../control/md5sums
+find * -type f -print0 | xargs -0 md5sum > ../control/md5sums
 tar -c -z --owner=0 --group=0 -f ../data.tar.gz *
 
 # Process control
--- a/setup.cmd	Sat May 02 10:48:17 2020 -0700
+++ b/setup.cmd	Sun May 03 16:15:10 2020 -0700
@@ -8,6 +8,7 @@
 set ANT_HOME=C:\Users\David Barts\java\apache-ant-1.10.7
 set EXIV2_HOME=C:\Users\David Barts\Downloads\exiv2-0.27.2-2017msvc64\exiv2-0.27.2-2017msvc64
 set LAUNCH4J_HOME=C:\Program Files (x86)\Launch4j
+set OSDEP_HOME=..\Osdep
 
 rem For each directory, fix PATH if needed.
 call :fixpath "%JRE_HOME%"
--- a/setup.sh	Sat May 02 10:48:17 2020 -0700
+++ b/setup.sh	Sun May 03 16:15:10 2020 -0700
@@ -3,6 +3,7 @@
 export JRE_HOME="$(/usr/libexec/java_home)"
 export KOTLIN_HOME="/usr/local/Cellar/kotlin/1.3.71/libexec"
 export EXIV2_HOME="$HOME/temp/exiv2/exiv2-0.27.2-Source"
+export OSDEP_HOME="../Osdep"
 
 export ANT_HOME="$HOME/java/apache-ant-1.10.1"
 if [[ "$PATH" != *$ANT_HOME/bin* ]]