Guidance on installation and downloads

The only installation I have performed was on a Windows XP and a Windows 7 (64 bit) machine, so I will describe that.

• Download and install the latest Java Runtime Environment (JRE) from Sun/Oracle:

  The results of installing the JRE are like these:
  
  

  • A directory C:\Program Files\Java\jre7 was created with files/directories in it.
  • Java™ Control Panel got created or updated in the Windows Control Panel Window.

• Getting jars, sources, and kaw_manual_7 :

-----------
You can get the executables, sources, and a kawDoc manual from the download page of this project. This is one zipped "Windows" directory called Kaw7_release.zip, which contains an outer folder Kaw7_release and 3 inner folders: jars, src, kaw_manual_7, the last folder being a kawDoc.

The MD5 for the big zip:

FILE		MD5
Kaw7_release.zip		a2845b9e050793b8dcdb155360d289dc

Available: here (I think the download button is working, but in any case heed the warning below).

Download must be Kaw7_release.zip to be the latest version.
-----------

The executables kawRelease7.jar and other/other.jar in the jars folder should stay in the same folder (i.e. directory), with inner directories unaltered, to allow jars to use each other as "libraries" (see the manifest files of each jar for details).

Kaw.7 is a desktop application, but the multiple-jar structure is a way of hinting at a library-way of thinking. kawRelease7.jar has the core functionality. The first extension jar, other.jar has something to expand Kaw.7 functionality. Typically what I do is unzip a .jar with extra functionality so its classes and class directory structure lies in other/. Alternatively, you could augment (i.e., recompile) other.jar with extra services.

