The below assumes that you use csh (or tcsh).  If you use another shell, similar instructions apply.

• requirements

 
• below, $HOME refers to your home directory.

 
• the JR_HOME environment variable must be set to the directory in which JR was installed.  E.g., 

    setenv JR_HOME "/usr/local/jr"

(So you don't have to type the above command on each login, consider placing it in $HOME/.cshrc.)
 

• the PATH environment variable must be set to include $JR_HOME/bin.  E.g.,

   set path = ("$JR_HOME"/bin $path)

(Consider placing this command in $HOME/.cshrc.)
 

• JR requires JDK version 1.6.xx. The location of the `javac' translator and the `java' JVM must be in your search path (i.e., the PATH environment variable).  Be sure that if your search path specifies multiple Java implementations, that you put this JDK version early enough in the search path so that the correct Java tools are found.
  
 
• JR requires that the location of `perl' be in your search path (i.e., the PATH environment variable).

• JR requires that the location of `csh' be in your search path (i.e., the PATH environment variable).  If your system does not have csh installed (as one might find on Ubuntu Linux), then you can install csh or ask JR to use a different shell.  E.g., in bash,
  

                    (Consider placing this command in $HOME/.bashrc.)

• single virtual machine programs require nothing additional.
  
 
• multi-VM programs (single VM programs will still work with these settings)
  
 
1. $HOME/.cshrc needs to contain                                                                                                                                                       
setenv CLASSPATH .:"$JR_HOME"/classes/jrt.jar:"$JR_HOME"/classes/jrx.jar

(It also first needs to set JR_HOME as shown above. and it also needs to set PATH to include the location for  `perl' and `java' and `javac' as shown above.  If you needed to set JRSH above, then that command needs to be in your .bashrc file. )


2. To run multi-VM JR programs that use Swing or AWT, $HOME/.cshrc needs to contain                                                                                                                                                       
setenv DISPLAY :0.0


3. The JR implementation uses rsh to create virtual machines.  The rest of this item applies only to UNIX-based systems.  JR's use of rsh requires that  $HOME/.rhosts on the target machine (i.e., the machine named in `new cap vm() on "machinename"') contains an entry for the machine on which the vm creation is initiated.  Details are installation dependent, but here are typical cases.
• Always include localhost as a separate entry.
• In a NFS environment with many hosts, machine names are often grouped together.  For example, in UC Davis's CSIF, all CSIF systems can be specified by a single entry (+@csifhosts).
• the entire .rhosts file in such an environment will contain the two lines:
  
          localhost
          +@csifhosts
   
• In a non-NFS environment, typically you will need to list each host name as a separate entry. For example, if you want to run on hosts named m1 and m2
  • the entire .rhosts file in such an environment will contain the three lines:
    
            localhost
            m1
            m2
 
4. Verify that rsh works independent of JR!
• on machine A give the following commands, where B is the name of another machine
• `rsh A hostname', which should output A's name.
• `rsh B hostname', which should output B's name.
  
• `rsh localhost hostname', which should output A's name.


5. Verify that environment variables are set correctly.
   
• if A is a UNIX-based system, give the following commands,
• `rsh A setenv'; make sure that PATH, CLASSPATH, and the JR environment variables are set properly.
• `rsh A jrc -version'; make sure that this works and gives you the right version of JR.
• `rsh A which jrrun'; make sure that this works and gives you the right version of JR.
• `rsh A jrrun -version'; make sure that this works and gives you the right version of JR.
• `rsh A which java'; make sure that this works and gives you the right version of Java.
• `rsh A java -version'; make sure that this works and gives you the right version of Java.
• `rsh A which javac'; make sure that this works and gives you the right version of Java.
• if A is a Windows system, give the following commands,
• `rsh A cmd /c set'; make sure that PATH, CLASSPATH, and the JR environment variables are set properly.
• `rsh A cmd /c jrc -version'; make sure that this works and gives you the right version of JR.
• `rsh A cmd /c jrrun -version'; make sure that this works and gives you the right version of JR.
• `rsh A cmd /c java -version'; make sure that this works and gives you the right version of Java.
• Also, repeat the above tests using localhost instead of A.


