Mercurial > cgi-bin > hgweb.cgi > JpegWasher

comparison 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
comparison
equal deleted inserted replaced
43:8aada13933c6 44:6999afa6fff3
10 pre, code, kbd, samp { font-family: "Menlo", monospace; ; font-size: 85%; } 10 pre, code, kbd, samp { font-family: "Menlo", monospace; ; font-size: 85%; }
11 </style> 11 </style>
12 </head> 12 </head>
13 <body> 13 <body>
14 <h1>Building JpegWasher</h1> 14 <h1>Building JpegWasher</h1>
15 <h2>In General</h2>
16 <p>Building JpegWasher is a bit more involved than building your
17 run-of-the-mill Java application, because JpegWasher is not a pure Java
18 application. The latter is for the simple reason that there are no pure
19 Java libraries that allow one to both read <em>and modify</em> image
20 metadata. (This deficiency is one of the reasons I put off writing
21 JpegWasher for so long, despite my awareness of the need for such a
22 utility.)</p>
23 <p>At any rate, this has several implications:</p>
24 <ol>
25 <li>Building JpegWasher takes part in two phases: compiling and linking
26 the native-mode code, then compiling the Kotlin code to JVM bytecodes.</li>
27 <li>The result of a build will not be portable; it will only run on the
28 same type of platform as you used to build it.</li>
29 </ol>
30 <p>The second point is not <em>strictly</em> true; it is possible, if you
31 are careful, to build an executable jar that will run on multiple
32 platforms, but the procedure for doing so is not automated and the results
33 are not as satisfactory as applications bundled for a specific target. See
34 “Building a (Somewhat) Universal Jar” below.<em></em></p>
15 <h2>Prerequisites</h2> 35 <h2>Prerequisites</h2>
16 <ul> 36 <ul>
17 <li><a href="https://ant.apache.org/">Apache Ant</a>, with the following 37 <li><a href="https://ant.apache.org/">Apache Ant</a></li>
18 extensions (note that the extensions are already present in the lib 38 <li><a href="http://launch4j.sourceforge.net/">Launch4j</a>, if you are
19 subdirectory, but you will need to install Ant).</li> 39 building on Windows</li>
20 <ul>
21 <li><a href="http://ant-contrib.sourceforge.net/">Ant-Contrib</a></li>
22 <li><a href="https://github.com/UltraMixer/JarBundler">JarBundler</a>
23 (if building on a Mac)</li>
24 <li><a href="http://launch4j.sourceforge.net/">launch4j</a> (if building
25 on Windows)</li>
26 </ul>
27 <li>Java JDK 1.8 or better (see notes).</li> 40 <li>Java JDK 1.8 or better (see notes).</li>
28 <li>Kotlin</li> 41 <li><a href="https://kotlinlang.org/">Kotlin</a></li>
29 <li>Exiv2</li> 42 <li><a href="https://www.exiv2.org/">Exiv2</a></li>
30 <li>A C++ Compiler</li> 43 <li>A C++ Compiler</li>
31 <li>Make (Nmake on Windows)</li> 44 <li>Make (Nmake on Windows)</li>
32 <li>Osdep</li> 45 <li>Osdep</li>
33 </ul> 46 </ul>
34 <h2>JpegWasher Is Not Pure Java</h2>
35 <p>This means two things: </p>
36 <ol>
37 <li>You need a C++ compiler in addition to a Kotlin compiler (and a Java
38 one) to build&nbsp; JpegWasher.</li>
39 <li>The result of a build will run only on the architecture you built it
40 on.</li>
41 </ol>
42 <p>It <em>is</em> possible to create a semi-portable JAR that runs on both
43 Linux and Windows (it contains both <code>*.so</code> libraries and <code>*.dll</code>
44 ones, and loads the correct ones at run time, see <code>linwin.jar</code>),
45 but the process for doing so is not totally automated. It is alas not
46 possible to support the Macintosh in the same JAR as well, because a Mac
47 app in Java 1.8 requires making a few nonportable, Apple-only API calls,
48 whose presence will cause <code>ClassNotFoundException</code> to be
49 thrown at runtime on non-Macintosh systems.</p>
50 <p>As to why, the answer is simple: Try as I could, I could not find any
51 pure Java libraries that could read <em>and write</em> image metadata.
52 Therefore I had to use a C++ library.</p>
53 <h2>Which Version of Java to Use?</h2> 47 <h2>Which Version of Java to Use?</h2>
54 <p>In short, Java 1.8. Most systems don't yet have OpenJDK 11 or greater 48 <p>In short, Java 1.8. Most systems don’t yet have OpenJDK 11 or greater
55 installed, so using a compiler newer than 1.8 is asking for trouble. All 49 installed, so using a compiler newer than 1.8 is asking for trouble. All
56 code <em>should</em> build on OpenJDK 11 or greater, with the exception 50 code <em>should</em> build on OpenJDK 11 or greater, with the exception
57 of the OS-dependent code for the Macintosh (which will have to be recoded 51 of the OS-dependent code for the Macintosh (which will have to be recoded
58 to use the <code>java.awt.Desktop</code> class). The latter would be a 52 to use the <code>java.awt.Desktop</code> class). The latter would be a
59 net win, as it is portable, and would spell the death of the only bit of 53 net win, as it is portable, and would spell the death of the only bit of
60 OS-dependent Kotlin code in this application.</p> 54 OS-dependent Kotlin code in this application.</p>
61 <p>In another year or two, I will probably make OpenJDK 11 or greater the 55 <p>In another year or two, I will probably make OpenJDK 11 or greater the
62 preferred version.</p> 56 preferred version. It’s a little too early to do that right now, however,
57 as not many systems have Java 11 present.</p>
58 <h2>Build Procedure</h2>
59 <h3>Install Prerequisites</h3>
60 <p>See the “Prerequisites” section above for the details of what you will
61 need.</p>
62 <p>If you are building on Windows and are tempted to use a binary
63 distribution of Exiv2, the MSVC version is preferred, as it will result in
64 a fully native Windows application which does not require Cygwin or MinGW
65 to be present. For the same reason, Visual Studio (the free-to-download
66 “community” version suffices) is the preferred compiler to compile <code>src/name/blackcap/exifwasher/exiv2/native.cpp</code>
67 with.</p>
68 <h3>Define Environment Variables</h3>
69 <p>The <code>build.xml</code> Ant script expects several environment
70 variable to be set, and for your PATH to allow the command-line utilities
71 for the prerequisites to be found. Look in <code>setup.sh</code> and/or <code>setup.cmd</code>
72 for examples.</p>
73 <h3>Compile C++ Source</h3>
74 <p>This is done by running <code>make</code> (on Windows, <code>nmake</code>)
75 on the appropriate Makefile (<code>Makefile.linux</code>, <code>Makefile.mac</code>,
76 or <code>Makefile.win</code>). On Windows, make sure you are in the
77 correct sort of command prompt window for the compiler you wish to run
78 (these are found in the menu under Visual Studio; the standard command
79 prompt will not work, because it won’t have the Visual Studio command-line
80 tools in its PATH).</p>
81 <h3>Compile Kotlin Source and Bundle an App</h3>
82 <p>Just type <code>ant macapp</code>, <code>ant winapp</code>, or <code>ant
83 deb</code> depending on whether you are building on a Mac, Windows, or
84 Debian Linux (note that Ubuntu is a Debian variant).</p>
85 <h3>That’s It!</h3>
86 <p>If all went well, a system-specific bundle should be found in the <code>dist</code>
87 directory.</p>
88 <h2>Building a (Somewhat) Universal Jar</h2>
89 <p>It is possible to build an executable jar that will run on both Windows
90 and Linux systems, but the process for doing so is not automated. What you
91 will have to do is build non-portable Jar files for both Windows and Linux
92 by running ant jar on both types of system, then to combine files in both
93 jars to create a jar whose <code>name/blackcap/exifwasher/binaries </code>contents
94 are their superset and thus contains native-mode code for both systems.</p>
95 <p>The drawback here is that the result is nowhere near as nice as the
96 bundled applications the standard Ant tasks build. It won’t show up as a
97 normal, native-mode application with a nice icon. It is also not possible
98 to add the Macintosh to that list of systems, as for sake of human
99 interface consistency, the Mac code must contain calls to proprietary
100 classes which are not present on non-Mac systems.</p>
63 </body> 101 </body>
64 </html> 102 </html>