# Installing Sparky (revised June 18, 2001)

Sparky is a graphical program for doing NMR assignment and integration. It runs under Windows 95/98/NT, Linux, and SGI, Sun, and DEC flavors of Unix. The latest version is available at http://www.cgl.ucsf.edu/home/sparky and is free for both academic and commercial users. To help us obtain grant money for further Sparky development we keep track of the number of sites using Sparky. We ask that you send in a signed license agreement to get access to non-expiring versions of the program. See the web page for instructions on sending in the license form. A trial version of the program good for 3 to 6 months is available without sending in a signed license and functions exactly the same as the non-expiring version.

## Installing for Unix or Linux

The standard installation directory is /usr/local/sparky. Unpack the sparky-xxx.tar.gz file as follows.

    	% cd /usr/local
    	% gunzip -c /tmp/sparky-xxx.tar.gz | tar xf -

You can start Sparky by running /usr/local/sparky/bin/sparky. You may want to add /usr/local/sparky/bin to your executable search path in your shell startup file (for example in .cshrc).

You can install Sparky in any directory you like. But you will need to edit the SPARKY_INSTALL path in the startup script bin/sparky so that Sparky can find auxilliary files it uses.

## Installing for Windows 95/98/NT

The standard installation directory is c:\Program Files\sparky. Unzip the sparky-win32.zip in "c:\Program Files". Get the shareware program WinZip 6.2 from the Sparky web site if you do not have an unzip utility.

You can start Sparky by clicking on the "sparky" icon in folder c:\Program Files\sparky\bin. You can create a shortcut to sparky by selecting the icon and then choosing "Create Shortcut" under the folder File menu. Then you can move this shortcut icon to the desktop or some other more convenient place.

You can install Sparky in any directory you like. But you will need to edit the SPARKY_INSTALL path in the startup script bin/sparky.bat so that Sparky can find auxilliary files it uses.

## Notes for Windows 95/98/NT

On some Windows 95 and Windows 98 systems starting Sparky fails with the error message "Out of environment space" and complaints about not being able to find the Tcl/Tk libraries. This happens because Windows limits the total number of environment variables. The Sparky start up script needs to set a few variables to specify where Sparky is installed and where the Tcl/Tk libraries are. Because the limit has been reached Windows does not allow the variables to be set and startup fails. The solution is to right click on the sparky.bat icon in the c:\Program Files\sparky\bin directory, select "Properties" and under the "Memory" tab adjust the parameter called "initial environment". It is by default set to "auto" and you should choose some number instead. I don't know how big the number has to be -- just experiment or choose the biggest value in the pull down menu of choices. Then Sparky will start without problems. This solution was reported to me by a Sparky user. I have not been able to test it because I have only Windows NT available and it does not exhibit this problem.

Many Sparky dialogs have help buttons that display the relevant section of the Sparky manual using Netscape. It will not work with Internet Explorer or other browsers. (It uses a Netscape specific DDE interface.) If you do not have Netscape you can look at the Sparky manual directly with your web browser of choice. The help buttons have been observed to crash Sparky under Windows 95 but work ok under Windows NT. If you have netscape but Sparky cannot find it, correct the Netscape path in the Sparky startup script.

## Notes for SGI

The SGI 6.5 version contains n32 binaries and the SGI 5.3 version contains o32 binaries. If you will be using Sparky with Python then Sparky must have the same executable format (o32 or n32) as Python. If you install Python by compiling under IRIX 6.5 it is probably n32. Compiling on all older IRIX'es produces o32 by default. You can check your Python executable format with command

    	% file /usr/local/bin/python1.5

## Notes for Linux

The Linux version requires libc6 (aka glibc 2.0 or 2.1) libraries. You can see whether you have this by looking for /lib/libc.so.6 on your system. Linux distributions Red Hat 5.0, Debian 2.0, Slackware 3.6 use libc6. I don't distribute a version that runs with older libc5 libraries because I don't have a Linux machine with older libraries to compile on. The glibc 2.0 Sparky distribution is known to core dump when run on a glibc 2.1 system (eg Redhat 6).

Sparky crosshairs do not get erased and quickly cover the whole spectrum window when using XFree86 3.3.5 with a Voodoo3 graphics card. The X server on most Linux systems is called XFree86. You can determine what version you have with the command "X -showconfig". This problem is a bug with XFree86 and has been reported to the XFree86 group. Until the X server is fixed the only solution is to turn off crosshairs using the View Settings dialog vt. This has to be done for each window. There is no command for turning off crosshairs in all windows at once.

