Quick start instructions for installing the Cutting Board application


  1) The Cutting Board application assumes that you have a compatible version of java already installed on your computer (at least java 19 is a good choice). 
     To install on a linux-like host (e.g. a Debian derivative):
     a) sudo apt install openjdk-19-jre openjdk-19-jdk
     b) sudo apt-cache policy openjdk-19-jre openjdk-19-jdk
        java --version

  2) Unzip the cuttingboard directory within the cuttingBoard.zip file to a desired location per operating system (e.g. D:\ or "C:\Program Files\" or /home/<user>).  
     We'll call the resulting directory, .../cuttingboard, the PROGRAM_DIR.
     a) This should produce the following files in the PROGRAM_DIR:
        cuttingboard.jar, CuttingBoard.bat, launchCuttingBoard.vbs, launchCuttingBoard.sh, and this README_START_CuttingBoard.txt
     b) On a Windows desktop:
        If a Windows-protected location is used (e.g. "C:\Program Files\cuttingboard\"), 
        open up permissions for the target directory and all of its contents by:
 	    i)   right-click on the target directory and select: properties -> security tab -> Advanced
 	    ii)  select the Change Permissions button,
        iii) select the Add button and then the Select a principal link on the Principal line
        iv)  enter your account name (e.g. user@outlook.com) in the object name box and select the Check Names button to lookup your account; then select the OK button
        v)   back on the "Permission Entry for <target directory>" panel check both the "Full Control" and "Only apply these permissions to ..." check-boxes
        vi)  select OK on each panel to close
     c) On a unix-/linux-based desktop: 
        Make the shell script executable by:
        chmod 755 $HOME/cuttingboard/launchCuttingBoard.sh 
		   
  3) Application execution.
     a) For a Windows desktop, you may execute the application via any of the following methods:
        i)  Open a command terminal (type "cmd" in the search box), cd to the directory PROGRAM_DIR, and execute "java -jar cuttingBoard.jar"
        ii) Double-click on the launchCuttingBoard.vbs file after navigating to the PROGRAM_DIR within the File Manager
     b) On a unix-based host, you may execute the application via:
        i) $HOME/cuttingboard/launchCuttingBoard.sh

  4) On the first startup, the application will ask you:
     a) Which directory should be used to store its data (e.g. database, support files, ...).  
        We'll call the resulting directory, the DATA_DIR (e.g. C:\Users\<user>\AppData\Local\CuttingBoard is the default on Windows)  
        Ideally, this should be a different location from PROGRAM_DIR.
     b) Whether you wish to have a desktop shortcut automatically created for subsequent startups.
	 c) If you wish to manually create a desktop shortcut at a later time,
        i)    the command-line value is:  PROGRAM_DIR\launch_cuttingBoard.vbs    (e.g. "C:\Program Files\cuttingboard\launchCuttingBoard.vbs")
        ii)   the starting location value is the directory path:  PROGRAM_DIR    (e.g. "C:\Program Files\cuttingboard")
        iii)  the icon can be set to the application's cuttingBoard.ico file or any other you may prefer 
             
Configuration

  1) Once you have the application running, you may modify settings (i.e. configuration preferences) via the tools > preferences menu item     
             
  2) If you'd like to retrieve nutrition information for recipe ingredients: 
     a) Request your free personal FDC API KEY from the US Gov't FoodData Central web site: https://fdc.nal.usda.gov/api-key-signup.html
     b) When the app's Nutrition menu option is selected and the Query Button is first pressed for a food, you will be prompted to enter this key if it doesn't already exist
        
  3) The first time the application is executed, the following files are automatically created in the PROGRAM_DIR:
     a) Configuration file: preferences.xml
     b) Debug trace / log configuration file: log4j2.xml
     c) License files: LICENSE.GPLv3 and LICENSE.other
  
  4) The application's configuration file, preferences.xml, contains settings. A few examples are:
     a) FdcApiKey (the FDC API KEY), and 
	 b) ArtifactDirectory (i.e. DATA_DIR), under which sub-directories reside such as:
        i)  database (for the app's database), and 
	    ii) export (for the app's exported data files of the form *.xml)
	      
  5) The application's debug trace / log configuration file, log4j2.xml, contains debug logging settings:
	 a) This log configuration file's settings may be found at: https://logging.apache.org/log4j/2.x/manual/configuration.html#XML
	   
  6) To observe the application's debug trace log (which displays application messages during its processing):
     a) Select the application menu items, Show -> Console, to observe all post-initialization processing, or
     b) Execute the application from a command prompt (e.g. enter "cmd" via the Windows "Run Command Box") to observe all processing including initialization: 
        java -jar cuttingBoard.jar
     c) To change the level of information logged. from within the application select:  Tools > Preferences > Edit > Preferences > Logging > Level

Troubleshooting

  1) If the application doesn't launch (i.e. you don't see a GUI and the launch script just returns), 
     try running the application via "java -jar cuttingboard.jar" at the command line. 
     a) If you see a java.lang.UnsupportedClassVersionError exception, update your installed java to the latest available version.
        This issue can happen because a java application simply won't launch if the host's Java Runtime doesn't support that application's newer class file version.      