Difference between revisions of "Download and Installation"

(Special Note for Mac Users)
(geWorkbench Installation Instructions)
 
(136 intermediate revisions by the same user not shown)
Line 5: Line 5:
  
  
=IMPORTANT note for MacOSX (Gatekeeper function, MacOSX 10.7.3 and higher)=
+
=IMPORTANT Note for Windows (and Linux)=
 +
Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps.  Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.
  
The first time you attempt to start geWorkbench from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yesAfter this first time, on subsequent invocations you can start geWorkbench just by double-clicking on the alias or command file.
+
==Affected versions==
 +
* geWorkbench_v2.6.0_Windows_JRE7_x64.exe  (64-bit JRE7)
 +
* geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)
  
=Download geWorkbench=
+
==The problem==
As of November 6, 2013, geWorkbench downloads are being hosted on an SFTP server hosted by NCI-CBIIT.
+
When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "'''Windows error 2 occurred while loading the Java VM'''".
  
The previous download site on the NCI GForge system is no longer usable.
+
==Workaround==
 +
===If you wish to run the geWorkbench installer===
 +
Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.
  
==geWorkbench 2.6.0 (released January 22, 2015)==
+
===Instead you can just download a zip file===
 +
You can avoid the installer problems by downloading the simple Zip file
  
Please stand by while we update out scripts for the new release.
+
geWorkbench_v2.6.0_Windows_JRE7_x64.zip 
  
* [[Media:GeWorkbench_v2.6.0.md5.txt|GeWorkbench_v2.6.0.md5.txt]]
+
found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.  
  
 +
After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe]  (290,040 KB) Includes 64-bit JRE7, default 2GB max Java heap memory.
+
=IMPORTANT Note for Mac OS X=
 +
(Gatekeeper function, Mac OS X 10.7.3 and higher)
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB) Includes 32-bit JRE7, default 950 MB max Java heap memory.  For older 32-bit Windows systems (XP) and those with very limited physical RAM.
+
The following instructions appear in more detailed form, with figures, in
 +
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]].
  
 +
The Mac OS X version of geWorkbench is started using command files found in the installation directory.  There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB.  Requesting larger amounts of memory may be needed when you are analyzing very large datasets.  These command files have the form, e.g. for requesting Java memory of 4 GB, of  "'''launch_geworkbench_macosx_4G.command'''" for Mac OS X.  You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder.  Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit.  You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_noJRE&version=2.6.0 geWorkbench_v2.6.0_Windows_noJRE.exe] (288,452 KB)
+
'''The first time you attempt to start geWorkbench''' from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip]  (287,622 KB)
 
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,485 KB)
+
Detailed instructions are also available [[Download_and_Installation#Mac_OS_X_2 | below]].
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_noJRE&version=2.6.0 geWorkbench_v2.6.0_Linux_noJRE.bin]  (280,597 KB)
+
=Download geWorkbench=
  
* [http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&version=2.6.0 geWorkbench_v2.6.0_Generic.zip]  (240,045 KB)
+
==geWorkbench 2.6.0.3 (released December 21, 2015)==
  
=geWorkbench 2.6.0 - System Requirements=
+
'''Installation note''' - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.
==Java==   
 
* The Java 7 Runtime Environment (JRE7) is required.  geWorkbench will run using Java 8, but has not been fully tested in that environment. 
 
* For Windows and Linux, geWorkbench is distributed in two installer forms, one with and one without the JRE7 included.  To install a version of geWorkbench that does not include the JRE, the JRE7 must be installed separately on the machine.  
 
* On MacOSX, the Java 7 JRE is included in the installation file.
 
* The "Generic" distribution of geWorkbench does not include the JRE7.  It must be installed separately.  The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
 
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
 
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] for further details.
 
  
  
===How to choose===
+
[[Media:GeWorkbench_v2.6.0.3.md5.txt|geWorkbench_v2.6.0.3.md5.txt]] - MD5 digest of each download file
* Using an installer version of geWorkbench that inludes the JRE7 allows you to be sure that you are running geWorkbench with the correct version of the JRE.
 
  
 +
[[Media:GeWorkbench_v2.6.0.3_ReleaseNotes.txt | geWorkbench_v2.6.0.3 Release Notes]]
  
===Obtaining the Java 7 JRE===
+
[[Media:GeWorkbench_v2.6.0.3_ChangeLog.txt | geWorkbench_v2.6.0.3_ChangeLog.txt]]
* The standalone JRE7 can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads. See the section at the bottom of that page "Previous Releases - Java Archive".
 
* Note: Java 7 is also referred to as Java 1.7.
 
  
==Display Driver==
 
* This requirement pertains only to using the PCA component 3D graph viewer.
 
* When using a 64-bit JVM, the Java 3D library requires that OpenGL version 1.2 or higher be supported by your display driver.
 
  
==Memory== 
+
The files for download below have all been updated to version 2.6.0.3.
At least 4 GB is recommended.  The 64-bit JRE7 version of geWorkbench 2.6.0 will by default will request up to 2 GB of memory for the Java VM.
 
  
==Operating System==
+
===Windows===
* '''Windows XP/Vista/Windows 7/8 (32 or 64-bit)''': no special requirements.
+
Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) fileClick "More Info" and then "Run".
               
 
* '''MacOSX''': Version 10.7.3 or higher is required for compatibility with Java 7 (Intel platform only) (See special note above).
 
               
 
* '''Linux''': no special requirements.
 
  
geWorkbench, unless otherwise noted for particular components, can be run on both 32 and 64-bit operating systems and JREs.
+
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.exe]  (290,041 KB)
 +
* Includes 64-bit JRE7, default 2GB max Java heap memory.  InstallAnywhere  version.
  
==Graphics Driver==
+
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x64_zip&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x64.zip]  (290,041 KB)
At least one component, the PCA viewer, uses a Java 3D library.  When using a 64-bit JVM, the Java 3D library requires OpenGL version 1.2 or higher to be supported by the graphics display adapter in your computer.
+
* Includes 64-bit JRE7, default 2GB max Java heap memory.  Zip file version.
  
 +
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Windows_x86&version=2.6.0 geWorkbench_v2.6.0_Windows_JRE7_x86.exe] (288,452 KB)
 +
* Includes 32-bit JRE7, default 950 MB max Java heap memory.  For older 32-bit Windows systems (XP) and those with limited physical RAM.
  
==R server==
+
===Mac OS X===
Several components (SAM, DeMAND, and VIPER)  can use a local installation of R on your desktop computer.
+
[[Media:GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf|GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf]]
  
This has been tested with R versions 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.
+
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=MacOSX_x64&version=2.6.0 geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip]  (287,622 KB)
 +
* Includes 64-bit JRE7, max Java heap memory selectable by command file.
  
There are special considerations for installing a local copy of R on Windows computers.  Please see the section on this further below.
+
===Linux===
  
