CRUSH-2 on Windows 7/8/10

Author: Attila Kovacs <attila[AT]sigmyne.com>

Last updated: 5 January 2018


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)
    • 2.5 Installation from the archive (ZIP or tarball)
  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 -version

If Java is installed, you will see printed on the console something like:

java version "1.8.0_121"
java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-bit Server VM (build 25.121-b13, mixed mode)

If, instead, you see a message about the java not being a recognized command, then you need to install Java first.

If you have a 64-bit Windows, it is recommended that you use a 64-bit Java (JRE or JDK) to run CRUSH. You can install the 32-bit and 64-bit JREs side-by-side. When both the 32-bit and 64-bit versions are installed, the 64-bit one should be default (which you can confirm by printing the version info as shown above), and your browser should be happy too..

To install Java, grab the desired JRE (Java Runtime Environment) from

https://www.java.com/en/download/manual.jsp

2.2. Download CRUSH

Download the latest CRUSH package from:

http://www.sigmyne.com/crush

You probably want to get the executable installer (.EXE). If that does not suit you, you can also download one of the archives (ZIP or tarball).

2.3 Standard installation (Administrator)

Run the installer as Administrator (in File 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 and/or you run the installer normally (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.

2.5. Installation from the archives (ZIP or tarball)

Unpack the archive. In the extracted crush directory, run windows\install (.bat) either as Administrator (for complete system-wide install) or as user (to install in user's profile directory). It works the same as the Windows installer (see above).

After the installation is complete, you can delete the crush directory that was extracted from the archive.

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. inC:Doe.crush2`). Such program-level files will be parsed 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 (preferred)
D:\data\Sharc2\2010            # proper Windows paths
"~John Doe\Data"               # relative to another user

Copyright (C)2017 -- Attila Kovacs