Installation Notes on the Xgopher client These notes describe Xgopher version 1.3, completed in May 1993. +---------------------+ | System Requirements | +---------------------+ Xgopher requires Release 4 or 5 of the X window system, version 11. It uses the Athena widget set, the X toolkit intrinsics, and the X library. Xgopher contains many dependencies on the Unix operating system. PLEASE NOTE: Xgopher was developed using X11R5 platforms. It should work with X11R4 also, but may require a small change. For most computers, this change will not be necessary. If you receive errors when compiling with X11R4, see the note below. +---------------+ | Documentation | +---------------+ This README file contains installation instructions. The Documents subdirectory contains considerable additional information on porting Xgopher to other Unix systems and configuring Xgopher. +--------------+ | Installation | +--------------+ The Xgopher program will likely be obtained as a Unix tar file. After using tar to extract the contents of this file, perform the following steps. 1. Modify the configuration file (conf.h). If you do not modify this file at all, then Xgopher will connect to the University of Illinois gopher server by default. The comments in the file tell you what is expected. Possibly little change will be necessary, but at least consider changing the default top-level gopher server host name to a server near you. These are just the compiled-in defaults, most can still be changed at run-time to accommodate individual preferences. +------------------------------------------------------------------------+ | OPEN WINDOWS ALERT! | | If you are COMPILING with Sun's OpenWindows (Version 3) libraries, | | replace step 2 with the steps outlined below for OpenWindows. | +------------------------------------------------------------------------+ 2. xmkmf (this will turn the Imakefile into a Makefile, if X11R5 is properly installed on your system.) +------------------------------------------------------------------------+ | If you do not have xmkmf or imake, you can edit and use the file | | Makefile.NoNo (named to discourage its use), as your Makefile. | | If you use Makefile.NoNo, skip step 3. | +------------------------------------------------------------------------+ 3. make depend (this will build the include file dependency information into the Makefile.) 4. make (this will compile the 37 or so source files and link them with X11 to produce the executable file xgopher.) 5. Modify the application defaults file (Xgopher.ad). Little change may be necessary. However, the entries in this file (e.g., for host name, port number, help file name, etc.) override those defaults compiled into xgopher through the configuration file (step 1). 6. Make the application defaults file (Xgopher.ad) known to X. There are several ways to do this for testing without installing the file in a system directory. Choose one of the following - whichever is most comfortable for you. IMPORTANT! Although you can test Xgopher with old (pre Xgopher 1.3) resource files on your system, you may see some warning messages. These are informatory only. For final installation, remove all of the application defaults from previous versions of Xgopher before you install Xgopher 1.3. a. xrdb -merge Xgopher.ad b. setenv XENVIRONMENT `pwd`/Xgopher.ad (`pwd` will return the current directory, which should be the Xgopher source directory.) c. if you have your own app-defaults directory, for example, ~/app-defaults: setenv XAPPLRESDIR ~/app-defaults/ cp Xgopher.ad ~/app-defaults/Xgopher Note the name change. COLOR OPTION: If you are using a color display, it is strongly recommended that you also include the Xgopher color resources. if you used method (a) above, then also use: xrdb -merge Xgopher-color.ad -nocpp Otherwise, consider using the file Xgopher-complete.ad instead of Xgopher.ad. The former file has all of the color resources included in it. This is sufficient for now, and to let you test. For permanent installation, see the later section of this document which discusses color resources. For final installation, this file will be stored in the X application defaults directory, with the file named Xgopher. Depending on where your X (or OpenWindows) libraries are installed, this will be the file such as /usr/lib/X11/app-defaults/Xgopher. 7. to test: xgopher (this executes the xgopher program!) (If you see messages like this: Warning: Cannot convert string "indexLabel" to type Widget It means that you have old Xgopher resources left somewhere in your resource files or server. The message is probably harmless, but you should get rid of the old files before installing Xgopher 1.3 permanantly.) +------------------------------------------------------------------------+ | SUN USER ALERT! | | Whether you are using X11R5 or Sun's OpenWindows (version 3), | | you may receive an error saying that Xgopher cannot connect to | | the gopher server. If this happens to you, see the additional | | help in the file Documents/Porting. | +------------------------------------------------------------------------+ 8. to install Xgopher on your system: With root privileges: make install make install.man this should install the 4 files needed by Xgopher. If you wish to install all of the files manually instead of using the "make install" sequence, the four files that need to be installed are: xgopher this is the xgopher 1.3 program. It may be installed as the file xgopher in /usr/local/bin, for example. xgopher.help the help text file. It may be installed with this name in /usr/local/lib, for example. Note that its path name was compiled in to Xgopher through the Imakefile. The resource file (Xgopher.ad) can override this. Xgopher.ad the X application defaults file. It may be installed as Xgopher, in /usr/lib/X11/app-defaults, for example. xgopher.man the user documentation (man page). It may be installed as xgopher.l (letter l), in /usr/man/manl, for example. +-------------+ | OpenWindows | +-------------+ Many people compile with MIT's X11 library then use Sun's OpenWindows server. This is never a problem. +------------------------------------------------------------------------+ | If you are compiling Xgopher with the MIT X11 software, you should | | not be using this part of the installation instructions. Return | | immediately to step 2 above. | +------------------------------------------------------------------------+ Some problems arise when compiling with the OpenWindows 3 libraries. OpenWindows 2 cannot be used as it is an implementation of X11R3. I will try to help people who want to compile with OW3, but I do not have good access to such a system, nor am I proficient with its use. With this caveat, I will say that I have invested considerable effort to understand the problems people have been reporting with OW3 and in modifying the Imakefile to avoid these problems. (Solaris 2.1) My comments here apply to SunOS 4.x, not necessarily to Solaris. I have had somewhat better luck in my quick visit with Solaris 2.1 using the "standard" procedures - with one exception. For Solaris 2.1, in the Imakefile, I needed to chande the line EXTRA_LIBRARIES = -lm to EXTRA_LIBRARIES = -lm -lsocket -lnsl (This line is commented out in the Makefile; you may need to include it depending on your networking software configuration on your Sun.) With this change you can probably continue with the installation procedure as documented above. You also may need to uncomment out the line beginning "LOCAL_DEFINES" which defines the symbols SYSV and SVR4 in case your imake templates do not already define these symbols. Sun supplies a version of xmkmf and imake. However, these point to incorrect directories for the build and installation of software. Also, their Xmu library is broken for dynamic loading. +------------------------------------------------------------------------+ | There are two solutions to this problem. Choose one of the following: | | | | (1) Use the work-arounds I suggest below. | | (2) Fix everything the right way, patching Sun's software | | | | Your desire and ability to modify system files may determine your | | choice. | +------------------------------------------------------------------------+ Use either method (1) or method (2) below - not both. (1) To use the work-around: I have provided the file Documents/OW3-site.def in the Xgopher directory, which should correct enough of the problems with Sun's imake template files to allow you to build Xgopher. Feel free to modify this file if you need to. You will rename it to site.def in step 2c below. To compile with OW3, replace step 2 of the installation instructions with the following: 2a. Make sure that your environment variable OPENWINHOME is set to the proper directory - the top level of your OW3 tree. 2b. Edit the Imakefile to uncomment the 3 lines which are well-marked in the Imakefile: MKDIRHIER = BourneShell $(BINDIR)/mkdirhier EXTRA_LIBRARIES = -lresolv -lm XMULIB = -lm -Bstatic -lXmu -Bdynamic (Or, Stew Ellis suggests that you can avoid the use of -Bstatic by using the parameter "-assert nodefinitions". Use the following line instead of the XMULIB defined above: XMULIB = -assert nodefinitions -lXmu I have not tested this.) 2c. Rename or copy the file Documents/OW3-site.def to be site.def. For example: cp Documents/OW3-site.def site.def This file is read by the imake command to build your Makefile. 2d. Instead of xmkmf, use the following command: imake -DUseInstalled -I. $OPENWINHOME/lib/config Be sure that this is the imake from $OPENWINHOME/bin/imake and not an X11 directory. Use "which imake" or check your path if you are not positive. The -Bstatic load option (in step 2b) is necessary to avoid loader warnings of unresolved externals for: _get_vwShellWidgetClass _get_applicationShellWidgetClass I have tried loading without -Bstatic. I get errors telling me that these are missing, but the resulting xgopher binary still seems to work. If you are willing to risk a possible future error, you may omit the -Bstatic option. (Larry Butler butler@rex.cs.tulane.edu reports that the binarys work fine with either the OpenWindows X server or MIT's X11R4 server and twm, but that they kill openlook. I think he is refering to the OpenLook Window Manager.) (2) To fix everything the right way, patching Sun's software: * NOTE * I have not tested these patches and cannot take responsibility for their correct behavior. They have been kindly supplied by a Sun user (Dawn Endico). Apply the following patches to Sun's libXmu and libXt: libXmu: 100573-03.tar.Z libXt: 100512-02.tar.Z They are available from: iskut.ucs.ubc.ca:/pub/ubc/sun-patches or: dragon.cso.uiuc.edu:/SUN-FIXES Apply the supplied patch to the OpenWindows xmkmf software. The file Documents/OW3-xmkmf.patch contains this patch. You should NOT be using the file Documents/OW3-site.def. That file is only for working around Sun's xmkmf as a temporary fix. Then you can use xmkmf as described in step 2 of the installation instructions for non-OpenWindows systems. You may still need to load with -lm (the math library). If you get unresolved external references to routines such as sin, cos, pow, floor, then insert the line: EXTRA_LIBRARIES = -lm near the start of the Imakefile +---------------+ | X11 Release 4 | +---------------+ There has been considerable interest in compiling Xgopher under X11R4. I have tried to provide that capability to the extent possible. If you use X11R4, certain tests in the file compatR4.h should detect this and automatically define the symbol XGOPHER_X11R4. Unlike previous versions of Xgopher, you should not need to take special action to compile with MIT's X11R4 libraries. However, some vendor libraries may fail these tests. If these tests fail, then you should define this symbol yourself in the file conf.h by removing the comments from the define statement (or use -DXGOPHER_X11R4 as a compiler option). This will cause the compiler to omit some minor R5 specific things without loss of functionality. I cannot promise to maintain this backwards compatibility forever. I do not have good access to an X11R4 library for testing so I must depend on feedback from others to detect release-dependencies. +---------------+ | Customization | +---------------+ The installer may wish to customize some of the Xgopher features such as the image display, telnet, or other commands. These are all described in the file Documents/Install-Customization. This document also mentions some alternative "plug-compatible" widgets that could be used to modify the appearance of Xgopher. There is another writeup, Documents/Customization, which describes changes that a user may use in configuring Xgopher. This latter file should be available to knowledgable end-users. +------------------------+ | Color Resource Support | +------------------------+ The supplied defaults file (Xgopher.ad) will work fine on all color displays and black & white displays. It has no color definitions. Depending on your users of Xgopher, you may want to install certain versions of these app-defaults files. This section is for the installer of Xgopher. A separate document, "Customization", provides information for other users of Xgopher. If EVERY Xgopher user has a black and white display screen, then just use the file Xgopher.ad. (You needn't read further in this section.) If EVERY Xgopher user has a color display screen, then you can use the file Xgopher-complete.ad, which has colors defined in addition to all the rest of the resources. Rename it to be Xgopher.ad and install it as Xgopher in the system defaults directory. In many cases, both black and white screens and color screens are present at an installation. If so, it is poor practice to install the color resources file only - monochrome users may get poor results such as black characters on a black background. One suggestion is to install the standard Xgopher.ad file, then let each color user keep their own resources file with only color preferences. This file would be used in their personal .Xdefaults or xrdb data files. The file Xgopher-color.ad can be copied to get a suggested set of colors. For sites running X11R4 and using both color and non-color displays, the above is the only solution. It will also work with X11R5. There is another possibility for sites with X11R5. I encourage you to look at the "customization" option that will allow you to install both color and B&W resource files, and conditionally load the color one automatically depending on the screen you are using. For X11R5, the Imakefile will handle the installation of both the monochrome and color resources files: Xgopher-color.ad as Xgopher-color Xgopher.ad as Xgopher Then, each and every user can add the following to the file they input to xrdb: #ifdef COLOR *customization: -color #endif The #ifdef will determine whether you are on a color screen, and if so, use the color resource file. The color resource file "includes" the standard Xgopher resource file. +----------+ | Problems | +----------+ Please report and problems, suggestions, or portability problems to the author of xgopher. e-mail contact is preferred: Allan Tuchman Computing and Communications Services Office (CCSO) University of Illinois at Urbana-Champaign 1304 W. Springfield Ave. Urbana, Illinois 61801 USA (217) 244-0048 a-tuchman@uiuc.edu +--------------------+ | Other Contributors | +--------------------+ Thanks to all people who took the time to send me their comments, suggestions, and problems in previous versions of Xgopher. All bug reports and most of the suggestions have been incorporated into Xgopher 1.3. Of course, the present author assumes responsibility for any problems introduced.