
		      *** CRUSH-2 on Windows 7/8/10 *** 
	

			       Attila Kovacs 
		         <attila[AT]sigmyne.com>

		       Last updated: 21 February 2017


Table of Contents
=================

1. Introduction

2. Installation

 2.1. Java
 2.2. Download CRUSH
 2.3. Standard installation (Administrator)
 2.4. Custom installation (any user)

3. (optional) Java runtime configuration

 3.1. Runtime configuration files
 3.2. Runtime configuration syntax

4. Path names in CRUSH pipeline configuration


 
###########################################################################
1. Introduction
###########################################################################

As of version 2.34-2, CRUSH provides improved support for Windows.

This document is aimed specifically at using CRUSH on Windows OS. It is not
a standalone guide. Rather, it is meant to be used together with the main
README, with this document pointing out only the important differences 
for the Windows OS.



###########################################################################
2. Installation
###########################################################################


2.1. Java
=========

   Make sure you have Java installed. To check if you have Java, open
   a command prompt (CMD) and type 'java'. If Java is installed, you will
   see an information screen on usage. If you see a message about the
   command not being recognized instead, then you need to install Java first.
   
   To install Java, grab a JRE (Java Runtime Environment) from www.java.com. If
   you have a 64-bit Windows installed, you need decide if you want a 32-bit or
   64-bit JRE. (For a 32-bit Windows OS, just grab the standard 32-bit JRE).

   The pros of the 64-bit JRE is mainly that you can use more RAM (over 2GB),
   which may be handy if you want to reduce a large volume of data with CRUSH. 
   On the flipside, the merit of the 32-bit JRE is that it works nicer with 
   your browser in general. (You can also install both the 32-bit and 64-bit
   JREs side-by-side -- but then chose carefully on which of the two is the
   default, and which you will want to use with CRUSH). If in doubt about your
   default Java, just open a command prompt (CMD) and type:

     > java -version



2.2. Download CRUSH
===================

   Download the latest CRUSH package from:

     www.submm.caltech.edu/~sharc/crush
 
   You probably want to get the executable installer (.EXE).



2.3 Standard installation (Administrator)
=========================================

   Run the installer (crush-2.xx-x.exe) as Administrator (in Windows Explorer, 
   right-click on the CRUSH installer and select 'Run as Administrator' in the 
   pop-up menu). It will install CRUSH into 
   
     C:\Program Files\crush

   add crush to the search PATH, and install the show tool in the Start Menu. 
   Provided you have Java installed, you should be ready to go. Open a 
   command prompt (CMD), and type 'crush'. You should see a simple help screen
   on using crush. (You can also try 'CRUSH show tool' in you Start Menu -- it
   should be ready to go also).



2.4 Custom installation (any user)
==================================

   If you do not have Administrator privileges, or run the installer not as 
   Administrator, the installer will set up crush inside your profile 
   directory, e.g. into:

     C:\Users\John Doe\crush
   
   After the installer is finished, you may move the extracted crush folder to 
   anywhere you like, and use crush from inside that directory or otherwise by 
   specifying the full path to it, e.g.:

     C:>"\Users\John Doe\crush\crush" hawc+ -flight=360 66

   Optionally, you may want to edit the default search path to include the
   directory in which CRUSH is installed. Open the Control Panel, search for
   and select 'System', then on the left tab, click on 'Advanced System 
   Settings'. Click the 'Environment Variables', and edit the 'PATH' variable.
   Add the CRUSH directory as your new entry at the end. 




###########################################################################
3. (optional) Java Runtime Configuration
###########################################################################

   As of version 2.34-2, CRUSH behaves very similarly on Windows as it does
   on POSIX (e.g. Linux, BSD, or MacOS X) systems.

   This means, that CRUSH will attempt to automatically configure optimal
   runtime settings for your system. If you want to exert more control over 
   the runtime configuration, you can do it in a similar way as you would on a 
   POSIX OS.
   
   Thus, this section covers only the important ways the Windows 
   configuration differs from the usual POSIX one. For further details, 
   please look at the 'Java Runtime Configuration' section of the main README.



