home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / RockRidge / info-service / gopher / Unix / xgopher.1.3 / README < prev    next >
Encoding:
Text File  |  1993-05-25  |  16.9 KB  |  439 lines
  1.           Installation Notes
  2.                on the
  3.             Xgopher client
  4.  
  5.  
  6. These notes describe Xgopher version 1.3, completed in May 1993.
  7.  
  8.  
  9. +---------------------+
  10. | System Requirements |
  11. +---------------------+
  12.  
  13. Xgopher requires Release 4 or 5 of the X window system, version 11.  It uses
  14. the Athena widget set, the X toolkit intrinsics, and the X library.
  15. Xgopher contains many dependencies on the Unix operating system.
  16.  
  17. PLEASE NOTE: Xgopher was developed using X11R5 platforms.  It should work
  18.          with X11R4 also, but may require a small change.  For most
  19.          computers, this change will not be necessary.  If you
  20.          receive errors when compiling with X11R4, see the note below.
  21.  
  22.  
  23. +---------------+
  24. | Documentation |
  25. +---------------+
  26.  
  27. This README file contains installation instructions.
  28. The Documents subdirectory contains considerable additional information
  29. on porting Xgopher to other Unix systems and configuring Xgopher.
  30.  
  31. +--------------+
  32. | Installation |
  33. +--------------+
  34.  
  35. The Xgopher program will likely be obtained as a Unix tar file.
  36. After using tar to extract the contents of this file, perform
  37. the following steps.
  38.  
  39. 1. Modify the configuration file (conf.h).  If you do not modify this
  40.    file at all, then Xgopher will connect to the University of Illinois
  41.    gopher server by default.  The comments in the file tell you what
  42.    is expected.  Possibly little change will be necessary, but at least
  43.    consider changing the default top-level gopher server host name to
  44.    a server near you.  These are just the compiled-in defaults, most
  45.    can still be changed at run-time to accommodate individual preferences.
  46.  
  47.    +------------------------------------------------------------------------+
  48.    | OPEN WINDOWS ALERT!                                                    |
  49.    |     If you are COMPILING with Sun's OpenWindows (Version 3) libraries, |
  50.    |     replace step 2 with the steps outlined below for OpenWindows.      |
  51.    +------------------------------------------------------------------------+
  52.  
  53. 2. xmkmf
  54.    (this will turn the Imakefile into a Makefile, if X11R5
  55.    is properly installed on your system.)
  56.    +------------------------------------------------------------------------+
  57.    | If you do not have xmkmf or imake, you can edit and use the file       |
  58.    | Makefile.NoNo (named to discourage its use), as your Makefile.         |
  59.    | If you use Makefile.NoNo, skip step 3.                                 |
  60.    +------------------------------------------------------------------------+
  61.  
  62. 3. make depend
  63.    (this will build the include file dependency information
  64.    into the Makefile.)
  65.  
  66. 4. make
  67.    (this will compile the 37 or so source files and link them
  68.    with X11 to produce the executable file xgopher.)
  69.  
  70. 5. Modify the application defaults file (Xgopher.ad).
  71.    Little change may be necessary.  However, the entries in this
  72.    file (e.g., for host name, port number, help file name, etc.)
  73.    override those defaults compiled into xgopher through
  74.    the configuration file (step 1).
  75.  
  76. 6. Make the application defaults file (Xgopher.ad) known to X.
  77.    There are several ways to do this for testing without installing
  78.    the file in a system directory.  Choose one of the following -
  79.    whichever is most comfortable for you.
  80.  
  81.  
  82.    IMPORTANT!  Although you can test Xgopher with old (pre Xgopher 1.3)
  83.                resource files on your system, you may see some warning
  84.                messages.  These are informatory only.  For final installation,
  85.                remove all of the application defaults from previous
  86.            versions of Xgopher before you install Xgopher 1.3.
  87.  
  88.  
  89.    a. xrdb -merge Xgopher.ad
  90.  
  91.    b. setenv XENVIRONMENT `pwd`/Xgopher.ad       
  92.       (`pwd` will return the current directory, which should be the
  93.       Xgopher source directory.)
  94.  
  95.    c. if you have your own app-defaults directory, for example, ~/app-defaults:
  96.      setenv XAPPLRESDIR ~/app-defaults/
  97.      cp Xgopher.ad ~/app-defaults/Xgopher
  98.       Note the name change.
  99.  
  100.    COLOR OPTION: If you are using a color display, it is strongly
  101.          recommended that you also include the Xgopher
  102.          color resources.  if you used method (a) above, then
  103.          also use:
  104.              xrdb -merge Xgopher-color.ad -nocpp
  105.  
  106.          Otherwise, consider using the file Xgopher-complete.ad
  107.          instead of Xgopher.ad.  The former file has all of the
  108.          color resources included in it.
  109.  
  110.          This is sufficient for now, and to let you test.  For
  111.          permanent installation, see the later section of this
  112.          document which discusses color resources.
  113.  
  114.    For final installation, this file will be stored in the X
  115.    application defaults directory, with the file named Xgopher.
  116.    Depending on where your X (or OpenWindows) libraries are installed,
  117.    this will be the file such as /usr/lib/X11/app-defaults/Xgopher.
  118.  
  119. 7. to test:
  120.       xgopher
  121.    (this executes the xgopher program!)
  122.  
  123.        (If you see messages like this:
  124.            Warning: Cannot convert string "indexLabel" to type Widget
  125.         It means that you have old Xgopher resources left somewhere in
  126.         your resource files or server.  The message is probably harmless,
  127.         but you should get rid of the old files before installing Xgopher 1.3
  128.         permanantly.)
  129.  
  130.    +------------------------------------------------------------------------+
  131.    | SUN USER ALERT!                                                        |
  132.    |     Whether you are using X11R5 or Sun's OpenWindows (version 3),      |
  133.    |     you may receive an error saying that Xgopher cannot connect to     |
  134.    |     the gopher server.  If this happens to you, see the additional     |
  135.    |     help in the file Documents/Porting.                                |
  136.    +------------------------------------------------------------------------+
  137.  
  138. 8. to install Xgopher on your system:
  139.    With root privileges:
  140.        make install
  141.        make install.man
  142.    this should install the 4 files needed by Xgopher.
  143.  
  144.    If you wish to install all of the files manually instead of using the
  145.    "make install" sequence, the four files that need to be installed are:
  146.  
  147.    xgopher    this is the xgopher 1.3 program.  It may be installed
  148.         as the file xgopher in /usr/local/bin, for example.
  149.    xgopher.help the help text file.  It may be installed with this
  150.         name in /usr/local/lib, for example.  Note that its
  151.         path name was compiled in to Xgopher through the Imakefile.
  152.         The resource file (Xgopher.ad) can override this.
  153.    Xgopher.ad    the X application defaults file.  It may be installed
  154.         as Xgopher, in /usr/lib/X11/app-defaults, for example.
  155.    xgopher.man    the user documentation (man page).  It may be installed
  156.         as xgopher.l (letter l), in /usr/man/manl, for example.
  157.  
  158.  
  159. +-------------+
  160. | OpenWindows |
  161. +-------------+
  162.  
  163. Many people compile with MIT's X11 library then use Sun's OpenWindows
  164. server.  This is never a problem.  
  165.  
  166.    +------------------------------------------------------------------------+
  167.    | If you are compiling Xgopher with the MIT X11 software, you should     |
  168.    | not be using this part of the installation instructions.  Return       |
  169.    | immediately to step 2 above.                                           |
  170.    +------------------------------------------------------------------------+
  171.  
  172. Some problems arise when compiling with the OpenWindows 3 libraries.
  173. OpenWindows 2 cannot be used as it is an implementation of X11R3.
  174.  
  175. I will try to help people who want to compile with OW3, but I do not
  176. have good access to such a system, nor am I proficient with its use.
  177. With this caveat, I will say that I have invested considerable effort 
  178. to understand the problems people have been reporting with OW3 and
  179. in modifying the Imakefile to avoid these problems.
  180.  
  181. (Solaris 2.1)
  182.     My comments here apply to SunOS 4.x, not necessarily to Solaris.
  183.     I have had somewhat better luck in my quick visit with Solaris 2.1
  184.     using the "standard" procedures - with one exception.  For Solaris 2.1,
  185.     in the Imakefile, I needed to chande the line
  186.  
  187.              EXTRA_LIBRARIES  =  -lm
  188.     to
  189.              EXTRA_LIBRARIES  =  -lm -lsocket -lnsl
  190.     (This line is commented out in the Makefile; you may need to include it
  191.     depending on your networking software configuration on your Sun.)
  192.     With this change you can probably continue with the installation
  193.     procedure as documented above.
  194.  
  195.     You also may need to uncomment out the line beginning "LOCAL_DEFINES"
  196.     which defines the symbols SYSV and SVR4 in case your imake templates
  197.     do not already define these symbols.
  198.  
  199.  
  200. Sun supplies a version of xmkmf and imake.  However, these point
  201. to incorrect directories for the build and installation of software.
  202. Also, their Xmu library is broken for dynamic loading.
  203.  
  204.    +------------------------------------------------------------------------+
  205.    | There are two solutions to this problem.  Choose one of the following: |
  206.    |                                                                        |
  207.    |  (1) Use the work-arounds I suggest below.                             |
  208.    |  (2) Fix everything the right way, patching Sun's software             |
  209.    |                                                                        |
  210.    | Your desire and ability to modify system files may determine your      |
  211.    | choice.                                                                |
  212.    +------------------------------------------------------------------------+
  213.  
  214. Use either method (1) or method (2) below - not both.
  215.  
  216. (1) To use the work-around:
  217.  
  218.     I have provided the file Documents/OW3-site.def in the Xgopher
  219.     directory, which should correct enough of the problems with Sun's
  220.     imake template files to allow you to build Xgopher.  Feel free to
  221.     modify this file if you need to.  You will rename it to site.def
  222.     in step 2c below.
  223.  
  224.  
  225.     To compile with OW3, replace step 2 of the installation instructions
  226.     with the following:
  227.  
  228.       2a. Make sure that your environment variable OPENWINHOME is set
  229.           to the proper directory - the top level of your OW3 tree.
  230.  
  231.       2b. Edit the Imakefile to uncomment the 3 lines which are
  232.           well-marked in the Imakefile:
  233.  
  234.              MKDIRHIER        = BourneShell $(BINDIR)/mkdirhier
  235.              EXTRA_LIBRARIES  = -lresolv -lm
  236.              XMULIB           = -lm -Bstatic -lXmu -Bdynamic
  237.  
  238.           (Or, Stew Ellis suggests that you can avoid the use of
  239.           -Bstatic by using the parameter "-assert nodefinitions".
  240.           Use the following line instead of the XMULIB defined above:
  241.              XMULIB           = -assert nodefinitions -lXmu
  242.           I have not tested this.)
  243.  
  244.       2c. Rename or copy the file Documents/OW3-site.def to be site.def.
  245.           For example:
  246.  
  247.              cp Documents/OW3-site.def site.def
  248.  
  249.           This file is read by the imake command to build your Makefile.
  250.  
  251.       2d. Instead of xmkmf, use the following command:
  252.  
  253.              imake -DUseInstalled -I. $OPENWINHOME/lib/config
  254.           
  255.           Be sure that this is the imake from $OPENWINHOME/bin/imake
  256.           and not an X11 directory.  Use "which imake" or check your
  257.           path if you are not positive.
  258.         
  259.  
  260.     The -Bstatic load option (in step 2b) is necessary to avoid loader
  261.     warnings of unresolved externals for:
  262.  
  263.         _get_vwShellWidgetClass
  264.         _get_applicationShellWidgetClass
  265.  
  266.     I have tried loading without -Bstatic.  I get errors telling me that
  267.     these are missing, but the resulting xgopher binary still seems to
  268.     work.  If you are willing to risk a possible future error, you may
  269.     omit the -Bstatic option.  (Larry Butler butler@rex.cs.tulane.edu
  270.     reports that the binarys work fine with either the OpenWindows X
  271.     server or MIT's X11R4 server and twm, but that they kill openlook.
  272.     I think he is refering to the OpenLook Window Manager.)
  273.  
  274.  
  275. (2) To fix everything the right way, patching Sun's software:
  276.  
  277.     * NOTE *  I have not tested these patches and cannot take
  278.           responsibility for their correct behavior.
  279.           They have been kindly supplied by a Sun user
  280.           (Dawn Endico).
  281.     
  282.     Apply the following patches to Sun's libXmu and libXt:
  283.  
  284.         libXmu:    100573-03.tar.Z
  285.         libXt:    100512-02.tar.Z
  286.  
  287.     They are available from: iskut.ucs.ubc.ca:/pub/ubc/sun-patches
  288.                          or: dragon.cso.uiuc.edu:/SUN-FIXES
  289.  
  290.     
  291.     Apply the supplied patch to the OpenWindows xmkmf software.
  292.     The file Documents/OW3-xmkmf.patch contains this patch.
  293.  
  294.     You should NOT be using the file Documents/OW3-site.def.  That file
  295.     is only for working around Sun's xmkmf as a temporary fix.
  296.  
  297.     Then you can use xmkmf as described in step 2 of the installation
  298.     instructions for non-OpenWindows systems.
  299.  
  300.     You may still need to load with -lm (the math library).  If
  301.     you get unresolved external references to routines such as
  302.     sin, cos, pow, floor, then insert the line:
  303.  
  304.         EXTRA_LIBRARIES  =  -lm
  305.     
  306.     near the start of the Imakefile
  307.  
  308.  
  309.  
  310.  
  311. +---------------+
  312. | X11 Release 4 |
  313. +---------------+
  314.  
  315. There has been considerable interest in compiling Xgopher under X11R4.
  316. I have tried to provide that capability to the extent possible.
  317. If you use X11R4, certain tests in the file compatR4.h should detect
  318. this and automatically define the symbol XGOPHER_X11R4.
  319.  
  320.   Unlike previous versions of Xgopher, you should not need to take
  321.   special action to compile with MIT's X11R4 libraries.  However, some
  322.   vendor libraries may fail these tests.
  323.  
  324. If these tests fail, then you should define this symbol
  325. yourself in the file conf.h by removing the comments from the define
  326. statement (or use -DXGOPHER_X11R4 as a compiler option).  This will cause
  327. the compiler to omit some minor R5 specific things without loss of
  328. functionality.
  329.  
  330. I cannot promise to maintain this backwards compatibility forever.
  331. I do not have good access to an X11R4 library for testing so
  332. I must depend on feedback from others to detect release-dependencies.
  333.  
  334.  
  335.  
  336. +---------------+
  337. | Customization |
  338. +---------------+
  339.  
  340. The installer may wish to customize some of the Xgopher features
  341. such as the image display, telnet, or other commands.  These are 
  342. all described in the file Documents/Install-Customization.  This
  343. document also mentions some alternative "plug-compatible" widgets
  344. that could be used to modify the appearance of Xgopher.
  345.  
  346. There is another writeup, Documents/Customization, which describes
  347. changes that a user may use in configuring Xgopher.  This latter
  348. file should be available to knowledgable end-users.
  349.  
  350.  
  351. +------------------------+
  352. | Color Resource Support |
  353. +------------------------+
  354.  
  355. The supplied defaults file (Xgopher.ad) will work fine on all color
  356. displays and black & white displays.  It has no color definitions.
  357. Depending on your users of Xgopher, you may want to install certain
  358. versions of these app-defaults files.
  359.  
  360. This section is for the installer of Xgopher.  A separate document,
  361. "Customization", provides information for other users of Xgopher.
  362.  
  363. If EVERY Xgopher user has a black and white display screen, then just
  364. use the file Xgopher.ad.  (You needn't read further in this section.)
  365.  
  366. If EVERY Xgopher user has a color display screen, then you can use
  367. the file Xgopher-complete.ad, which has colors defined in addition
  368. to all the rest of the resources.  Rename it to be Xgopher.ad and
  369. install it as Xgopher in the system defaults directory.
  370.  
  371. In many cases, both black and white screens and color screens are
  372. present at an installation.  If so, it is poor practice to install
  373. the color resources file only - monochrome users may get poor results
  374. such as black characters on a black background.
  375.  
  376. One suggestion is to install the standard Xgopher.ad file, then
  377. let each color user keep their own resources file with only color
  378. preferences.  This file would be used in their personal .Xdefaults
  379. or xrdb data files.  The file Xgopher-color.ad can be copied to
  380. get a suggested set of colors.
  381.  
  382. For sites running X11R4 and using both color and non-color displays,
  383. the above is the only solution.  It will also work with X11R5.
  384.  
  385. There is another possibility for sites with X11R5.  I encourage you to
  386. look at the "customization" option that will allow you to install both
  387. color and B&W resource files, and conditionally load the color one
  388. automatically depending on the screen you are using.
  389.  
  390. For X11R5, the Imakefile will handle the installation of both the
  391. monochrome and color resources files:
  392.  
  393.     Xgopher-color.ad  as  Xgopher-color
  394.     Xgopher.ad        as  Xgopher
  395.  
  396. Then, each and every user can add the following to the file they
  397. input to xrdb:
  398.  
  399.     #ifdef COLOR
  400.     *customization:   -color
  401.     #endif
  402.  
  403. The #ifdef will determine whether you are on a color screen, and if
  404. so, use the color resource file.  The color resource file "includes"
  405. the standard Xgopher resource file.
  406.  
  407.  
  408.  
  409. +----------+
  410. | Problems |
  411. +----------+
  412.  
  413. Please report and problems, suggestions, or portability problems to
  414. the author of xgopher.  e-mail contact is preferred:
  415.  
  416.     Allan Tuchman
  417.     Computing and Communications Services Office (CCSO)
  418.     University of Illinois at Urbana-Champaign
  419.     1304 W. Springfield Ave.
  420.     Urbana, Illinois   61801
  421.     USA
  422.  
  423.     (217) 244-0048
  424.     a-tuchman@uiuc.edu
  425.  
  426.  
  427.  
  428. +--------------------+
  429. | Other Contributors |
  430. +--------------------+
  431.  
  432. Thanks to all people who took the time to send me their comments,
  433. suggestions, and problems in previous versions of Xgopher.
  434. All bug reports and most of the suggestions have been
  435. incorporated into Xgopher 1.3.
  436.  
  437. Of course, the present author assumes responsibility for any
  438. problems introduced.
  439.