6. JR can also use ssh instead of rsh.  For our CSIF here at UCD, we use OpenSSH; other ssh's will be similar in spirit, but details will likely differ.  (Thanks to UCD CS support staff for help on ssh and these instructions.)
• Setup  ssh so it works between CSIF hosts without asking for a password.
  
• Specify that JR should use ssh (the next line is a good candidate for  your ~/.cshrc file)
  setenv JRRSH /usr/bin/ssh
• Handle localhost specially.  In your ~/.ssh/config file, add the line
  NoHostAuthenticationForLocalhost yes
• Handle X11Forwarding specially.
  
• In your ~/.ssh/config file, add the line
  ForwardX11 no
• Be sure to set DISPLAY as shown in step 2.
• Disable X11 access control checking via the command
     xhost +
  or if you do this in your $HOME/.cshrc use the command
     xhost + >& /dev/null
  (be sure that the xhost command is in the search path at that point in .cshrc)
• Note: these settings might disrupt your usage of some other application, so you might need to change them back.
• Test that ssh is properly configured by running tests similar to those given above for rsh, e.g., `ssh A hostname'.  This command might question you about the authenticity of a particular host and prompt you (type `yes') the first time you run it for a particular host, but shouldn't on subsequent times.
  


• JR program organization
  
• place class c in the file c.jr (this is the simplest way; or follow Java conventions)
• place the program's main method in a public class.


• editing JR programs
• vim
  