=IMPORTANT NOTICE ABOUT THE LICENSE=
+
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Linux_x64&version=2.6.0 geWorkbench_v2.6.0_Linux_JRE7_x64.bin] (326,484 KB)
Use of geWorkbench is governed by the rules specified in the [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.
+
* Includes 64-bit JRE7, default 2GB max Java heap memory.
  
 +
===Generic - any platform===
  
 +
[http://magnet.c2b2.columbia.edu/?q=node/44&software=geWorkbench&platform=Generic&version=2.6.0 geWorkbench_v2.6.0_Generic.zip]  (240,045 KB).  No Java JRE is included, you must supply and configure the appropriate JRE for your machine.
  
=Installation Instructions=
 
  
All three platform-specific versions of geWorkbench (Windows, Linux, and Macintosh) provide an installation wizard (generated using InstallAnywhere).
 
  
* Using an installer version of geWorkbench that inludes the JRE6 allows you to be sure that you are running geWorkbench with the correct version of the JRE. 
+
=Install and Run geWorkbench=
* You may wish to install a "no JRE" version of geWorkbench if you want to choose yourself between 32 and 64 bit JREs, or to keep up with the latest updates to the JRE.
 
* On Windows and Linux, geWorkbench was tested using installer versions which included the JRE6.  The included JREs are 32-bit versions.
 
   
 
A generic version of geWorkbench, which does not use any installer, is also available, and should run on any machine which supports Java 6.
 
  
Further information about the [http://www.flexerasoftware.com/products/installanywhere/requirements.htm InstallAnywhere requirements] are found at the Flexera website.
+
==Windows (XP/Vista/7/8/10)==
 +
===Installation===
 +
Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.
  
 +
New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0.  With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.
  
==Windows (XP/Vista/7/8)==
+
===Running geWorkbench on Windows===
   
+
====Installer versions====
===Special note for Vista/Windows 7 & 8===
+
Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.
====geWorkbench installation====
 
* '''geWorkbench installation directory''' - If you run the installer on Vista or Windows 7 or 8, the installer will prompt you to install geWorkbench to your user home directory, e.g. '''C:\Users\''username''\geWorkbench_2.5.1''', where ''username'' is your Windows login name.
 
  
====R installation on Windows====
+
====Any 64-bit version====
* '''R installation directory''' - Some geWorkbench components can make use of a locally installed version of RThere are specific considerations for installing R on Windows Vista/7/8.
+
If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0"These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.
  
We have demonstrated two methods based on the links shown below.
+
To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut").  You can then move the shortcut e.g. to your Desktop for easy access.  Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.
  
=====-Install R in user directory=====
+
==Mac OS X==
You can install R directly into your own user directory. Packages will be placed directly into the library within the installation. You just need to set the R-script location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.  
+
===Installation===
 +
* Recent testing has been on Mac OS X 10.10+ only.
 +
* As Java 7 is not available for the PowerPC platform, regardless of OS X version, geworkbench will not run on the PowerPC platform under any version of OS X.
  
  C:\Users\''user_name''\R-3.1.1\bin\Rscript.exe
+
The MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE.  No Mac installer is available for this release, instead, please follow the below steps.  
 +
 +
Please carefully read and follow these instructions:
 +
 +
1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).
  
where for ''user_name'' please substitute your own Windows login name.
+
2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or  another convenient folder.
  
=====-Install R in system directory=====
 
You can allow Windows to install R into the default system directory, e.g. '''C:\Program Files\R\R-3.1.1\'''. 
 
  
'''NOTE - If you are using a recent version of Java 6 or Java 7 you must instead install R to a directory without spaces in its path, e.g.
 
'''C:\R\R-3.1.1\'''.  This problem is fixed in the upcoming release of geWorkbench v2.5.2.'''
 
  
Set the Rscript location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.
+
===Running geWorkbench on Mac OS X===   
  
C:\Program Files\R\R-3.1.1\bin\Rscript.exe
+
1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example)Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.
  or  
 
  C:\R\R-3.1.1\bin\Rscript.exe
 
  
depending on where you installed R.
+
Right-click on the desired command file and select "Make Alias".
  
However, in this case, geWorkbench will not be able to install needed R packages into the default location because it cannot write to the system directory. However, you can circumvent this problem by setting the Windows environment variable '''R_LIBS_USER''' to an appropriate user directory, e.g '''C:\Users\''user_name''\R\win-library\3.1''' for the current release of R, where for ''user_name'' please substitute your own Windows login name.  (The proper number to use is x.y, for R version x.y.z).
+
2. Drag the new alias file e.g. to your Desktop for easy access.
  
* You can create the environment variable '''R_LIBS_USER''' by e.g.
+
3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):
** right-clicking on "Computer" in Windows Explorer,
 
** then clicking "Properties", Advanced system settings",
 
** then under "User variables" for "your_user_name", click "New...". 
 
** Enter the new variable name '''R_LIBS_USER''' and the location '''C:\Users\''user_name''\R\win-library\3.1'''. 
 
* You must create the corresponding directory structure yourself before running geWorkbench, e.g.
 
** in your home directory '''C:\Users\''user_name''''', create the new folder '''R''',
 
** then within it create '''win-library''',
 
