Installing GSAS/EXPGUI under Mac OS X

This page contains information on installing and running GSAS & EXPGUI on Macintosh OS X computers. The software has been built using OS X 10.2.6 and has been installed successfully on 10.2 and 10.3 machines.


The following summarizes the steps needed to load prerequisite software as well as the GSAS/EXPGUI distribution. I presume that most Mac users will probably have already installed X11 and FINK on their computers. I have very limited experience with this, so please do not contact me for help with steps 1-3. However, most OS X books can provide more details beyond what is given here.

  1. Install X11
    This can be done from your OS (Jaguar or Panther) CD-ROM or can be downloaded from http://www.apple.com/macosx/features/x11/download/ .

  2. Install FINK
    To do this, you will need to install the Development Tools, which are distributed with OS X as well as the FINK package, which can be downloaded from http://fink.sourceforge.net/ . Download the package and then double-click on it.

  3. Download and install required packages.
    GSAS requires the "Portable Network Graphics" (libpng3) library. EXPGUI requires the X11 (not Aqua) version of Tcl/Tk package; installation of the BLT add-on for Tcl/Tk is needed for plotting from EXPGUI (for example, LIVEPLOT). There are many ways to install this software. One way is to type in Fink (apt-get) commands, as described below. A more "Mac-appropriate" approach is to avoid use of the command line completely and with a user-friendly front-end, FinkCommander, also described below.

  4. Download the GSAS & EXPGUI programs as a Mac disk image.
    Download this file from the NIST website:
    ftp://ftp.ncnr.nist.gov/pub/cryst/gsas/osx_gsaskit.dmg (~7 Mb)
    These files can also be downloaded from the CCP14 mirrors: [(UK), (Canada), (US) or (Australia)].

    What happens when you download this file depends on your method for downloading. Some browsers will automatically perform the next step for you:

    Mount this file by double-clicking on it. This should create a new volume in your top-level ("Computer") called "GSASvol"; clicking on this device will open a finder window with a single folder ("gsas") present.

    While you can run GSAS & EXPGUI from this location, you are strongly suggested to instead copy the entire package to your computer by dragging the gsas folder icon to another finder window, or by clicking on it and using Copy and Paste.

    At this point you are able to run EXPGUI using the full command name from inside an X11 window -- by typing a command such as this:

         /sw/bin/wish /MyApps/gsas/expgui/expgui
    but this gets old fast -- see the following section for a better way.
  5. Install a "shortcut" to launch EXPGUI
    The following instructions describe ways that the EXPGUI program can be integrated into the Mac environment.

    EXPGUI AppleScript icon The OSX version of GSAS & EXPGUI has an EXPGUI AppleScript application in the "gsas" folder with the icon shown to the right. This AppleScript will start X11, if needed and then lauch EXPGUI. (If you have ideas for improving the script, the code can be found in file expgui_applescript.txt.) The EXPGUI AppleScript can be used in three ways:

    • Double-clicking on the icon will launch EXPGUI so that it starts with the "file open" window in your home directory. This window can then be used to navigate to access/create experiments in other folders.

    • Dropping one or more GSAS Experiment (.EXP) files onto the EXPGUI icon will cause the experiment files to be opened. If more than one file is dropped, each file will open in a separate EXPGUI session.

    • Dropping one or more folders onto the EXPGUI icon will cause EXPGUI to be started with the "file open" window in that folder.

    You may find it convenient to drag the EXPGUI icon to the dock, for easy access. Note, that this EXPGUI app will not work correctly if copied or moved to another folder -- instead create an alias (for example using the Finder Command-L key). An alias can be moved where desired -- for example, to the desktop or to the Application folder.

  6. Make a command-line "shortcut" to run EXPGUI
    If you are a "Unix enthusiast," you might be interested in setting up command line short-cuts to the gsas script and the EXPGUI program; however, my presumption is that most people buy Mac's to avoid using the command line. Those people who wish to define a command line short-cut should see section 2.2 in the Unix installation notes.

EXPGUI Enhancements specific to the Mac

EXPGUI will automatically designate the EXPGUI AppleScript as the "open with" application for every GSAS experiment (.EXP) file that is read or written by EXPGUI, provided that the Development Tools program Rez is found in /Developer/Tools. At the same, EXPGUI will also designate an icon for the .EXP file. After this is done, EXPGUI can be invoked by simply double-clicking on a GSAS experiment file.

If for some reason you would prefer this not be done (I would be interested to hear why) -- deselect the "Assign app to .EXP files" checkbox in the Options menu.