3.1. Runtime configuration files
================================

   You can place systrem default runtime settings inside the

     C:\Program Data\crush2\startup

   directory. The settings should be stored in batch (.bat) files placed
   in that directory. CRUSH will 'call' all batch files in that directory
   before Java is launched. However, there is no specific order in which the
   files are called, if and when multiple config files are present.

   You can also add user-level configurations, by placing similar batch (.bat)
   files inside a .crush2\startup\ directory inside your user profile. E.g.:

     C:\Users\John Doe\.crush2\startup\

   The user-level configuration files will be parsed AFTER the system-wide
   default configurations stored in 'C:\Program Data\crush2\startup'.

   You may also add program-level runtime configurations, if for example
   you want to run 'show' with different settings than used for the other 
   programs of the CRUSH suite. Accordingly you can place batch files under 
   
     ... startup\show\
  
   both for system-wide (in C:\ProgramData\crush2) and user-specific ways 
   (e.g. in C:\Users\John Doe\.crush2\). Such program-level files will be
   parse AFTER the universal settings above, with the system-wide settings
   first, followed by any user-specific ones.



3.2. Runtime configuration syntax
=================================

   As mentioned, the runtime configuration files are basically regular
   Windows batch (.bat) files that are called each time one of the CRUSH
   tools is launched. Unfortunately, the Windows command interpreter is
   not as flexible as say bash. This means that you have to pay special
   attention and follow the Windows command rules strictly. Even the smallest
   errors can break the CRUSH startup process entirely.

   A typical runtime configuration file may contain entries like:
 
     set JAVA=C:\Program Files\Java\jre6\bin\java
     set DATAMODEL=64
     set USEMB=4000
     set JVM=-server
     set EXTRAOPTS=-showversion

   (You can read more about these settings in the 'Java Runtime 
   Configuration' section of the main README.)

   Notice, that none of the values contain quotes. Unlike in bash, where the
   quotes are optional (even encouraged) and are automatically removed 
   (unless escaped), in Windows any quotes are retained as literal parts of 
   the assignment, and their accidental presence will likely break the 
   functionality of CRUSH.

   You can also set other environment variables that may be used by crush, 
   such as:

     set CRUSH_NO_UPDATE_CHECK=1
     set CRUSH_NO_VM_CHECK=1

   (Again, consult the main README on what these do, and why you probably
   should not use them.) 





###########################################################################
4. Path names in CRUSH pipeline configuration
###########################################################################


   Path names generally follow the rules of your OS. However, in order to
   enable platform independent configuration files, the UNIX-like '/' is
   always permitted (and is generally preferred) as a path separator. As a
   result, you should avoid using path names that contain literal '/' 
   characters (even in quoted or escaped forms!) other than those separating 
   directories.

   Since CRUSH allows the use of environment variables when defining settings
   (see above), you can use {@HOMEPATH} for your user folder under Windows. 
   Or, {#user.home} has the same effect universally, by referring to it as 
   the Java property storing the location of the user's home folder.

   The tilde character '~' is also universally understood to mean your home  
   folder. And, finally, the UNIX-like '~johndoe' may specify johndoe's home 
   directory in any OS as long as it shares the same parent directory with 
   your home folder (e.g. both johndoe and your home folder reside under a 
   common '/home' or 'C:\Users').

   Thus, any of the following path specification may be used in the CRUSH
   pipeline configuration:

       "~\My Data"                    # Using the '~' shorthand
       "{$HOMEPATH}\My Data"          # Using environment variables
       "{#user.home}\My Data"         # Java properties
       D:/data/Sharc2/2010            # UNIX-style paths
       D:\data\Sharc2\2010            # proper Windows paths
       "~John Doe\Data"               # relative to another user



===============================================================================
Copyright (C)2017 -- Attila Kovacs