** then within win-library create the appropriate directory e.g. '''3.1''' for version 3.1.* of R.
 
  
=====-Links to information on installing R on Windows=====
+
The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.
*'''R on Windows''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].
 
  
* '''R 32 vs 64 bit installation''' - [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].
+
After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.
  
* '''R packages directory''' - You can set the R packages directory to one in your own user space in order to gain write permission.  Please see the [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].
+
==Linux==
  
===Installer with JRE6===
+
* You may need to configure the JRE. See section below, "Java Environment Configuration".
* File: geWorkbench_v2.5.1_Windows_installer_with_JRE6.exe
 
* Includes the 32-bit Sun Java 6 JRE.
 
  
Download and double-click the installer file to begin installation.
+
===Installation===
 
===Installer without JRE6===          
 
* File: geWorkbench_v2.5.1_Windows_installer_noJRE.exe
 
* No JRE is included, you must make sure that an appropriate Java 6 JRE is installed on your system before installing geWorkbench.
 
  
Download and double-click the installer file to begin installation.
+
The Linux version of geWorkbench relies on X-Windows being installed and running. If you are running Linux on a server and e.g. you wish to view the application on a Windows desktop, you will also need to run an X-windows server on your desktop machine.  See X-Windows configuration instructions below.
  
==MacOSX==
+
After downloading, cd (if needed) to the directory to which you downloaded the installer.
  
* File: geWorkbench_v2.5.1_MacOSX_installer.zip.
+
To begin the installation, type the command for the particular version, e.g. for the installer with JRE:
* This version uses the Java 6 JRE, which is still available as an update to the MacOSX operating system. (Intel platforms only).
 
  
Double-click geWorkbench_v2.5.1_MacOSX_installer.zip to begin installation. This will extract a file called "install". Double-click on this file to install geWorkbench. 
+
"sh geWorkbench_v2.6.0_Linux_JRE7_x64.bin".
  
You may see a message '''"Install is damaged and cannot be opened. You should move it to the Trash"'''
+
This will extract geWorkbench into a new directory called geWorkbench_2.6.0.
  
The installer is not damaged, rather, this message is a consequence of restrictions imposed by the OSX Gatekeeper.  Please see the next section for a work-around.
+
If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).
 +
 
  
 +
===Running geWorkbench (Linux)===
 +
To run geWorkbench, and assuming you are using the Linux bash shell, and that you created a shortcut link during installation, issue one of the following commands from your home directory, depending on how the alias file was named: 
  
===GateKeeper===
+
    sh geWorkbench_2.6.0
In recent versions of Mac OSX (starting with 10.8), the Gatekeeper function may not allow the downloaded geWorkbench file to install.  The initial zip file can be unpacked, but the resulting "install" app may not execute.  Instead, you may see the message:
+
    or
 +
    sh rungeWorkbench_2.6.0.
 +
         
 +
Alternatively, in the directory in which geWorkbench was installed, you can start geWorkbench with the command:
 +
         
 +
    sh geWorkbench
  
'''"Install is damaged and cannot be opened. You should move it to the Trash"'''
+
==Generic==
 +
A non-installer-based version of geWorkbench is supplied in a Zip file which should work on any platform.
  
 +
File: geWorkbench_v2.6.0_Generic.zip
  
To allow geWorkbench to install, you must temporarily tell Gatekeeper to allow installation of files from "anywhere".
+
===Installation===
 +
   
 +
Unzip the file. It will create a directory geWorkbench_2.6.0.
 +
         
  
You can do this by
+
===Running geWorkbench (generic)===
  
1. Go to System Preferences, Security and Privacy
+
You must have the Java 7+ JRE installed and the JRE must be in the path for geWorkbench (see Java Environment Configuration below).
  
2. On the "General" tab select "Allow applications to download from: Anywhere".
+
====Windows====
  
3. Now run the geWorkbench installer again.
+
Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory.  The files can also be run from the command window.
  
4. After you have installed geWorkbench, the security preference changed in (2) should be set back to its original setting.
+
====Mac OS X====
 +
Double-click on one of the command (.command) files for specific sizes of Java heap memory.  The files can also be run from the command window.
 +
           
 +
====Linux/Unix====
 +
  Execute the script "launch_geworkbench.sh".
 +
     
 +
Any: Alternatively, if you have Apache Ant installed, you can type "ant run" in the geWorkbench directory.
  
 +
=R Installation for geWorkbench=
 +
Some geWorkbench components can make use of a locally installed version of R.
  
See also [http://www.bu.edu/infosec/howtos/bypass-gatekeeper-safely/ bypass-gatekeeper-safely] for other (perhaps simpler) methods to bypass Gatekeeper.
+
==R installation on Windows==
 +
* '''R installation directory''' - There are specific considerations for installing R on Windows Vista/7/8/10.
  
===R installation on Mac OS X===
+
We have demonstrated two methods based on the links shown below.
R can be installed to the default system location. 
 
* If you are running as an administrator, R will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.0/Resources/bin/Rscript.
 
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.0/Resources/Library.
 
  
===Java 6 on Mac OSX===
+
===Install R in user directory===
Recent releases of OS X such as 10.8 and 10.9 may disable the Java 6 runtime which is needed by geWorkbench.
+
You can install R directly into your own user directory. Packages will be placed directly into the library within the installation. You just need to set the R-script location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.  
  
When you first try to run geWorkbench on one of these later versions of OSX, you may be prompted by the operating systgem to install the Java 6 runtime.
+
C:\Users\''user_name''\R-3.1.2\bin\Rscript.exe
  
If this prompt does not appear, Java 6 can be re-enabled by installing the latest Java 6 update from Apple.  The most recent update (as of November 2013) is [http://support.apple.com/kb/dl1572 2013-005].
+
where for ''user_name'' please substitute your own Windows login name.
  
With the exception of a few components, geWorkbench will also run under Java 7 and Java 8. The Java 7 and 8 JREs can be downloaded from http://java.oracle.com.
+
===Install R in system directory===
 +
You can allow Windows to install R into the default system directory, e.g. '''C:\Program Files\R\R-3.1.2\'''.
  
 +
Set the Rscript location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.
  
===Notes===
+
  C:\Program Files\R\R-3.1.2\bin\Rscript.exe
* Requires Mac OS X 10.5 with updates, or 10.6+. Recent testing has been on 10.6, 10.8 and 10.9.
 
* As Java 6 is not available for the PowerPC platform, regardless of OS X version, geworkbench will not run on the PowerPC platform under any version of OS X.
 
* The compressed installer should be expanded automatically by the system.
 
  
==Linux==
+
However, in this case, geWorkbench will not be able to install needed R packages into the default location because it cannot write to the system directory.  (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\''username''\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).
  
===Installer with JRE6===
+
There are two ways to circumvent this:
* File: geWorkbench_v2.5.1_Linux_installer_with_JRE6.bin.
 
* Includes the 32-bit Sun Java 6 JRE.
 
  
===Installer without JRE6===
+
1. Use the geWorkbench '''Tools-Preferences->R Package''' directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourselfThis has the advantage that you can have a separate location for use just by geWorkbench.
* File: geWorkbench_v2.5.1_Linux_installer_noJRE.bin.
 
* No JRE is included, you must make sure that an appropriate Java 6 JRE is installed on your system before installing geWorkbench.
 
* You may need to configure the JRESee section below, "Java Environment Configuration".
 
  
===Installation===
+
2. Alternatively, set the Windows environment variable '''R_LIBS_USER''' to an appropriate user directory, e.g '''C:\Users\''user_name''\R\win-library\3.1''' for the current release of R, where for ''user_name'' please substitute your own Windows login name. (The proper number to use is x.y, for R version x.y.z). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".
You must already have installed a version of Java 1.6 or later on your Linux machine in order to run the geWorkbench installer.
 
  
The Linux version of geWorkbench relies on X-Windows being installed and running. If you are running Linux on a server and e.g. you wish to view the application on a Windows desktop, you will also need to run an X-windows server on your desktop machine. See X-Windows configuration instructions below.
+
* You can create the environment variable '''R_LIBS_USER''' by e.g.
 +
** right-clicking on "Computer" in Windows Explorer,
 +
** then clicking "Properties", Advanced system settings",
 +
** then under "User variables" for "your_user_name", click "New...". 
 +
** Enter the new variable name '''R_LIBS_USER''' and the location '''C:\Users\''user_name''\R\win-library\3.1'''.
 +
* You must create the corresponding directory structure yourself before running geWorkbench, e.g.  
 +
** in your home directory '''C:\Users\''user_name''''', create the new folder '''R''',
 +
** then within it create '''win-library''',  
 +
** then within win-library create the appropriate directory e.g. '''3.1''' for version 3.1.* of R.
  
After downloading, cd (if needed) to the directory to which you downloaded the installer.
+
===Links to information on installing R on Windows===
 +
*'''R on Windows''' -  [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Does-R-run-under-Windows-Vista_003f R FAQ entry on installation].
  
To begin the installation, type the command for the particular version, e.g. for the installer with JRE:
+
* '''R 32 vs 64 bit installation''' -  [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#Can-I-use-R-on-64_002dbit-Windows_003f R FAQ entry on 32 vs 64 bit installation].
  
"sh ./geWorkbench_v2.5.1_Linux_installer_with_JRE6.bin".
+
* '''R packages directory''' - You can set the R packages directory to one in your own user space in order to gain write permission. Please see the [http://cran.r-project.org/bin/windows/base/rw-FAQ.html#I-don_0027t-have-permission-to-write-to-the-R_002d3_002e0_002e2_005clibrary-directory R FAQ on library directory].
  
This will extract geWorkbench into a new directory called geWorkbench_2.5.1.
+
==R installation on Mac OS X==
 +
R can be installed to the default system location. 
 +
* If you are running as an administrator, R will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/bin/Rscript.
 +
* In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.
  
  
If you requested that a desktop link be created, it will be called rungeWorkbench_2.5.1.
 
 
 
Note - if you made changes to the default installation directory name, the shortcut link may just be called "geWorkbench_2.5.1" rather than "rungeWorkbench_2.5.1".
 
  
===Running geWorkbench (Linux)===
+
=Java Environment Configuration=
To run geWorkbench, and assuming you are using the Linux bash shell, and that you created a shortcut link during installation, issue one of the following commands from your home directory: 
 
         
 
    ./rungeWorkbench_2.5.1
 
    or
 
    sh rungeWorkbench_2.5.1.
 
    or
 
    sh geWorkbench_2.5.1 if the link received the alternative name (see above).
 
         
 
Alternatively, in the directory in which geWorkbench was installed, you can start geWorkbench with the command:
 
         
 
    sh launch_geWorkbench.sh
 
  
==Generic==
+
To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 must be installed and, depending on the platform configured separately.
A non-installer-based version of geWorkbench is supplied in a Zip file which should work on any platform.
 
  
File: geWorkbench_v2.5.1_Generic.zip
+
Two environment variables may need to be properly configured. These are the JAVA_HOME and the PATH variables. They should be configured to point to your own installation of the JRE7.  
  
===Installation===  
+
==Linux/Generic==
   
+
Here is an example of setting the two environment variables for a JRE installed in the directory /opt:
Unzip the file.  It will create a directory geWorkbench_2.5.1.
 
         
 
  
===Running geWorkbench (generic)===
+
PATH=/opt/jre1.7.0_71/bin:$PATH
  
You must have the Java 6 JRE installed and the JRE must be in the path for geWorkbench (see Java Environment Configuration below).
+
JAVA_HOME=/opt/jre1.7.0_71  (for use with Ant)
  
Windows: you can double click on the file "launch_geWorkbench.bat" to launch geWorkbench, or run it from a command window.
+
==Macintosh OS X==
           
+
The Mac OS X version of geWorkbench includes the Java 7 JRE.
Linux/Unix:  Execute the script "launch_geworkbench.sh".
 
     
 
Any: Alternatively, if you have Apache Ant installed, you can type "ant run" in the geWorkbench directory.
 
  
=Java Environment Configuration=
+
==Switching between different installed JREs on Windows==
 
+
If you have multiple versions of Java installed, you can set JAVA_HOME to the desired version, and if you start geWorkbench simply by double-clicking on launch_geworkbench.bat, it will use the version of Java specified there.
To run a version of geWorkbench that does not include the Java 6 Runtime Environment (JRE6), the JRE6 must be installed and, depending on the platform configured separately.
 
  
Two environment variables may need to be properly configured. These are the JAVA_HOME and the PATH variablesThey should be configured to point to your own installation of the JRE6.  
+
==Downloading older versions of Java==
 +
Previous Java versions can be downloaded from the [http://www.oracle.com/technetwork/java/javase/archive-139210.html Java archive site]Signing up for an Oracle web account is required.
  
==Linux/Generic==
+
=Java Runtime Special Exceptions=
Here is an example of setting the two environment variables for a JRE installed in the directory /opt:
+
The '''GenomeSpace webstart (jnlp) launcher application''' and the '''MarkUs molecular structure visualizer''' are unsigned Java applets.  To use either, special steps must be taken, as described below.
  
JAVA_HOME=/opt/jre1.6.0_31
+
Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.
  
PATH=/opt/jre1.6.0_31/bin:$PATH
+
In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:
 +
* http://www.c2b2.columbia.edu
 +
* https://bhapp.c2b2.columbia.edu
 +
* https://honiglab.c2b2.columbia.edu
  
==Macintosh OS X==
+
The first is for GenomeSpace, and the second and third for MarkUs.
No special Java configuration is need if you run the regular installer version of geWorkbench.  
 
  
In recent versions of OS X (including 10.8.5 and 10.9), the Java 6 JDK can be found in /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home.  Set JAVA_HOME to this if you wish to run the generic version of geWorkbench, or the Macintosh installer version from the command line rather than the app launcher.  In the latter case, see the instructions for running the generic version of geWorkbench.
+
In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.
  
A recent test on a MacBook Pro with OS X 10.9.2, which had Java 6 installed, and on which then Java 7 update 45 was also installed, showed that the installer version of geWorkbench continued to use the Java 6 installed at the location shown aboveThe same result was found when Java 8 update 5 was installed.
+
On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.
 
+
* If using Firefox, go to Downloads and right-click on the downloaded jnlp fileChoose "Open".
==Switching between different installed JREs on Windows==
+
* If using Chrome, you may see an option pulldown to Open the downloaded fileThis should allow it to run.
The installer versions of geWorkbench on Windows will use a system-specified version of Java, typically the highest version installedThey will ignore the JAVA_HOME environment variable.
 
  
If you have multiple versions of Java installed, you can set JAVA_HOME to the desired version, and if you start geWorkbench simply by double-clicking on launch_geworkbench.bat, it will use the version of Java specified there.
+
Once this has been done once, you will not be asked again.
  
 
=Typical steps in running X-windows=
 
=Typical steps in running X-windows=
Line 322: Line 304:
  
  
=Tutorial data=
+
=geWorkbench 2.6.0 - System Requirements=
 +
==Java==
 +
* geWorkbench 2.6.0 has been developed and tested using Java 7.  Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
 +
* geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
 +
* The "Generic" distribution of geWorkbench does not include the JRE7.  Java must be installed separately.  The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
 +
* geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
 +
* See the [https://www.java.com/en/download/help/sysreq.xml Java System Requirements] and [https://www.java.com/en/download/faq/java_win64bit.xml Java on 64-bit Windows] for further details.
 +
 
 +
==Special Java Requirements for Specific Components==
 +
* '''GenomeSpace''' - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application.  This in turn requires a Java JRE be installed separately on your machine.  The latest version of the Java 8 JRE may be used and is recommended.  Either 32-bit or 64-bit versions may be used.
 +
 
 +
Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.
 +
 
 +
 
 +
* '''MarkUs''' - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine.  The latest version of the Java 8 JRE may be used and is recommended.  You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows.  This is true even if you have a 64-bit version already installed for other reasons.
 +
 
 +
 
 +
There are specific steps to configure Java for these two applets.  See [[Download_and_Installation#Java_Runtime_Special_Exceptions | Java Runtime Special Exceptions]] below.
 +
 
 +
===Obtaining Java===
 +
* Standalone versions of Java can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads.
 +
 
 +
==Display Driver==
 +
* This requirement pertains only to using the PCA component 3D graph viewer.
 +
* When using a 64-bit JVM, the Java 3D library requires that OpenGL version 1.2 or higher be supported by your display driver.
 +
 
 +
==Memory== 
 +
At least 4 GB is recommended.  The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.
 +
 
 +
==Operating System==
 +
* '''Windows XP/Vista/Windows 7/8/10 (32 or 64-bit)''':
 +
** 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
 +
** 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.
 +
               
 +
* '''Mac OS X''':  As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only).  A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.
 +
               
 +
* '''Linux''': no special requirements.
 +
 
 +
geWorkbench, unless otherwise noted for particular components, can be run on both 32 and 64-bit operating systems and JREs.
 +
 
 +
==Graphics Driver==
 +
At least one component, the PCA viewer, uses a Java 3D library.  When using a 64-bit JVM, the Java 3D library requires OpenGL version 1.2 or higher to be supported by the graphics display adapter in your computer.
 +
 
 +
 
 +
==R server==
 +
Several components (SAM, DeMAND, and VIPER)  can use a local installation of R on your desktop computer.
 +
 
 +
This has been tested with R versions 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.
 +
 
 +
There are special considerations for installing a local copy of R on Windows computers.  Please see the section on this further below.
 +
 
 +
=IMPORTANT NOTICE ABOUT THE LICENSE=
 +
Use of geWorkbench is governed by the rules specified in the [[geWorkbench License | software license]]. Please make sure to read the license and understand your obligations before proceeding to download the application.
 +
 
  
[[Media:tutorial_data.zip|tutorial_data.zip]] (3.586 MB) - data files in several different formats useful for the tutorials or just trying out geWorkbench.
 
  
[[Media:Bcell-100.zip|Bcell-100.zip]] (5.256 MB) - A large (100 array) microarray dataset in the geWorkbench matrix format.  Data is from the lab of Riccardo Dalla-Favera, Columbia University, and is provided only for use in learning and testing geWorkbench.  It was obtained from experiments using Affymetrix HG-U95Av2 chips.  This file contains the same data as the previously used file "webmatrix", but with the array subsets given more descriptive names.
+
=Tutorial data=
  
 +
Tutorial data is further described on the [[Tutorial_Data]] page.
  
=Training Slides=
+
[[Media:tutorial_data.zip|tutorial_data.zip]] (3.586 MB) - data files in several different formats useful for the tutorials or just trying out geWorkbench.
A set of PowerPoint training slides for an earlier version of geWorkbench is still available, but is of historical interest only.  The PowerPoint file is available from the [[Project Documentation]] section of this site.
 
  
 +
[[Media:Bcell-100.zip|Bcell-100.zip]] (5.256 MB) - A large (100 array) microarray dataset in the geWorkbench matrix format.  Data is from the lab of Riccardo Dalla-Favera, Columbia University, and is provided only for use in learning and testing geWorkbench.  It was obtained from experiments using Affymetrix HG-U95Av2 chips.
  
 
=Download the geWorkbench Source Code=
 
=Download the geWorkbench Source Code=
Line 350: Line 385:
  
 
==geWorkbench 2.4.1 and earlier on SVN==
 
==geWorkbench 2.4.1 and earlier on SVN==
 
+
Public access to the NCI Subversion repository is no longer available.
A. '''NOTICE - to avoid a huge download, make sure to follow all of the below instructions carefully so that you only check out the development source code, not the entire project.'''
 
* The full URL for the development trunk of geworkbench at the NCI SVN site is https://ncisvn.nci.nih.gov/svn/geworkbench/trunk/geworkbench.
 
* If you are using a graphical SVN client, such as SmartSVN,
 
** the project URL is https://ncisvn.nci.nih.gov/svn/geworkbench/, 
 
** '''and you must navigate to trunk/geworkbench''' to just get the geWorkbench source code.  This process is illustrated below using SmartSVN:
 
 
 
[[Image:Geworkbench_svn_checkout.png]]
 
 
 
* For just checking out the code, you can use the username and password of anonymous/anonymous.
 
* There should be no further changes in this repository.
 
  
 
=Compiling the geWorkbench Source Code=
 
=Compiling the geWorkbench Source Code=
  
* you must have the Java JDK 6 installed on your machine - see http://java.oracle.com, under the "Java SE" link.  
+
* you must have the Java JDK 7 installed on your machine - see http://java.oracle.com, under the "Java SE" link.  
 
* you must make sure that the value of the environment variable JAVA_HOME is the directory where the JDK is installed, e.g.
 
* you must make sure that the value of the environment variable JAVA_HOME is the directory where the JDK is installed, e.g.
  C:\Program Files\Java\jdk1.6.0_45
+
  C:\Program Files\Java\jdk1.7.0_71
  
If you have Ant installed on your machine, you can just type "ant run" in the geworkbench root directory and the program will be built and run.  Ant can be downloaded from http://ant.apache.org/.  Note that installing Ant involves manually adding the Ant bin directory to the PATH variable, setting the ANT_HOME directory.
+
If you have Ant installed on your machine, you can just type "ant run" in the geWorkbench root directory and the program will be built and run.  Ant can be downloaded from http://ant.apache.org/.  Note that installing Ant involves manually adding the Ant bin directory to the PATH variable, setting the ANT_HOME directory.
  
'''Special Note for Mac Users'' - Ant has been removed from release 10.9 of OSX.  However, you can reinstall it, either from the Apache distribution or possibly using "brew" and "xcode" (we have not tried this).
+
'''Special Note for Mac Users'' - Ant has been removed from release 10.9 of OS X.  However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".

Latest revision as of 15:50, 22 December 2016

Download Instructions | License Information



This section contains instructions for downloading and installing geWorkbench.


Contents

IMPORTANT Note for Windows (and Linux)

Machines with a version of Java higher than Java 8 update 51 can not run the geWorkbench installers (executable .exe files on Windows) without taking special steps. Zip file versions of geWorkbench can be used instead, or a workaround described below can be used with the installers.

Affected versions

  • geWorkbench_v2.6.0_Windows_JRE7_x64.exe (64-bit JRE7)
  • geWorkbench_v2.6.0_Windows_JRE7_x86.exe (32-bit JRE7)

The problem

When a version of Java 8 above update 51 is installed on the machine and one of the above installers is run, the installation will fail with a "Windows error 2 occurred while loading the Java VM".

Workaround

If you wish to run the geWorkbench installer

Uninstall any copies of Java (JDK or JRE) above Java 8 update 51 on the machine, perform the geWorkbench installation, and then reinstall the version of Java you removed, if desired.

Instead you can just download a zip file

You can avoid the installer problems by downloading the simple Zip file

geWorkbench_v2.6.0_Windows_JRE7_x64.zip

found further below. This file contains geWorkbench2.6.0 and the 64-bit Java JRE7.

After unzipping the file, double-click one of the .bat files to start geWorkbench (e.g. "launch_geworkbench_winpc_4G.bat" for 4 gigabytes of Java memory), depending on how much memory you wish to request for geWorkbench.

IMPORTANT Note for Mac OS X

(Gatekeeper function, Mac OS X 10.7.3 and higher)

The following instructions appear in more detailed form, with figures, in GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf.

The Mac OS X version of geWorkbench is started using command files found in the installation directory. There are individual command files for starting with a Java memory limit of 1, 2, 4, 8 or 16 GB. Requesting larger amounts of memory may be needed when you are analyzing very large datasets. These command files have the form, e.g. for requesting Java memory of 4 GB, of "launch_geworkbench_macosx_4G.command" for Mac OS X. You can make short-cuts from these files and copy them to a convenient location such as your Desktop folder. Double-clicking on the original file or its short-cut will start geWorkbench with the requested maximum Java memory limit. You should make sure your computer has sufficient physical RAM memory, e.g. on a machine with 8 GB of physical memory you might limit your request to 4 GB of memory for Java

The first time you attempt to start geWorkbench from one of the command or alias files, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes. After this first time, on subsequent invocations of that particular command file you can start geWorkbench just by double-clicking on the command file or its alias.


Detailed instructions are also available below.

Download geWorkbench

geWorkbench 2.6.0.3 (released December 21, 2015)

Installation note - If you have a previous version of geWorkbench 2.6.0 installed, please uninstall it before installing this new version.


geWorkbench_v2.6.0.3.md5.txt - MD5 digest of each download file

geWorkbench_v2.6.0.3 Release Notes

geWorkbench_v2.6.0.3_ChangeLog.txt


The files for download below have all been updated to version 2.6.0.3.

Windows

Note - Windows SmartScreen may warn you about running a downloaded installer (.exe) file. Click "More Info" and then "Run".

geWorkbench_v2.6.0_Windows_JRE7_x64.exe (290,041 KB)

  • Includes 64-bit JRE7, default 2GB max Java heap memory. InstallAnywhere version.

geWorkbench_v2.6.0_Windows_JRE7_x64.zip (290,041 KB)

  • Includes 64-bit JRE7, default 2GB max Java heap memory. Zip file version.

geWorkbench_v2.6.0_Windows_JRE7_x86.exe (288,452 KB)

  • Includes 32-bit JRE7, default 950 MB max Java heap memory. For older 32-bit Windows systems (XP) and those with limited physical RAM.

Mac OS X

GeWorkbench_2.6.0_Installation_MacOSX_README_FIRST.pdf

geWorkbench_v2.6.0_MacOSX_JRE7_x64.zip (287,622 KB)

  • Includes 64-bit JRE7, max Java heap memory selectable by command file.

Linux

geWorkbench_v2.6.0_Linux_JRE7_x64.bin (326,484 KB)

  • Includes 64-bit JRE7, default 2GB max Java heap memory.

Generic - any platform

geWorkbench_v2.6.0_Generic.zip (240,045 KB). No Java JRE is included, you must supply and configure the appropriate JRE for your machine.


Install and Run geWorkbench

Windows (XP/Vista/7/8/10)

Installation

Download one of the Windows installers and double-click it to begin installation, or download the Zip file version and extract geWorkbench.

New with release 2.6.0, geWorkbench installers will by default install geWorkbench to "C:\Program Files" system directory, e.g. to C:\Program Files\geWorkbench_2.6.0. With the Zip file version, you can place the extracted folder anywhere that is convenient, either in a user directory or in e.g. C:/Program Files.

Running geWorkbench on Windows

Installer versions

Launch geWorkbench using the default Java max heap memory size by just clicking on the shortcut created by the installer. This is 2 GB for the 64-bit JVM and 950 MB for the 32-bit JVM.

Any 64-bit version

If you wish to start the 64-bit version of geWorkbench with a different (larger) memory request, you can use the launcher .bat files found in the geWorkbench installation directory, typically "C:\Program Files\geWorkbench_2.6.0". These files are name such as "launch_geworkbench_winpc_4G.bat", and are available for starting with geWorkbench with 1, 2, 4, 8 or 16 GB of Java heap memory.

To start geWorkbench with one of these batch files, you can either just double-click on it, or you can first make a shortcut to it (right-click, "Create Shortcut"). You can then move the shortcut e.g. to your Desktop for easy access. Double-clicking on the shortcut will then start geWorkbench with the requested amount of memory.

Mac OS X

Installation

  • Recent testing has been on Mac OS X 10.10+ only.
  • As Java 7 is not available for the PowerPC platform, regardless of OS X version, geworkbench will not run on the PowerPC platform under any version of OS X.

The MacOSX version of geWorkbench 2.6.0 is distributed as a simple zip file and includes the Java 7 update 71 JRE. No Mac installer is available for this release, instead, please follow the below steps.

Please carefully read and follow these instructions:

1. Double-click on the downloaded file "geWorkbench_v2.6.0_MacOSX_JRE7.zip" to expand it (or allow the autoexpander to expand it on download).

2. Drag the extracted "geWorkbench_2.6.0" folder to your system's Applications folder, or another convenient folder.


Running geWorkbench on Mac OS X

1. The geWorkbench_2.6.0 folder contains launcher command files (e.g. "launch_geworkbench_macosx_2G.command") which can be used to start geWorkbench with varying amounts of Java heap memory (2 GB in this example). Launcher command files are available to start geWorkbench with 1, 2, 4, 8, or 16 GB of maximum Java heap memory. Choice of the Java heap memory size is discussed elsewhere in this document. 2 GB is the recommended default value for geWorkbench 2.6.0 on 64-bit systems such as Mac OS X.

Right-click on the desired command file and select "Make Alias".

2. Drag the new alias file e.g. to your Desktop for easy access.

3. IMPORTANT (Gatekeeper function, Mac OS X 10.7.3 and higher):

The first time you attempt to start geWorkbench from one of the command files or an alias file, right-click on the file and select "Open". You will be prompted as to whether you want to open this file from an unidentified developer; answer yes.

After this first invocation, you can then start geWorkbench just by double-clicking on the alias or command file.

Linux

  • You may need to configure the JRE. See section below, "Java Environment Configuration".

Installation

The Linux version of geWorkbench relies on X-Windows being installed and running. If you are running Linux on a server and e.g. you wish to view the application on a Windows desktop, you will also need to run an X-windows server on your desktop machine. See X-Windows configuration instructions below.

After downloading, cd (if needed) to the directory to which you downloaded the installer.

To begin the installation, type the command for the particular version, e.g. for the installer with JRE:

"sh geWorkbench_v2.6.0_Linux_JRE7_x64.bin".

This will extract geWorkbench into a new directory called geWorkbench_2.6.0.

If you requested that a desktop link be created, it will be called geWorkbench_2.6.0 or rungeWorkbench_2.6.0 (if you create the shortcut in the same directory as the in which you extracted geWorkbench).


Running geWorkbench (Linux)

To run geWorkbench, and assuming you are using the Linux bash shell, and that you created a shortcut link during installation, issue one of the following commands from your home directory, depending on how the alias file was named:

   sh geWorkbench_2.6.0
   or
   sh rungeWorkbench_2.6.0.
         

Alternatively, in the directory in which geWorkbench was installed, you can start geWorkbench with the command:

   sh geWorkbench

Generic

A non-installer-based version of geWorkbench is supplied in a Zip file which should work on any platform.

File: geWorkbench_v2.6.0_Generic.zip

Installation

Unzip the file. It will create a directory geWorkbench_2.6.0.


Running geWorkbench (generic)

You must have the Java 7+ JRE installed and the JRE must be in the path for geWorkbench (see Java Environment Configuration below).

Windows

Double-click on the file "launch_geWorkbench.bat" to launch geWorkbench with its default Java heap memory setting, or double-click on one of the batch (.bat) files for specific sizes of Java heap memory. The files can also be run from the command window.

Mac OS X

Double-click on one of the command (.command) files for specific sizes of Java heap memory. The files can also be run from the command window.

Linux/Unix

  Execute the script "launch_geworkbench.sh".
     

Any: Alternatively, if you have Apache Ant installed, you can type "ant run" in the geWorkbench directory.

R Installation for geWorkbench

Some geWorkbench components can make use of a locally installed version of R.

R installation on Windows

  • R installation directory - There are specific considerations for installing R on Windows Vista/7/8/10.

We have demonstrated two methods based on the links shown below.

Install R in user directory

You can install R directly into your own user directory. Packages will be placed directly into the library within the installation. You just need to set the R-script location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.

C:\Users\user_name\R-3.1.2\bin\Rscript.exe 

where for user_name please substitute your own Windows login name.

Install R in system directory

You can allow Windows to install R into the default system directory, e.g. C:\Program Files\R\R-3.1.2\.

Set the Rscript location in the geWorkbench Preferences tab (Tools->Preferences-R Location), e.g.

C:\Program Files\R\R-3.1.2\bin\Rscript.exe

However, in this case, geWorkbench will not be able to install needed R packages into the default location because it cannot write to the system directory. (The R Console version of R, in this case, would suggest creating a personal library in a user directory such as (C:\Users\username\Documents\R\win-library\3.1, but this is not automatically implemented in geWorkbench).

There are two ways to circumvent this:

1. Use the geWorkbench Tools-Preferences->R Package directory setting. Enter a path to an alternate location for R packages. You must create any needed directories yourself. This has the advantage that you can have a separate location for use just by geWorkbench.

2. Alternatively, set the Windows environment variable R_LIBS_USER to an appropriate user directory, e.g C:\Users\user_name\R\win-library\3.1 for the current release of R, where for user_name please substitute your own Windows login name. (The proper number to use is x.y, for R version x.y.z). Or you could use the same path as suggested above, "C:\Users\username\Documents\R\win-library\3.1".

  • You can create the environment variable R_LIBS_USER by e.g.
    • right-clicking on "Computer" in Windows Explorer,
    • then clicking "Properties", Advanced system settings",
    • then under "User variables" for "your_user_name", click "New...".
    • Enter the new variable name R_LIBS_USER and the location C:\Users\user_name\R\win-library\3.1.
  • You must create the corresponding directory structure yourself before running geWorkbench, e.g.
    • in your home directory C:\Users\user_name, create the new folder R,
    • then within it create win-library,
    • then within win-library create the appropriate directory e.g. 3.1 for version 3.1.* of R.

Links to information on installing R on Windows

  • R packages directory - You can set the R packages directory to one in your own user space in order to gain write permission. Please see the R FAQ on library directory.

R installation on Mac OS X

R can be installed to the default system location.

  • If you are running as an administrator, R will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/bin/Rscript.
  • In addition, R package files will be installed to a directory such as /Library/Frameworks/R.framework/Versions/3.1/Resources/Library.


Java Environment Configuration

To run a version of geWorkbench that does not include the Java 7 Runtime Environment (JRE7), the JRE7 must be installed and, depending on the platform configured separately.

Two environment variables may need to be properly configured. These are the JAVA_HOME and the PATH variables. They should be configured to point to your own installation of the JRE7.

Linux/Generic

Here is an example of setting the two environment variables for a JRE installed in the directory /opt:

PATH=/opt/jre1.7.0_71/bin:$PATH

JAVA_HOME=/opt/jre1.7.0_71 (for use with Ant)

Macintosh OS X

The Mac OS X version of geWorkbench includes the Java 7 JRE.

Switching between different installed JREs on Windows

If you have multiple versions of Java installed, you can set JAVA_HOME to the desired version, and if you start geWorkbench simply by double-clicking on launch_geworkbench.bat, it will use the version of Java specified there.

Downloading older versions of Java

Previous Java versions can be downloaded from the Java archive site. Signing up for an Oracle web account is required.

Java Runtime Special Exceptions

The GenomeSpace webstart (jnlp) launcher application and the MarkUs molecular structure visualizer are unsigned Java applets. To use either, special steps must be taken, as described below.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.

In the Java control panel (found in Control Panel in Windows or in Settings on the Mac), in the Security tab, add the following to the Exception Site List:

The first is for GenomeSpace, and the second and third for MarkUs.

In addition, you may be prompted to allow popups from these sites when you attempt to run one of these, and you may also need to grant specific permission to run the applet.

On the Macintosh, the first time you try to run the GenomeSpace launcher applet, you will be prevented by Gatekeeper from launching it.

  • If using Firefox, go to Downloads and right-click on the downloaded jnlp file. Choose "Open".
  • If using Chrome, you may see an option pulldown to Open the downloaded file. This should allow it to run.

Once this has been done once, you will not be asked again.

Typical steps in running X-windows

Here are some typical steps to configure a remote Linux host and a local desktop X-server. Under Windows, a local X-server can be provided for example by the Cygwin package.

On the remote Linux host (assuming you are using the bash shell), issue the command

  • "export DISPLAY=(your IP):0"

where (your IP) should be substituted with the IP address of your local desktop machine.

On your local desktop machine, you may need to

  1. start the X-windows server with a command such as "startx". You may need to cd to the X11 bin directory to find this command.
  2. allow remote connections with a command such as "xhost +".

Quick Start

A Quick Start guide to geWorkbench is being developed.

Community Support Forums

geWorkbench community forums are operated by the caBIG Molecular Analysis Tools Knowledge Center. There are separate user and developer forums. Anyone can browse through existing postings, but to start a new topic one must first register.

The forums can be viewed at https://cabig-kc.nci.nih.gov/Molecular/forums/


geWorkbench 2.6.0 - System Requirements

Java

  • geWorkbench 2.6.0 has been developed and tested using Java 7. Versions of geWorkbench which include a built in Java 7 Runtime Environment (JRE) are provided. Using a version of geWorkbench that includes the JRE7 allows you to be sure that you are running geWorkbench in its intended environment.
  • geWorkbench has not been extensively tested using Java 8. However, at this time there are no known incompatibilities.
  • The "Generic" distribution of geWorkbench does not include the JRE7. Java must be installed separately. The generic distribution can be used on any machine, including Windows, Mac, Linux and others.
  • geWorkbench can run on both 32-bit and 64-bit versions of Java on appropriate OS platforms.
  • See the Java System Requirements and Java on 64-bit Windows for further details.

Special Java Requirements for Specific Components

  • GenomeSpace - The GenomeSpace (genomespace.org) website allows geWorkbench to be launched using a Java Web-Start application. This in turn requires a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. Either 32-bit or 64-bit versions may be used.

Note - Using GenomeSpace in geWorkbench does not require the use of the web start applet. It is just a convenience to start geWorkbench directly from the GenomeSpace portal.


  • MarkUs - The MarkUs component molecular structure display in your web browser requires that a Java JRE be installed separately on your machine. The latest version of the Java 8 JRE may be used and is recommended. You must install the version matching your browser, e.g. 32-bit Java (i586) for 32-bit web browsers such as Firefox and Chrome on Windows. This is true even if you have a 64-bit version already installed for other reasons.


There are specific steps to configure Java for these two applets. See Java Runtime Special Exceptions below.

Obtaining Java

Display Driver

  • This requirement pertains only to using the PCA component 3D graph viewer.
  • When using a 64-bit JVM, the Java 3D library requires that OpenGL version 1.2 or higher be supported by your display driver.

Memory

At least 4 GB is recommended. The 64-bit JRE7 version of geWorkbench 2.6.0 by default will request up to 2 GB of memory for the Java VM.

Operating System

  • Windows XP/Vista/Windows 7/8/10 (32 or 64-bit):
    • 32-bit versions of Windows can only run the 32-bit JRE versions of geWorkbench.
    • 64-bit versions of Windows can run either 32-bit or 64-bit JRE versions.
  • Mac OS X: As geWorkbench for Mac now includes the Java JRE7, it should run on any recent version of Mac OS (Intel platform only). A previous requirement for OS X Version 10.7.3 or higher was based on using an externally installed version of Java.
  • Linux: no special requirements.

geWorkbench, unless otherwise noted for particular components, can be run on both 32 and 64-bit operating systems and JREs.

Graphics Driver

At least one component, the PCA viewer, uses a Java 3D library. When using a 64-bit JVM, the Java 3D library requires OpenGL version 1.2 or higher to be supported by the graphics display adapter in your computer.


R server

Several components (SAM, DeMAND, and VIPER) can use a local installation of R on your desktop computer.

This has been tested with R versions 3.1.2, 3.1.1, 3.0.3, 3.0.2 and 2.15.0.

There are special considerations for installing a local copy of R on Windows computers. Please see the section on this further below.

IMPORTANT NOTICE ABOUT THE LICENSE

Use of geWorkbench is governed by the rules specified in the software license. Please make sure to read the license and understand your obligations before proceeding to download the application.


Tutorial data

Tutorial data is further described on the Tutorial_Data page.

tutorial_data.zip (3.586 MB) - data files in several different formats useful for the tutorials or just trying out geWorkbench.

Bcell-100.zip (5.256 MB) - A large (100 array) microarray dataset in the geWorkbench matrix format. Data is from the lab of Riccardo Dalla-Favera, Columbia University, and is provided only for use in learning and testing geWorkbench. It was obtained from experiments using Affymetrix HG-U95Av2 chips.

Download the geWorkbench Source Code

geWorkbench 2.5.0 and later on Github

Following release 2.5.0 of geWorkbench, the source code was migrated to a Github repository. geWorkbench 2.5.0 and all following releases can be obtained from there.

On Github, geWorkbench is now divided into three parts: the core, the components, and the supplemnetal files. Each project can be downloaded from the web interface by entering the particular project and pushing the button "Download ZIP".

The main project page on Github is https://github.com/geworkbench-group.

To create the fully functional geWorkbench source tree,

  1. First download and extract geworkbench-core.
  2. Then download and extract geWorkbench-components.
  3. From within geworkbench-components, move the extracted "components" directory into the core.
  4. Finally, download the two files from the geworkbench_supplemental_files project.
    1. Cytoscape - copy the file cytoscape.jar into the directory components/cytoscape/lib.
    2. VIPER - copy the file viper.tar.gz into the directory components/viper/viperScripts. You do not need to unzip it.

geWorkbench 2.4.1 and earlier on SVN

Public access to the NCI Subversion repository is no longer available.

Compiling the geWorkbench Source Code

  • you must have the Java JDK 7 installed on your machine - see http://java.oracle.com, under the "Java SE" link.
  • you must make sure that the value of the environment variable JAVA_HOME is the directory where the JDK is installed, e.g.
C:\Program Files\Java\jdk1.7.0_71

If you have Ant installed on your machine, you can just type "ant run" in the geWorkbench root directory and the program will be built and run. Ant can be downloaded from http://ant.apache.org/. Note that installing Ant involves manually adding the Ant bin directory to the PATH variable, setting the ANT_HOME directory.

'Special Note for Mac Users - Ant has been removed from release 10.9 of OS X. However, you can reinstall it, either from the Apache distribution or using "brew" and "xcode".