// -*- text -*- // $RCSfile: README-distutils,v $ // $Revision: 1.3 $ // $Author: langer $ // $Date: 2005/09/12 17:46:52 $ Congratulations! You are reading the README file for a software package you downloaded! You are now officially an *advanced* system adminstrator. This is the README file for OOF2, describing how to build and install it with the Python distutils utility. This version does *not* contain a configure script or Makefile. Installation: ------------ Installation is similar to other Python libraries. If your system is well-set-up, and has the required libraries, there should be no difficulties. The executive summary of steps is: > tar -xzf oof-.tgz > cd oof- > python setup.py build_ext > python setup.py install If something goes wrong, your system adminstrator may be able to help you, or you can contact the oof developers at oof_manager@ctcms.nist.gov. It's diagnostically useful to include all the output from setup.py. OOF2 has been built and tested on Debian Linux, Redhat Linux, SGI, and Macintosh OS X. Details: ------- 0. What You Should Already Have: A computer running a variant of the Unix operating system, including Linux and Macintosh OS X, and an X11 server. OOF2 currently does *not* run on Microsoft Windows. The following external programs and libraries must be present before you can run OOF2. To compile OOF2 from sources, you will also require the header files ("includes") associated with these programs and libraries. These are usually available as part of a "development" version of the library software. Python (2.3 or later) http://www.python.org Magick++ http://www.imagemagick.org/www/Magick++/index.html gtk+-2.0 (2.6 or later) http://www.gtk.org/download/ libgnomecanvas2 http://directory.fsf.org/graphics/misc/libgnomecanvas.html pygtk2 (2.6 or later) ftp://ftp.gtk.org/pub/gtk/python/v1.2/ *swig 1.1 build 883 http://www.swig.org/download.html Macintosh OS X users will need to install an X11 server. Apple's X11.app is available as an option when installing OS X 10.3, or may be obtained from http://www.apple.com/macosx/features/x11/. Users of earlier versions of OS X will need to get a server elsewhere. You should also have the ability to run the "blas" basic linear algebra subroutines. On Macintosh OS X, this is built in to the vecLib framework, and no special libraries are required. On Linux and commercial Unix systems, it may have to be installed, and you may require headers. **We're using an old version of swig because it was the stable version at the time we started working on OOF2. The current version will *not* work with OOF2. We will upgrade to a modern version of swig in a later release. Because of the obscurity/antiquity of swig 1.1 build 883, this package is optional. The swig output is included with the OOF2 distribution. However, if you want to add your own extensions to OOF2, you will need swig. 1. What You Got From Us: The file "oof2-distutils-.tar.gz". Procedure: --------- (Macintosh OS X users can install OOF2 from either a Terminal or xterm window, or the equivalent.) 0. Unpack Unpack the .tar.gz file. The usual way is to run "tar -xzf" on the file you want to unpack. This will create a subdirectory named "oof2-" in the directory where you run tar. 1. Build the OOF2 Python extension Switch to the newly-created directory, and run % python setup.py build_ext You can see the full set of options by running % python setup.py --help build_ext In particular, if you need to tell it where some required libraries are, you will need to use the --libraries and --library-dirs options. The build_ext command will create a "build" subdirectory in the top OOF2 directory. Within "build" it will create a subdirectory with a system-dependent name. This will *not* conflict with any build directory that you might have created with the configure/make method of building OOF2. 2. Install To install OOF2, run % python setup.py install This will install OOF2 in the standard location for Python extensions on your system. This is good, because then you won't have to do anything special to get OOF2 to run. It's also bad, because unless you are the system administrator, you probably don't have permission to install anything in that directory. You have two options: a) Get a system administrator to run the installation step. b) Tell distutils to install oof2 in a different place, like this: % python setup.py install --prefix= where is a directory that you can write to. The default value of is usually /usr/local. On OS X it may be something like /Library/Frameworks/Python.framework/Versions/2.3 if you're using the system Python, or /sw if you're using fink's Python. The installation procedure will create an executable script called "oof2" in /bin, a shared library called "oofcppcmodule.so" and a directory called "oof2" in /lib/python2.x/site-packages (where 2.x is your python version number), and some example files in /share/oof2/examples. (It's possible to use --home= instead of --prefix when installing oof2. The only difference is that --home will put the python libraries in /lib/python instead of /lib/python2.x/site-packages.) If /bin is not in your Unix command path, you'll need to add it to the PATH environment variable, or create a symbolic link from a directory that is in your path (or start OOF2 the hard by by typing /bin/oof2). (Typing "echo $path" will print the current value of your path. The method for setting environment variables depends on which Unix shell you're using.) If /lib/python2.x/site-packages is not in your Python path, you'll have to add it to the PYTHONPATH environment variable. (Running the command % python -c "import sys; print sys.path" will print your Python path.) Running OOF2: ------------ At this point, you should have an executable file named "oof2" in a bin directory in your execution path. You can now simply type "oof2" at your shell prompt, and OOF2 will start up. (Macintosh OS X users will have to start X11 before starting OOF2. Then OOF2 can be started in an xterm window, or in a Terminal window if the DISPLAY environment variable has been set correctly, probably to ":0.0".) OOF also has many options, and you can get a summary of them by typing "oof2 --help". By default, OOF runs in graphics mode, opening a couple of windows to get you started. If you don't want this, you can use the "--text" option to run it in command-line mode.