Installation of LSD from sources

Last modified : February, 14th 2008.

Please read carefully before starting any installation !

Installation is known to work under IRIX (Silicon Graphics), Cygwin (PC/Windows, see below), GNU/Linux and MacOSX.

LSD is writtren in ANSI C and should be reasonably portable to other systems.

Note to PC/Windows users

Cygwin as operating system.

LSD-3.2.4 was developed in a Unix environment. However, PC/Windows users can use LSD if they install cygwin. It provides a wide subset of Unix functionalities. Alternatively, you may use a binary distribution, LSDos, that is LSD for MS-DOS. A specific documentation is included.

You can find Cygwin at www.cygwin.com.

There is no point to install the X/windows extension of Cygwin. Ghostview is needed to visualize the Postcript file that contains the solutions generated by LSD. It is possible to avoid using Ghostview by editing the "solve" file. Ghostview can be downloaded from www.cs.wisc.edu/~ghost. Pre-installation of AFPL Ghostscript is required. The latter can be downloaded from the same web site. Installation of both tools should be achieved in the default locations, C:/ for gs (Ghostscript) and C:/Program File for Ghostgum (Ghostview).

A fully detailed installation of Cygwin can be found at www.gammon.com.au/smaug/installingcygwin.htm, and at other places.

A double-click on the cygwin icon on your desktop pops up a DOS-style (background color is black) command window in which you may type UNIX commands. This may be sufficient if this window bears a vertical scrollbar. Else, type "rxvt &", and another command window appears, but this one has a vertical scroll bar and its background color is white. Ancient times DOS users will appreciate this... This window is the place where you will type commands to run LSD, once installed. In Unix terminology, a command window is also named a "shell window", or even simpler, a "shell".

If you want to leave (kill) a command window, just type Control-D. (One time for the rxvt window, a second time for the DOS-style window).

If you are new to both Cygwin and UNIX, the following points may be important for you.

Cygwin file system

The root of the Cygwin file system is named "/" and is located at C:\Cygwin\. This is equivalent to "Workstation" in Windows, meaning it is the directory that contains all the files of you computer. "/" contains all the files of the Cygwin operating system.

Home directory

