Getting Started: Installing Lens

This explains how to install your own copy of Lens. The procedures differ between Windows and Unix/Mac OS X.

Installing Under Unix and Mac OS X

1. To install Lens under Mac OS X, you will first need to install Fink, which will give you a Unix and X-windows emulation environment. I can't give you much support where this is concerned. Be sure to install the xfree* packages. From here on in, I will assume you are running a Unix shell (xterm).
2. Make a Lens directory for yourself. Why not call it "~/Lens". Go there.
   mkdir ~/Lens
   cd ~/Lens
3. Download the complete distribution, lens.tar.gz into your new directory.
4. Untar the distribution. If you have a smart version of tar, you can do this with:
   tar xvzf lens.tar.gz
   If you have a dumb version of tar, you will need to do:
   zcat lens.tar.gz | tar xv
   
5. rm lens.tar.gz
   
6. mv Bin/i586 Bin/${HOSTTYPE}
7. Next you need to compile the TclTk libraries for your machine. If you're running on a Linux machine with glibc (the equivalent of RedHat 6.0 or later), you may be in luck because the TclTk libraries are already compiled and you can go right to the next step. If you have problems with shared libraries at the end of the Lens compilation, you should go back and compile your own TclTk libraries as follows:
   1. cd TclTk/tcl8.3.4/unix
   2. rm config.cache
   3. Linux: ./configure --enable-shared
      OS X: ./configure --disable-shared --disable-load
   4. make
   5. Pray that nothing bad happens. If all went well, a new libtcl8.3.so file should have been created. There is a chance a libtcl8.3.a was built instead. If so you will not be using shared libraries. But that's ok. If all didn't go well, I'm afraid I can't help you much. Start reading the README file.
   6. Remove the .o files we don't need anymore:
      rm -f *.o
   7. cd ../../tk8.3.4/unix
   8. rm config.cache
   9. Linux: ./configure --enable-shared --with-tcl=../../tcl8.3.4/unix
      OS X: ./configure --disable-shared --disable-load --with-tcl=../../tcl8.3.4/unix
   10. make
   11. Pray pray pray...and voilá you have a Tk library, maybe.
   12. rm -f *.o
   13. Now you should move the two libraries to your Lens Bin directory:
       cd ~/Lens (or wherever you installed it)
       mv TclTk/tcl8.3.4/unix/libtcl8.3.* Bin/${HOSTTYPE}
       mv TclTk/tk8.3.4/unix/libtk8.3.* Bin/${HOSTTYPE}
       
   14. On OS X:
       ranlib Bin/${HOSTTYPE}/libtcl8.3.a
       ranlib Bin/${HOSTTYPE}/libtk8.3.a

   Compiling Lens

8. Go back to your Lens directory and take a look at the Makefile. If you do not see a section at the top for your HOSTTYPE, you may need to add one and set it up appropriately. When compiling on Mac OS X, the HOSTTYPE should be "macintosh". If you are compiling on an Alpha, you should use "MACHINE=ALPHA".
9. Check to be sure the file /usr/X11R6/include/X11/Xlib.h exists. If it doesn't you will need to install the XFree86-devel RPM package that is appropriate for your version of Unix. If you don't have the CDs you used to install your Unix in the first place, you may be able to find the package here.
10. Now you're ready to compile. So type:
    make all
    This will compile alens and then lens.
11. If something went wrong, it is probably because you have funny C header files in your /usr/include or /usr/include/sys directories. Try to fix this by:
    1. Creating a MACHINE_... definition for your machine in sysext.h.
    2. Inside of the test for your machine type in sysext.h, #include any necessary header files, #define things to prevent bad header files from being included, or #undef things that cause problems.
    3. If you really can't figure it out, send the compile message to Doug Rohde. He'll probably want a temporary account on your machine so he can take a look at your header files and test for byte ordering and such.
12. When everything builds correctly, you will have two executables, lens and alens, which are actually pointers to the real executables that sit in the Bin/${HOSTTYPE} directory. Now you're ready to run Lens.
13. If you ever want to recompile, you have to be careful whether the object files that aren't being changed are for the correct version (either lens or alens). To compile only alens, do:
    make alens
    To compile only lens, do:
    make lens or just make
    If you ever switch from compiling one to the other, always do:
    make clean
    to remove the object files.
14. Be sure to read the section on Running Lens before you try to run it. It won't work unless you set the right environment variables.

Installing Under Windows

The first thing you will need to do is to install the Cygwin Utilities. These provide a Unix-like environment for Windows, including a shell, compiler, C libraries, and other goodies.
1. Download the latest Cygwin release from the Cygwin homepage.
2. To install the Cygwin stuff, just run the setup.exe program and follow the instructions. It will take some time, especially if you have a slow internet connection. When choosing packages for Cygwin, be sure to include Devel/gcc, Devel/make, Text/less, and Text/more.
3. Now start up a Cygwin shell window. They probably made an icon in your Start menu for just that purpose.
4. Make a Lens directory for yourself. Why not call it "Lens".
   mkdir Lens
   cd Lens
5. Download the complete windows distribution, lens-win.tar.gz into your new directory. If Windows mangled the name, mutter offensive things about Emperor Gates and rename it lens-win.tar.gz.
6. tar xvzf lens-win.tar.gz
   rm lens-win.tar.gz
7. If all you want is the plain Lens release. You should be ready to go. Head straight to Running Lens. If Lens seg faults when you try to run it, it is likely that the precompiled binary is incompatible with your version of Cygwin, and you will need to compile it yourself.

   Compiling Lens

   If you're going to want to customize the source code, you'll need to be able to compile your own version of Lens.
8. Look for the file /usr/include/X11/Xlib.h. If it isn't there, do this:
   1. Download this tar file.
   2. Be warned that when you untar this file it may write over some of the include files in your /usr/include/X11 directory. If you don't want it to do this, leave off the P flag and then move the results by hand from the usr directory that will be created.
   3. tar xvzfP xlib.tar.gz
9. If you don't have one already, create a .bash_profile file in your Cygwin home directory. In it, you should put:
   export HOSTTYPE=i686
   And be sure to source that file or run that command before proceeding.
10. Now you're ready to compile. So type:
    make all
    This will compile alens and then lens.
11. If something went wrong, it may be because stuff in the Windows section of the Makefile needs to be changed.
12. When everything builds correctly, you will have two executables, lens and alens, which are actually pointers to the real executables that sit in the Bin/ directory. Now you're ready to run Lens.
13. If you ever want to recompile, you have to be careful whether the object files that aren't being changed are for the correct version (either lens or alens). To compile only alens, do:
    make alens
    To compile only lens, do:
    make lens or just make
    If you ever switch from compiling one to the other, always do:
    make clean
    to remove the object files.
14. Be sure to read the section on Running Lens before you try to run it. It won't work unless you set the right environment variables.

New Versions

Untarring this will overwrite the files in your Src/, Commands/, and Examples/ directories. The only files it will not overwrite are Src/extension.c, Src/type.h, Src/sysext.h, and the Makefile. For these files, it will write a ".default" file instead.

If you have not customized those files, rename the ".default" file to the same name without the ".default". If you have made changes to those files and the default file has changed (which should only happen rarely), you may need to update your version or reimplement your changes in the default one.

If you have customized any files other than Src/extension.c, Src/type.h, Src/sysext.h, and the Makefile, you should rename your copy before untarring the lens-src.tar.gz or the files will be overwritten. You may want to write a script to do this so you don't forget.

There is a handy link to the source update distribution on the main Manual page.

Working Offline?