Add Windows OS build and deployment (#5)

jody · web-flow · commit fcf0d94bf217 · 2025-12-25T15:58:10.000-07:00
* Add Windows packaging support with .msi installer
* Update and clarify information in README.
* Refactored build.xml then split javadoc target in two: usage api, internal
* Update src/Main.java comment about hidden constructor and add author and version tags
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [macos-latest, ubuntu-latest]
+        os: [macos-latest, ubuntu-latest, windows-latest]
 
     steps:
     - name: Checkout Code
@@ -61,6 +61,7 @@ jobs:
           files: |
             artifacts/*.dmg
             artifacts/*.deb
+            artifacts/*.msi
           body: "Automatic build of ${{ github.ref_name }}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,18 +1,18 @@
 # NativeJavaApp
 Scaffold for creating double-clickable apps using Java
 
-This project uses Apache Ant and JDK 25 to compile, bundle, and package a Java application into native installers (.dmg for macOS and .deb for Ubuntu).
+This project uses Apache Ant and JDK 25 to compile, bundle, and package a Java application into native installers (.dmg for macOS, .deb for Ubuntu, and .msi for Windows).
 
 ## Common Requirements (All Systems)
 Before running the build, ensure the following are installed and configured:
-- JDK 21 or 25: Must be installed. jpackage was introduced in JDK 14, but JDK 21+ is recommended for modern macOS/Linux support.
+- JDK 21 or 25: Must be installed. Although jpackage was introduced in JDK 14, JDK 21+ is recommended for modern macOS/Linux/Windows support.
 - Apache Ant: Installed and available in your PATH.
-- JAVA_HOME: This environment variable must point to your JDK installation directory.
-  - Check via: ant -version and java -version
+- `JAVA_HOME`: This environment variable must point to your JDK installation directory.
+  - Check via: `ant -version` and `java -version`
 ## macOS Setup
 To build the .dmg installer, your Mac needs the following:
 - Xcode Command Line Tools: Required for various build utilities.
-  - Install via: xcode-select --install
+  - Install via: `xcode-select --install`
 - Icon Asset: A file named icon.icns must be in the project root.
 - Note on Security: Since the app is not "Signed" with an Apple Developer Certificate, users may need to Right-Click > Open the app the first time to bypass the "Unidentified Developer" warning.
 ## Ubuntu / Debian Setup
@@ -27,24 +27,35 @@ sudo apt install ant fakeroot dpkg-dev
 - fakeroot: Allows the package to be built with correct file permissions without requiring root access.
 - dpkg-dev: Provides the core utilities to create Debian packages.
 - Icon Asset: A file named icon.png (512x512 recommended) must be in the project root.
+## Windows Setup
+To build the .msi installer on Windows, ensure the following:
+- JDK 21 or 25: Must be installed with JAVA_HOME configured.
+- Apache Ant: Installed and available in your PATH.
+- WiX Toolset: Required by jpackage to create MSI installers.
+  - Download and install from: https://wixtoolset.org/releases/
+  - Version 3.11 or higher is recommended.
+  - After installation, verify WiX is in your PATH by running: `candle -?`
+- Icon Asset: A file named icon.ico must be in the project root.
+- Note on Security: Windows may show a SmartScreen warning for unsigned installers. Users will need to click "More info" > "Run anyway" to install the app.
 ## Project Directory Structure
 Ensure your project looks like this for the build.xml to find all resources:
 
 ```Plaintext
-MyAntApp/
+MyAppName/
 ├── src/
 │   └── Main.java       # Your source code
 ├── icon.icns           # Required for macOS DMG
 ├── icon.png            # Required for Ubuntu DEB
+├── icon.ico            # Required for Windows MSI
 └── build.xml           # The Ant build script
 ```
 ## Usage Commands
-Open your terminal in the project root and use the following targets:
+Open a terminal in the project root and use the following targets:
 
 | Command |	Description |
 |-----|-----|
 | ant |	The default; runs the package target. |
-| ant package |	Automatically detects OS and builds .dmg (Mac) or .deb (Linux). |
+| ant package |	Automatically detects OS and builds .dmg (Mac), .deb (Linux), or .msi (Windows). |
 | ant run	| Compiles and launches the app immediately for testing. |
 | ant clean	| Deletes the build/ and dist/ folders to start fresh. |
 | ant -p	| Displays a help menu of all available targets. |
@@ -58,6 +69,10 @@ Open your terminal in the project root and use the following targets:
     <td>Linux Icon Error: </td>
     <td>If the Linux build fails, ensure icon.png is not just a renamed .icns or .jpg. It must be a valid PNG file.</td>
   </tr>
+  <tr>
+    <td>Windows "candle.exe not found": </td>
+    <td>Install WiX Toolset 3.11+ and ensure it's in your PATH. jpackage uses WiX to create MSI installers on Windows.</td>
+  </tr>
   <tr>
     <td>Permissions: </td>
     <td>If the generated .app or .deb won't execute, ensure you have the necessary write permissions in the dist/ directory.</td>
@@ -69,15 +84,15 @@ This project uses GitHub Actions to automatically build and distribute native in
 
 ### The Build Phase (Continuous Integration)
 Every time you push code to the main branch or open a Pull Request:
-- GitHub starts a macOS runner and an Ubuntu runner.
-- Both systems compile the code and create their respective installers (.dmg and .deb).
+- GitHub starts a macOS runner, an Ubuntu runner, and a Windows runner.
+- All systems compile the code and create their respective installers (.dmg, .deb, and .msi).
 - The installers are saved as Artifacts in the GitHub Actions run summary for 90 days.
 ### The Release Phase (Continuous Deployment)
 A formal GitHub Release is only triggered when you push a version tag.
-This creates a permanent download page for your users.
+This creates a permanent download page for users.
 
 #### How to trigger a new release:
-To release a new version (e.g., version 1.0.1), run the following commands in your terminal:
+To release a new version (e.g., version 1.0.1), run the following commands in a terminal:
 
 ```Bash
 # 1. Tag the current commit
@@ -92,8 +107,9 @@ git push origin v1.0.1
 - Under Assets, you will find:
   - MyAntApp-Installer.dmg (for macOS)
   - MyAntApp-Linux.deb (for Ubuntu/Debian)
+  - MyAntApp-Windows.msi (for Windows)
 
-### Pro-Tip: Changing the Version Number
-When you're ready to bump the version, remember to update the version number in two places to keep everything in sync:
+### Changing the Version Number
+When ready to bump the version, remember to update the version number in **two** places to keep everything in sync:
 - The Git Tag (the v1.0.1 above).
-- The app.version property at the top of your build.xml. This ensures that when the user installs the app, the OS sees the correct version number in the "About" or "Get Info" screens.
+- The **app.version** property at the top of `build.xml`. This ensures that when the user installs the app, the OS sees the correct version number in the "About" or "Get Info" screens.
diff --git a/build.xml b/build.xml
@@ -21,6 +21,31 @@
     </not>
   </condition>
 
+  <macrodef name="generate-javadoc">
+    <attribute name="access-level" default="protected"/>
+    <attribute name="output-subdir"/>
+    <sequential>
+      <mkdir dir="${docs.dir}/@{output-subdir}"/>
+      <javadoc destdir="${docs.dir}/@{output-subdir}"
+               source="1.8"
+               encoding="UTF-8"
+               use="true"
+               author="true"
+               version="true"
+               failonerror="true"
+               access="@{access-level}">
+        <fileset dir="${src.dir}" includes="**/*.java"/>
+        <link href="${javadoc.api.url}"/>
+        <!-- Uncomment to resolve references in Javadoc comments to lib/ jars. -->
+        <!--
+            <classpath>
+            <pathelement path="${build.dir}"/>
+            <fileset dir="lib" includes="**/*.jar" erroronmissingdir="false"/>
+            </classpath>
+        -->
+        </javadoc>
+    </sequential>
+  </macrodef>
 
   <condition property="isMac">
     <os family="mac"/>
@@ -33,9 +58,22 @@
     </and>
   </condition>
 
-  <condition property="icon.file" value="icon.icns" else="icon.png">
+  <condition property="isWindows">
+    <os family="windows"/>
+  </condition>
+
+  <condition property="icon.file" value="icon.icns">
     <isset property="isMac"/>
   </condition>
+  <condition property="icon.file" value="icon.ico">
+    <and>
+      <isset property="isWindows"/>
+      <not><isset property="icon.file"/></not>
+    </and>
+  </condition>
+  <condition property="icon.file" value="icon.png">
+    <not><isset property="icon.file"/></not>
+  </condition>
 
   <target name="preflight" description="Print toolchain/OS info">
     <echo message="Java: ${java.runtime.name} ${java.runtime.version}"/>
@@ -72,31 +110,20 @@
     <java jar="${jar.dir}/${app.name}.jar" fork="true"/>
   </target>
 
-  <target name="javadoc" depends="preflight" description="Generate Javadoc (works for unnamed or named packages)">
-    <mkdir dir="${docs.dir}"/>
-    <javadoc destdir="${docs.dir}"
-             source="1.8"
-             encoding="UTF-8"
-             use="true"
-             author="true"
-             version="true"
-             failonerror="true">
-      <fileset dir="${src.dir}" includes="**/*.java"/>
-
-      <link href="${javadoc.api.url}"/>
-      <!-- Uncomment to resolve references in Javadoc comments. -->
-      <!--
-          <classpath>
-          <pathelement path="${build.dir}"/>
-          <fileset dir="lib" includes="**/*.jar"/>
-          </classpath>
-      -->
-    </javadoc>
+  <target name="javadoc" depends="preflight" description="Generate standard API documentation">
+    <generate-javadoc access-level="protected" output-subdir="api"/>
   </target>
 
-  <target name="package" description="Build the native installer for the current OS (DMG or DEB)">
+  <target name="javadoc-internal" depends="preflight" description="Generate internal documentation (includes private members)">
+    <generate-javadoc access-level="private" output-subdir="internal"/>
+  </target>
+
+  <target name="javadoc-all" depends="javadoc, javadoc-internal" description="Generate both standard and internal documentation sets"/>
+
+  <target name="package" description="Build the native installer for the current OS (DMG, DEB, or MSI)">
     <antcall target="dmg"/>
     <antcall target="debian"/>
+    <antcall target="windows"/>
   </target>
 
   <target name="dmg" depends="jar" if="isMac" description="[Mac Only] Builds the .dmg installer">
@@ -148,4 +175,29 @@
     <echo message="Success! Debian Package: ${dist.dir}/${app.name}-Linux.deb"/>
   </target>
 
+  <target name="windows" depends="jar" if="isWindows" description="[Windows Only] Builds the .msi installer">
+    <mkdir dir="${dist.dir}"/>
+    <exec executable="jpackage" failonerror="true">
+      <arg value="--input"/><arg value="${jar.dir}"/>
+      <arg value="--dest"/><arg value="${dist.dir}"/>
+      <arg value="--name"/><arg value="${app.name}"/>
+      <arg value="--main-jar"/><arg value="${app.name}.jar"/>
+      <arg value="--main-class"/><arg value="${main.class}"/>
+      <arg value="--type"/><arg value="msi"/>
+      <arg value="--icon"/><arg value="${icon.file}"/>
+      <arg value="--app-version"/><arg value="${app.version}"/>
+      <arg value="--win-dir-chooser"/>
+      <arg value="--win-shortcut"/>
+      <arg value="--win-menu"/>
+    </exec>
+    <move todir="${dist.dir}">
+      <fileset dir="${dist.dir}">
+        <include name="${app.name}*.msi"/>
+        <exclude name="${app.name}-Windows.msi"/>
+      </fileset>
+      <mapper type="merge" to="${app.name}-Windows.msi"/>
+    </move>
+    <echo message="Success! Windows Installer: ${dist.dir}/${app.name}-Windows.msi"/>
+  </target>
+
 </project>
diff --git a/icon.ico b/icon.ico
diff --git a/src/Main.java b/src/Main.java
@@ -2,8 +2,13 @@
 
 /**
  * Main class with main method invoked on app start.
+ * @version 1.0.0
+ * @author Dr. Jody Paul
  */
 public class Main {
+    /** Private constructor to prevent instantiation of entry point class. */
+    private Main() { }
+
     /**
      * Invoked on start.
      * @param args ignored