Your "home" directory is the place where you put your own programs and files, like "C:\My Documents" for Windows. Before you type in the command window, you get something like MyName@MyPC (written in green) where MyPC is the computer's name and MyName is the user's name you gave when Windows was installated (default user's name is "Standard"). Your home directory is /home/MyName for Cygwin, and C:\Cygwin\home\MyName for Windows. A synonym of the home directory is "~", as visible in the command window, written in yellow after MyName@MyPC.

Your home directory is a good place for the file LSD-3.2.4.tar.gz before unpacking it (not right now !) and proceeding to LSD installation (see below).

Command interpreter

You will have to create a ".bash_profile" file in your home directory. Run WordPad and type in the one-line text "export PATH=.:$PATH", but without the quotes. Save this text as ".bash_profile" (!!!! with the quotes !!!!) in your home directory (C:\Cygwin\home\MyName) as a "Text only" file. Kill cygwin window(s) and re-open it (them), so that what was done right now becomes effective immediately. The single command that is stored in ".bash_profile" ensures that the current directory will always be in the list of the directories where executable files are searched. This list is provided by the command interpreter parameter named $PATH.

Browse files and directories

When you open a command window, the current directory is your home directory, hence the "~" in the title bar that always displays the name of the current directory. To change the current directory, enter the command cd, followed by the name of the target directory, followed by the "Enter" key. If the target directory is located in the current directory, only its name is required. To change to the parent directory give ".." for its name. It is also possible to give an "absolute" name that does not refer to the current directory. The name then starts with a "/" followed by the succession of sub-directories, separated by slashes. For example, "cd /usr/doc" sets the current directory to the one that contains documentation folders. The "cd" command without argument returns to the home directory.

The name of the current directory can always be referred to by the name ".". The command "ls -a" lists all its contents. Alternatively, you may use the Windows explorer. If you do not create the ".bash_profile" file, you will have to type "./lsd" instead of "lsd" (the same for outlsd and genpos) to specify that the program you want to run is located in the current directory.

Documentation

The Cygwin web site provides many useful tips about the organization and the use of this operating system. Many help files can be found in C:\Cygwin\usr\doc.

Starting installation

You need an opened shell window, to be positionned on your home directory and to have LSD-3.2.4.tar.gz in it.

Installation

Open a shell window and change the current directory to the one that contains LSD-3.2.4.tar.gz, if necessary.

1. Unpack
gunzip LSD-3.2.4.tar.gz
tar xvf LSD-3.2.4.tar

2. Change directory
cd LSD-3.2.4

3. Configure and compile
sh install.sh

4. Test
make test

You should see the structure of the pinene molecule. If the test fails after a correct installation (step 3), it most probably means that the path to the previewer in the "solve" script is wrong. You will have to edit it manually to enter the correct path. For MacOSX, the previewer is not launched. Success is obtained if LSD declares that a solution was found.

Notes

The "lsd" command

The LSD program itself is invoked by the "lsd" command. It appears that under some Linux systems lsd is an alias for "ls -d". Typing lsd gives you then the list of the directories within the current directory. You may change this temporarily with "unalias lsd" or permanently by modifying the shell start-up file that contains the alias definitions.

C Compiler

You need a C compiler to produce executable files from source code written in C. Under Cygwin and GNU/Linux gcc is the compiler and is included in the distribution of these operating systems. Under IRIX, cc is chosen if gcc is not available. You can install gcc under IRIX 6.5 from freeware.sgi.com. Typing "which cc" may erroneously lead you to believe that the cc compiler is installed. You need a valid licence file from SGI to use their cc.
With MacOSX, you need the Apple development tools (connect.apple.com) to run the gcc compiler. The Makefile file that is installed in the LSD-3.2.4 folder allows compilation of the LSD source code with the "make fromSrc" command.

Postscript display

A Postscript display program is necessary to visualize the solution structure(s) found by LSD. The output of LSD may be translated into various graphic formats by the outlsd program. One of these formats can be turned by the "genpos" program into Postscript intructions, suitable for both visualizing and printing purposes.

Under Cygwin, you will use gsview32.exe for Windows, installed according to the procedure described in the Note to PC/Windows users (see above). Under Linux and IRIX, gv and xpsview are the names of the standard previewers, respectively. For MacOSX, a Postscript tool comes with the TexShop typesetting software, available from darkwing.uoregon.edu/~koch/texshop.

M_edit

M_edit is a kind of a very minimalist chemical structure editor. It is there to beautify the ugly drawings outlsd sometimes produces. It is written in Tcl scripting language and uses the Tk toolkit for GUI creation. Tcl/Tk is invoked by the "wish" command, standing for "windowing shell".

m_edit uses the tk_getOpenFile and tk_getSaveFile widgets that appeared with Tk version 8.0. The version of Tcl/Tk you use must be 8.0 or higher.

Wish is part of Cygwin and Linux distributions, under the names cygwish8x.exe and wish8.x, respectively (x = 3 or 4). Under Linux, establish a symbolic link between wish8.x and wish, e.g. with "ln -s /usr/bin/wish8.x /usr/bin/wish". Alternatively, you can adapt the m_edit script. For IRIX 6.5, you may download it from freeware.sgi.com, or install it from the sources located at tcl.activestate.com/software/tcltk.

For MacOSX, Tck/Tk is available from www.apple.com/downloads/macosx/unix_open_source/tcltkaqua.html.

Solve

Solve is a small script that successively runs lsd for structure solving, outlsd for molecule drawing, genpos for Postscript file genereration and a Postscript previewer for result visualization. Solve is invoked when you type "make test". If you get the expected result (the structure of pinene), the installation is finished and you can start to learn how to write input files for LSD from the MANUAL_ENG.html document.

Copyright(C)2000 CNRS-UMR 6229-Jean-Marc Nuzillard