jGnash README

jGnash is a free (no strings attached!) personal finance manager with many of the same features as commercially-available software. It was created in order to make tracking personal finances easy, but also provides the functionality needed by advanced users. jGnash is cross-platform and will run on any operating system that has a current Java Runtime Environment (e.g., Linux, Mac OS X, and Microsoft Windows)

• jGnash 2.x requires Java 8 (It can run on later versions. See the Requirements section.)

• jGnash is compatible with the Oracle JVM as well as the open source OpenJDK Platform.

See the Requirements section below for more details, including notes on using Java versions 9, 10, or later.

Contents:

• About jGnash

  • jGnash Features

  • Current version: jGnash-FX

• Donations

• Support

• Requirements

  • Java

  • Supported Operating System versions

• Download jGnash

• Installation

• Running jGnash

• Building and Development

About jGnash

jGnash Features

• Operates on any operating system with Java 8 or newer installed

• Double Entry Accounting with reconciliation tools

• OFX, QFX, mt940, and QIF import capabilities

• Investment Accounts and automatic import of Stocks, Bond, and Funds price history

• Nestable accounts with automatic rollup of totals and intelligent handling of mixed currencies

• Reminders with automatic transaction entry

• Intelligent handling of multiple currencies and exchange rates with automatic online exchange rate updates

• Printable reports with PDF and spreadsheet export capability

• XML and relational database file formats

• Supports concurrent multiple users over a network

To learn more about the features of jGnash, visit the jGnash Website.

The jGnash download includes a user manual to help get you started with the basics if you are new to tracking finances. It also covers some of the more subtle features, command line options, and shortcuts that are not immediately obvious.

The Current Version: jGnashFX

The current version of jGnash uses JavaFX for the user interface. This replaces the old versions that used Java Swing for the user interface. This version is called "jGnashFX" to distinguish it from the older versions. Experienced jGnash users will notice interface improvements. For example, try using the vertical and horizontal scroll wheels in a date picker and the collapsible transaction forms.

The core/engine of jGnash remains the same and is shared by both the Swing and JavaFx versions. This means stability and protection of your valuable data remains the same. This also allows you to switch between versions without issue.

The advantages of JavaFX over Swing are an improved appearance with better utilization of the systems graphics hardware including Hi-DPI systems. It also means a smaller code base for the user interface, access to better components such as improved table support, HTML pages, functional animations, modern controls, etc.

Important

Linux users see must use either an Oracle Java or OpenJFX 8u71 or later. See the requirements on OpenJDK for specifics.

Donations

Donations are always welcome and appreciated. This helps to defer the cost of computer hardware and internet access.

Support

The jGnash Help Group is always a good source if you need help and is the prefered method of contact. Your first post to the group will be moderated to filter spam.

Requirements

1. Java 8 ( or 9 or 10): OpenJDK or Oracle JDK

Java 8

Java 8 JDK 8u71 or later is required to run jGnash using the jGnashFx interface. The 8u71 release fixed several JavaFX bugs and jGnashFx is dependent on several recent API changes. (See the The Current Version: jGnashFX section for information on jGnashFx vs. the legacy Java Swing version.)

Java 9 or 10

jGnash is designed to operate with Java 8. Starting with Java 9, Oracle has removed some modules required by jGnash. It is possible to run jGnash with Java 9 or 10: be sure to read the Install section below to ensure that jGnash has all modules available.

Java 11

jGnash does not yet work with Java 11, but integration work has started with the 3.0-dev branch.

OpenJDK or Oracle JDK

jGnash will work with either OpenJDK or Oracle JDK. jGnashFx has been heavily tested against OpenJFX. There are no noticeable differences in performance or stability with the Oracle release or OpenJDK with OpenJFX.

2. Supported Operating Systems: Windows, Linux, or Mac OS X

Microsoft Windows

• any version that can run the required version(s) of Java 8 8u71

Linux

• any version that can run the required version(s) of Java 8 8u71

Note: jGnash is not compatible with the GCJ Java installation pre-installed on older Linux distributions. You will need to install the OpenJDK or Oracle Java Platform and set the default for jGnash to operate correctly.

Linux and OpenJDK: Some Linux distributions separate the installation of the Open JavaFx libraries from the base JVM package. The jGnashFx interface requires OpenJFX 8u71 or later. OpenJFX 8u40 and u45 packages are generally available for most mainstream Linux distributions, but will not work.

Mac OS X

• Mac OS X 10.8.3 or later