other.jar currently has a MidiPlayer application (source released), the SDK libraries for which are now based on the GERVILL midi synthesizer (a major upgrade in MIDI capability that Java 7 sdk has over previous Javas. See http://java.net/projects/gervill/pages/Home.)

• Ways of setting up:

Launching kawRelease7.jar by double-clicking its file icon or a "shortcut-To" icon:

• Create a directory like E:\Kaw7_release by unzipping the Kaw7_release.zip there (it's that folder zipped). You don't have to call the folder this.

  For the sake of an example, let's say E:\ refers to a memory stick. The only important thing to remember about the jars is that they should reside on the same media as your kawDocs will go. However, DON'T place the jars in or around the rootForSerials\NesterAppLand directory (which Kaw.7 creates). Doing so causes Kaw.7 to lose capabilities.

• Go to jars folder and double-click kawRelease7.jar file icon, which can directly launch the application, given Java JRE (of at least 1.7.0_1) is installed on your system. A license acceptance gate should be the first thing you see.

  Creating a "shortcut" to kawRelease7.jar and placing that shortcut on the "desktop" is also reasonable. With one hard-drive, you could just use a shortCut on the "desktop" to launch the jar. With two hard-drives (or a hard drive and memory stick), a "different-media" setup is possible described next.

Launching kawRelease7.jar using a .bat file (different-media setup):

• Using the ".bat" allows you to launch kawRelease7.jar from different media than where it is installed, while still ensuring that the appropriate media is used as Kaw.7's "home base".
• Unfortunately, there are several ways to use a .bat file to launch Kaw.7 that won't work with respect to that last intention, so I'll describe one particular way that does work. For the description, assume the shortcut will be on C:\ (e.g. the "desktop") and the kaw jars are on E:\ (e.g., a memory stick or another drive).
• Create a batch run file (i.e. a ".bat" file) IN THE SAME DIRECTORY as kawRelease7.jar and the other jars. I'll call the .bat file start.bat. The batch file contains something analogous to next line and a line that says "pause" (You can see error messages, if any with a pause as the last command; typing SPACE bar ends the pause and closes the black console window. Change the pause line to "rem pause", if there are no errors seen. This turns the pause into a comment and you won't have to press a key to close the console window, after you've terminated a Kaw.7 session).
• 
  java -jar E:\Kaw7_release\jars\kawRelease7.jar
pause
  
  Technical Notes
  
  • This command says "run the jar file on the fully qualified path"; so your command may differ from mine in terms of the path to kawRelease7.jar.
  • To boost default memory allocation, consider using this version of the .bat content (note the single command should be on a single line, even if my html breaks the long command into two lines).
    java -Xms5m -Xmx240m -jar E:\Kaw7_release\jars\kawRelease7.jar

    The variant increases memory usage to a max of 240 meg (also check Java documentation on "X" options, if this doesn't appear to work).

    None of the documents I provide (e.g. kaw_manual_7) typically require this, even with several open at once. However, this depends on the content of the kawDocs (as well as the number of tabs). Use the memStats button on the Debug Log to investigate memory usage of open kawDocs.

  • More than one JRE installed on your system (e.g. 1.6.x and 1.7.x) may mean that your default JRE is not the right one. In that case you get a "minor version error" and the message that the "main" class is not found. You need to locate where the correct java (.exe) is and replace "java" in the batch run above by a java.
  • If there are spaces or funny characters in the path elements of either the java or the jar target, try double-quoting these arguments (e.g., "some path/etc etc/java" -Xms5m -Xmx240m -jar "some path with spaces\kawRelease7.jar" ).

• Next create a "shortcut" for/to the start.bat file, and put that in an accessible place, like the "desktop", so you can run start.bat by double-clicking the shortcut to it.
• The above advice intends the following goal: whenever kawRelease7.jar launches, the directory that houses it (which also houses start.bat) becomes the "user.dir", or user directory, for kawRelease7.jar. If you had just put a shortcut directly to kawRelease7.jar on your desktop and used it to launch the application, your desktop directory can become the user.dir, which is not accomplishing the goal.
  • Technical note:
    The definition of the System property user.dir determines where kawRelease7.jar creates the directories rootForSerials\NesterAppLand and looks for its documents. It creates them in the drive root of the user.dir directory path. Note that when the source is compiled and run within an IDE, the IDE might define user.dir the way it wants. You can tell what directory kawRelease7.jar considers the current user.dir, because the Debug Log Frame recites this after the application is launched.

• First Launch of kawRelease7.jar:

• Execute by double-clicking kawRelease7.jar or a short cut to it (i.e. same media setup) or by shortcut to a .bat ( different media setup). At this point, the license agreement "acceptance gate" comes up, which is the GNU Lesser General Public License.

-----------
You can view the LGPL license:

here

-----------

• You need to accept this license before going further. Where the license is most relevant is if you want to change and redistribute the code. There is also the inherent uncertainty of running any application on your system. The application does need to create some directories and write to the hard drive or some other media in order to be a "document builder" of some kind, but that is about as exotic as it gets.
• After accepting the license, E:\rootForSerials (as an example) was created with an inner licenses directory (which has a small .txt file in it) and an inner NesterAppLand directory with some config xml files preset. You will have to re-accept the license whenever you launch kawRelease7.jar from media that hasn't been used before (i.e. which doesn't have a rootForSerials, etc. set up on it).
• NesterAppLand houses "kawDocs" the program creates and is the default place you should put kawDocs that are meant to be read by the program. A "kawDoc" is a set of files contained in a folder in NesterAppLand as explained at about this project. Each kawDoc has its own folder. The name of the folder (i.e. directory) is not arbitrary, but is yoked to some of the files within that folder. Altering the names of folders or component files (e.g., via a file manager) will cause the kawDoc not to load.

• Setting up the program manual:

  • kaw_manual_7 is part of the overall download. Provided you can open it ok, the manual demonstrates/tests all the application's released capabilities.
  • You will need to take the directory kaw_manual_7, which was unzipped from Kaw7_release.zip and place it in the NesterAppLand directory Kaw.7 creates (e.g., cut and paste it there).
  • Once kaw_manual_7 is in place, its folder should contain:

    	kaw_manual_7.zip (the zippered-folder icon) kaw_manual_7.txt kaw_manual_7_tabs.txt a folder with a lot of structure inside it (i.e., folders for jpegs and other kawDocs).
    Directory structure of this particular kawDoc has changed since the last release to facilitate applet presentation of a kawDoc (applet libraries not in this release).

• Opening the program manual:

• Now restart the program (if it's not running). When you do this a second time (having accepted the license), you get two frames (aka windows). In the grey frame (title: kaw), LEFT-click on the ? / X button. This should open the kaw_manual_7.
• Look the manual over. There are kawDocs which notionally illustrate usage bundled (i.e. embedded) throughout. An embedded kawDoc is simply a kawDoc that resides inside another kawDoc, folder-wise.
• I think these embedded kawDocs and the "owning" kaw_manual_7 display (not exhaustively) what you can try to do with a kaw such as this. Regardless of whether the intents of the notional examples are clear, I think having them imparts a lot of information for (or against) this kaw.

------- Copyright Scott R. Chaiken, 2003-2011 (copyright excludes any copyrighted icons that I have used for illustration purposes) ---------