Mac ideosyncracies

Unlike in the Windows & Unix versions of GSAS, Mac windows may not be updated until they are brought to the top of the screen by clicking on them (given focus). This is most noticible for PGPLOT graphics (in POWPLOT, RAWPLOT,...). When you type graphics commands in a terminal window, the plot does not appear to change. However, click on the PGPLOT's window bar and the plot will update.

Installing software from the command line

With FINK installed, it is possible to download and install binary versions of the required programs by entering the following command in a terminal or xterm window:
     sudo apt-get install tcltk blt libpng3-shlibs

Installing software using FinkCommander

A second method, which is recommended for everyone other than UNIX gurus, is to use instead the "FinkCommander" application, which is provided in a separate directory (of the same name: see picture below). After installing the fink package ("Fink... Installer.pkg"), launch "FinkCommander". "FinkCommander" which is a GUI interface for fink (that allows you to avoid having to remember these ugly-, long-, obsure and esoteric UNIX-styled commands)

In "FinkCommander", with your computer connected to the internet, simply use "Update-all" (in the "Source" menu) the first time you run "FinkCommander", then be patient while Fink tabulates a list of the latest versions of all available OS X software packages.

Then, in the "binary" menu, select the "blt" package and ask to install it (from a binary distribution) using the "install" command, as shown in the picture below. Since FinkCommander will automatically load the packages required by blt (dependencies), this will also cause Tcl/Tk to be loaded or updated.

Repeat this step to install the "libpng3" library.

The "FinkCommander" folder on the desktop (back window) and application (front window) showing the installation of the binary "blt" package.

(click to enlarge)

Depending on which version of OS X you have, and the versions of the available binary distributions, it is possible that the above may not work. If this occurs, simply repeat the process, but this time use the install command from the source menu. The will achieve the same result, but will take much longer (say 15-45 minutes) as Fink will download and compile the source codes for the various packages.


If you cannot get EXPGUI or the GSAS graphics programs to work, you may have a setup problem with X-windows (X11). One common reason for this is that X11 must be restarted any time your computer's IP address changes. This can happen when you connect your Mac to a network directly or with a modem. Your IP address can change even while your computer is wired into a network. If exiting and restarting X11 does not address your problem, the following paragraphs may help you diagnose problems.
  1. One possible problem is the definition for the X11 display (shell environment variable DISPLAY). On my machine, this variable is set correctly in an X11 xterm window, but is not set by default within an Aqua terminal window.

    A quick test for this is to type xclock at the shell prompt:

         bash-2.05a$ xclock
    If you get a clock display -- great. If you get the following error message the DISPLAY variable is not set:
         bash-2.05a$ xclock
         Error: Can't open display: 
    If on the other hand, you get this error message, there is a problem with Xwindows:
         bash-2.05a$ xclock
         Error: Can't open display: localhost:0.0
    You can set the DISPLAY variable in bash/zsh, etc. using:
         bash-2.05a$ export DISPLAY=localhost:0.0
    or in csh/tcsh, etc. using:
         [d120234:~] toby% setenv DISPLAY localhost:0.0

  2. A second possible problem relates to the installation of the Tcl/Tk and BLT packages. You can test if Tcl/Tk and the BLT package are installed correctly using the following commands:
         [d120234:~] toby% wish
         % package require BLT
         % pack [blt::graph .g]
         % exit
    When you type "wish" and press Enter, a new small blank window should appear. when you type the 2nd line, "package require BLT," there will be no change in the blank window, but the computer should respond "2.4". After the "pack [blt::graph .g]" command is entered, a set of x- and y-axes should appear in this window. The window should disappear after "exit" is typed.

The EXPGUI icon, the original version of the EXPGUI AppleScript and help with this documentation was provided by Francois Farges -- many thanks!

GSAS is Copyright, 1984-2000, by the Regents of the University of California. The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36) by the Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Permission is granted to the public to copy and use this software without charge, provided that this notice and any statement of authorship are reproduced on all copies. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software.

The author of EXPGUI is a U.S. Government employee which means that EXPGUI is not subject to copyright. Have fun with it. Modify it. Please write new sections and make them available to the rest of the world.

Neither the U.S. Government nor any author makes any warranty, expressed or implied, or assumes any liability or responsibility for the use of this information or the software described here. Brand names cited herein are used for identification purposes and do not constitute an endorsement by NIST.

Questions/Problems: crystal@nist.gov
$Revision: 773 $ $Date: 2009-12-04 23:11:47 +0000 (Fri, 04 Dec 2009) $