## Using Sparky with Python

Many advanced Sparky features are written in the Python programming language. They are described in the Extensions section of the manual. To use them you need to install Python if it is not already on your system. Binary versions of Python are available from the Sparky web site or you can get it from the Python web site. The current Sparky distribution requires Python 1.5.2. The Sparky binary is not compatible with the earlier Python 1.5.1, 1.5, 1.4, or more recent Python 1.6 releases.

To install Python obtained from the Sparky site for Unix:

    	% cd /usr/local
    	% gunzip -c /tmp/sparky-xxx.tar.gz | tar xf -

For Windows, the Python distribution on the Sparky site is an installer program. Run it and follow the instructions.

If you get Python source code from the Python site and compile it you do not need to compile the optional Tkinter module. Sparky comes with a Tkinter module and the necessary Tcl/Tk libraries. Sparky requires Tkinter without thread support. If you compile your own Tkinter with thread support and you statically link it to Python then Sparky will not run.

## Description of Files

      README		- reminder of where web site and manual are
      license		- contains license expiration date

      manual
        index.html		- start of HTML manual
        intro.html		- introduction to basic commands
        install.html	- this file
        changelog.html	- list of changes version by version
        *.html		- other sections of manual
        manual.html		- manual in a single file
        manual-postscript	- Postscript version of manual

      example		- sample data

      bin
        sparky		- a script that starts Sparky
        sparky-no-python	- the executable for running without Python
        pipe2ucsf		- conversion from NMRPipe format to Sparky format
        ucsfdata		- prints UCSF NMR data header, extracts data matrix
        vnmr2ucsf		- conversion from Varian VNMR format to Sparky format
        bruk2ucsf		- conversion from Bruker format to Sparky format
        peaks2ucsf		- creates simulated specta from list of Gaussians
        matrix2ucsf		- make a UCSF format spectrum from a data array

      lib
        Sparky		- the Tk resource file, fonts sizes, ...
        print-prolog.ps	- Postscript used for printing spectrum windows

      python
        README		- description of Python interface to Sparky
        sparky/*.py		- code for Sparky extensions
        sparky/spy.so	- the C++ Sparky library
        lib-tk		- Tkinter Python code

## Compiling Sparky in no binary distribution is available

If a binary distribution is not available for your hardware and operating system you can compile Sparky from source code. If you are an experienced programmer this might work. Otherwise you've gotta be brave, foolish and lucky to get it to work. You will need a Sparky license, Tcl/Tk 8.0.5 (free from http://www.scriptics.com), a C++ compiler, and a make program. Sparky can be extended by users with the Python language (version 1.5.2). If you want to use this you must have Python (free from http://www.python.org).

Unpack the Sparky source distribution. Take a look at the script bin/make-sparky that invokes "make" with the proper arguments for the different platforms I compile on. The script chooses different sets of compiler options based on the host name. You can add an entry for the machine you will compile on.

An alternative, harder method is to edit Makefile and c++/Makefile directly. Set the paths to the source directory and the installation directory. If you have Python set the lib and include paths. Shared object libraries for Tcl/Tk are required. If you don't want to use the GNU C++ compiler g++ change the definition of CC. Add any flags needed by your compiler to the CFLAGS variable. If you want to install in a directory other than /usr/local/sparky edit the path in the sparky startup script "sparky". Now run "make" (or without Python "make nopython") and if everything compiles "make install" (or without Python "make install-nopython").

## Acknowledgement

Sparky was developed by Donald Kneller 1989-95 working with Tack Kuntz at the University of California, San Francisco. Development is continuing at UCSF in the Computer Graphics Laboratory, headed by Tom Ferrin, and with the assistance of Tom James' NMR group. My name is Tom Goddard. I've done the programming 1996-99.

We have not written a paper describing Sparky. If you publish work that made use of Sparky you can cite it as:

    	T. D. Goddard and D. G. Kneller, SPARKY 3,
    	University of California, San Francisco

## Copyright, License, and Disclaimer

The following copyright, license and disclaimer applies to the Sparky code, documentation and binaries included in this distribution.

Copyright (c) 1989-2001, University of California Regents

Permission is hereby granted, free of charge, to use, copy, and modify the Sparky code, documentation and binaries included in this distribution.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.