Quick start instructions for installing the Cutting Board application


  1) Java Installation
     A) If installing from the zip bundle, the Cutting Board application assumes that you have a compatible version of Java already installed on your computer (at least Java 25 is a good choice). 
        To install on a linux-like host (e.g. a Debian derivative):
        a) sudo apt install openjdk-25-jre openjdk-25-jdk
        b) sudo apt-cache policy openjdk-25-jre openjdk-25-jdk
           java --version
        To install on a windows host:
        a) Access https://www.oracle.com/java/technologies/downloads (or any desired open source alternative) and install per site's directions.
     B) If installing from the msi bundle, an appropriate Java run-time is automatically included (so no need to download anything extra)

  2) Application Installation
     A) 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.ps1, launchCuttingBoard.vbs (deprecated), 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
     B) Double-click on the msi bundle and follow the prompts. If you chose an installation directory (e.g. "C:\Program Files") that's different than the default, per user, 
        location (e.g. "C:\Users"), and it requires Administrator privilege, you may have perform one of more of the following procedures to successfully install.
        A) Ensure your user account is a member of the Admnistrators group
        B) During installation, if the MSI installer fails (a lack of administrative privileges error):
           a) create an EntangledBits directory,
           b) select that directory, right-mouse click and select the properties option,
           c) select the security tab,
           d) select Users (or your account),
           e) select the edit button,
           f) select Users (or your account) and check the grant Full control checkbox, and
           g) select Apply, then OKs to exit sequence.
        C) After installation, to execute the application via the shortcut, you may have to enable administrator privileges:
           a) right-click on the shortcut, 
           b) select the properties option, 
           c) select the advanced button, 
           d) check the "Run as Administrator" checkbox, and
           e) select Apply, then OKs to exit sequence. 
		   
  3) Application execution.
     A) For a Windows desktop, you may execute the application via any of the following methods:
        a) Open a command terminal (type "cmd" in the search box), cd to the directory PROGRAM_DIR, and execute "java -jar cuttingBoard.jar"
        b) Navigate to the PROGRAM_DIR within the File Manager: 
           Left-click on the launchCuttingBoard.ps1 file, then right-click and select the "Run with PowerShell" option
           Or, on older installations, double-click on the launchCuttingBoard.vbs file
     B) On a unix-based host, you may execute the application via:
        a) $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 or C:\ProgramData\CuttingBoard are typical defaults 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,
        a) the command-line value is:  powershell.exe -NoProfile -ExecutionPolicy Bypass -File "PROGRAM_DIR\launchCuttingBoard.ps1"    (e.g. "C:\Program Files\cuttingboard\launchCuttingBoard.ps1")
           Or, on older installations:
           the command-line value is:  PROGRAM_DIR\launch_cuttingBoard.vbs    (e.g. "C:\Program Files\cuttingboard\launchCuttingBoard.vbs")
        b) the starting location value is the directory path:  PROGRAM_DIR    (e.g. "C:\Program Files\cuttingboard")
        c) 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:
        a) database (for the app's database), and 
	     b) 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

  7) To launch the application from a windows command-line:
     A) Change to the directory where the application was installed, for example:
        D:
        cd D:\development\source\CuttingBoard\operation\run
     B) Start the application via its launch script, for example:
        C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -File "D:\development\source\CuttingBoard\operation\run\launchCuttingBoard.ps1"
        C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\development\source\CuttingBoard\operation\run\launchCuttingBoard.ps1" -logToFile 1
   
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.
              
  2) Some windows anti-virus products can overzealously (and erroneously) flag the application as a potential problem during the upgrade procedure during shortcut generation.
     In this case, defining an exception within your anti-virus product for the cuttingboard.lnk file and / or the launchCuttingBoard.* scripts will help. 