•  syntax file for JR that provides keyword highlighting, etc. Thanks to  Francois Kilchoer of L'Ecole d'ingénieurs et d'architectes de Fribourg/Hochschule für Technik und Architektur Freiburg for developing this useful script.  A few additional notes (which might be incorporated in the next version of jr.vim):
• UNIX users: Run "dos2unix jr.vim" before using the file.
• UNIX users: If you don't want to (or don't have root access needed to) modify the files in /usr/share/vim/vim63/ (since that might affect other users), you can simply
• create (if they don't already exist) the directories ~/.vim, ~/.vim/syntax, and ~/vim/ftdetect.
  
• copy jr.vim to ~/.vim/syntax.
• create the file ~/.vim/ftdetect/jr.vim that contains the "au" line in the instructions for syntax file for JR.
• (The above follows the directions under "MAKING YOUR OWN SYNTAX FILES" on the vim syntax page
  and under "*new-filetype*" on the vim filetype page.)
  
  
• emacs
  
• JR mode that provides keyword highlighting, etc. Thanks to Bryan W. Bell for this contribution.  Note that highlighting isn't perfect, but it works in many cases.  If someone wants to improve on this "jr-mode", please let  us  know.
  
• A less pleasing alternative is to just use emacs's "java-mode".  That works pretty well (although it doesn't know about JR keywords, such as send, so it won't highlight those).  To get "java-mode" automatically for JR files, put the following in your emacs startup file (e.g., ~/.emacs on Linux):
  

• other editors.  Please let us know about any similar scripts, etc. for other editors and we'll list them here.
  
 
• viewing JR programs
• a2ps
  
•  style sheet for JR Thanks to  Francois Kilchoer of L'Ecole d'ingénieurs et d'architectes de Fribourg/Hochschule für Technik und Architektur Freiburg for this contribution. 
 
• basic translation and execution -- the jr  and jrrun scripts, and the jrgo and jrgox scripts
• for many JR programs, the jr script (provided with the JR distribution) is sufficient to translate and execute the JR program.
• the jr script assumes all files with .jr suffix (i.e., *.jr) in the current directory are part of the program
• invoke the jr script via: `jr name_of_main_class [arguments to JR program]'
• caution: the jr script uses the jrGen subdirectory; jr deletes jrGen each time jr is run.
  
• the jrrun script will reexecute (without retranslating) the JR program
• invoke the jrrun script in the same way as the jr script: `jrrun name_of_main_class [arguments to JR program]'

 
• in many cases, the jrgo and jrgox scripts can be used instead of jr and jrrun.  These scripts attempt to automate finding the name_of_main_class and then invoke jr or jrrun with that name, so that the user can simply say
• `jrgo [arguments to JR program]' to translate and execute
• `jrgox [arguments to JR program]' to reexecute (without retranslating) the JR program
• (jgo and jgox, which work similarly for plain Java programs, are also provided in the JR distribution.)


• some JR programs that use generics (e.g., ArrayList<Integer>) will generate warning messages from javac.  For example, translating X.jr will give one or more messages like
     Note: jrGen/X.java uses unchecked or unsafe operations.
     Note: Recompile with -Xlint:unchecked for details.
  These warnings are innocuous.
   
• file redirection works with the jr and jrrun scripts (and with the jrgo and jrgox scripts)
• example: `jrrun main > zz' saves the standard output of the JR program in the file zz in the current directory.
• however, redirection of standard error will redirect error messages from the tools from which jr or jrrun are built (e.g., jrc or javac) and any standard error output from the JR program

 
• (JR versions 1.x used rmic at translation time and provided a jr_rmic command and, to speed up translation, cached some of those files.  This version of JR follows Java 1.5's lead and does the rmic step during program execution time.  Hence, there is no longer a separate jr_rmic command.)
  
 
• more advanced -- if you need to do something fancy
• the following commands require CLASSPATH and PATH to be set as indicated above under multi-VM; for single VM programs, the settings can be done via direct commands to the shell, but for multi-VM programs, they need to be done within the $HOME/.cshrc file.  CLASSPATH can also be set differently as indicated below.  (However, that setting pertains to the current shell, not to remote VMs, which use CLASSPATH from $HOME/.cshrc file only to locate JR's jar file.)

 
• translating JR to Java
• example: `jrc a.jr' creates jrGen/a.java
• translating Java to bytecode
• example: in the jrGen directory, `javac a.java'
• executing the program
• for single-VM programs, the command `java edu.ucdavis.jr.jrx.JRX_impl name_of_main_class [arguments to JR program]' can be given
• in the jrGen directory
• in the current directory
• this form is useful when an argument to the JR program contains a pathname relative to the current directory.
• this form requires that jrGen be in CLASSPATH, e.g., `setenv CLASSPATH jrGen:$CLASSPATH'.
• in any directory, provided that CLASSPATH includes the complete pathname for the appropriate jrGen directory.
 
• for multi-VM programs, the above also applies, but the command needs to include any non-default settings of the environment variables JRSH, JRSHC, and JRRSH. For example, on our Linux system here, we use, e.g.,
          java -DJRRSH=/usr/bin/ssh edu.ucdavis.jr.jrx.JRX_impl Test
  On a Windows system here, we don't need to specify the value of JRRSH since the rsh we use is called `rsh', which is the default.
• setting an option for the JVM (i.e., the "java" command). Use, e.g., in csh
          setenv JRJO -Xmx2000m
  All JVMs that JR creates (so, all JRVMs) will be passed this option when used with the regular JR commands (jrgo, jrrun, etc.). (JRJO is for "JR's Java option".) This option has been lightly tested, but it seems to work fine. If you give a bad parameter for JRJO (one that java doesn't understand), you'll probably get a somewhat cryptic message like
          Cannot create virtual machine on main host ... exiting!
  


• notes:
• The version number of the JR translator and JR RTS can be obtained by executing the commands:
• `jrc -version'
• `jrrun -version'
• The JR implementation (i.e., jrc and therefore all tools, such as jr and jrgo, that use it) doesn't support separate
  compilation, i.e., you need to compile all .jr files for a given program together in single jrc (or jr or jrgo) command.  As a consequence, you can't create packages of JR classes.  (JR code can import packages of Java classes.)
  
• JR program execution sometimes (e.g.,  sometimes when you interrupt (^C) multi-VM programs) leaves UNIX processes running java around (visible via ps),  which you might need to kill by hand (use kill).
• Non-main JR VMs execute in the home directory rather than the current directory, which might make a difference if the JR program uses relative pathnames for files. (This behavior is consistent with SR's behavior.)