• can run the required version(s) of Java 8 8u71

Be sure to read the section about installing on Mac OS X to create the startup script.

Download jGnash

You can download jGnash from the jGnash Download Page.

To Install jGnash

1. Install the latest version of Java 8 if you don’t already have it installed. Most users of jGnash will want to use the latest version of Oracle Java Runtime Environment, version 8.

   • If you use Java 9 or 10 you will need to do additional installation steps as specified in the Java 9 or 10 section.

   • Developers will want the Java Development Kit (see build instructions below.)

2. Unzip all files into a directory of your choice leaving the directory structure unchanged.

Mac OS X Installation:

1. Copy the jGnash folder to /Applications and remove the version so the final path looks like /Applications/jGnash.

2. Create an AppleScript that will run the application:

   1. Open the AppleScript Editor.

   2. Create the following script:

      try
          do shell script "/Applications/jGnash/jGnashFx"
      end try

   3. Save it as an Application called jGnash.app in /Applications/jGnash

3. Instead of step 2, you can set the /Applications/jGnash/jGnashFx file to Open with…​ Terminal.app (the Terminal application).

Installing with Java 9 or 10

You must have the jaxb-api.jar file available and manually tell jGnash to use it. Here are the steps to do that:

1. Ensure that you have a jaxb-api.jar file and that it is in the jGnash/lib directory. (You can google/search for jaxb-api.jar to find a download that works for you.)

2. Add the additional command line option --add-modules java.xml.bind to the command or shell file you use to run jGnash. You will need to modify the appropriate command or shell file for your operating system in the [jGnash]/bin directory. Adding this command-line option ensures that the jaxb-api.jar file is used.

If jGnash cannot find the jaxb-api.jar, you may see "An illegal reflective access has occurred" warning similar to the following:

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by javassist.util.proxy.SecurityActions (file:/home/craig/.gradle/caches/modules-2/files-2.1/org.javassist/javassist/3.20.0-GA/a9cbcdfb7e9f86fbc74d3afae65f2248bfbf82a0/javassist-3.20.0-GA.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain)
WARNING: Please consider reporting this to the maintainers of javassist.util.proxy.SecurityActions
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release

To fix this: double-check that the jaxb-api.jar file is in the \lib directory and that the command-line option is correct.

This warning should improve at a later date as the Java Ecosystem migrates to Java 9.

To Run:

Executable files are provided for Windows and UN*X users at the root of the installation directory. (These are .bat and bash shell files, respectively.) Mac OS X users will have created application launch files per the Mac installation instructions. The jGnashFx executables will launch jGnash with the latest interface (jGnashFX). The jGnash2 files will launch jGnash with the old legacy Java Swing interface.

Windows: Simply double click on the *.exe file of choice. (jGnashFx.bat is the current and preferred one.)

UN*X: Start jGnash with one of the provided Bash scripts. (jGnashFx is the current and preferred one.) If jGnash fails to launch, check your file permissions and make sure they are set to be executable or use a unzip tool that preserves file permissions.

An example for UN*X users is shown below assuming you have changed to the installation directory:

./jGnashFx

Mac OS X: Run the application file you created per the Mac installation instructions.

Building and Development

Travis-CI Build Status

Development Tools

The IDE used for the development of jGnash is:

Building jGnash:

Gradle is used as the primary build system for jGnash. The Gradle Wrapper is included (gradlew shell and .bat files) so that you do not need to install Gradle. The Wrapper will automatically download the necessary dependencies.

Note

Depending on your OS (almost always Windows and OSX) the JCE Unlimited Strength Jurisdiction Policy Files for Java 8 are needed for the unit tests to complete correctly. If you do not want to install these files or are restricted by your locale, modify the test build or disable tests. jGnash uses encryption for client / server communication and unit tests are performed to prevent regressions.

To build jGnash you’ll need the following software installed and correctly configured on your system:

1. JDK 8u71 or later.

If you are using JDK 9 or 10, you’ll need to do additional installation steps.

If you are building with a recent 64 bit Linux system, you may need to enable Multilib/32 Bit support capabilities. Otherwise, the Gradle build may fail when building the windows executables.

To create the distribution zip file, start at the main directory and run the gradle task to clean and create the distribution:

Building on Windows:

gradlew clean distZip

Building on UN*X or Mac OS X:

./gradlew clean distZip

This will run the gradle tasks necessary to run core tests and create the distribution file. The distributable zip file will be produced at the root of the build directory called jGnash-version-bin.zip.