home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / fortran / pgplot5.1 / pgplot5 / pgplot5.1.0 / doc / install.txt < prev    next >
Encoding:
Text File  |  1996-05-10  |  16.0 KB  |  406 lines
  1. Appendix F. PGPLOT Installation Instructions
  2.  
  3. Version 5.1.0.
  4.  
  5. To install PGPLOT, you need to perform the following steps. These steps are
  6. described more fully below.
  7.  
  8.   1. Copy the distribution file by anonymous ftp from Caltech.
  9.   2. Unpack the distribution file to create the ``PGPLOT distribution''
  10.      directory tree. This is identical for all implementations of PGPLOT and
  11.      can be placed on any disk that is visible on the target system,
  12.      including read-only network-mounted disks.
  13.   3. Create a writeable directory in which the PGPLOT library and associated
  14.      files will be created. One such directory is needed for each different
  15.      operating system and compiler combination (``target system'') that you
  16.      wish to support. This should not be the same directory as the directory
  17.      containing the source code.
  18.   4. Configure PGPLOT by selecting device drivers from the available list.
  19.   5. For supported operating systems, execute the supplied script to create
  20.      the library and demonstration programs.
  21.   6. Run the demonstration programs on your selected devices and verify that
  22.      they run satisfactorily.
  23.   7. Optionally, install and test the C binding and/or Motif driver. This
  24.      requires an ANSI C compiler (that understands function prototypes) and
  25.      is not available on all systems.
  26.  
  27. Step 1: Copy the distribution file
  28.  
  29. Copy the distribution file by anonymous ftp from Caltech. Use anonymous ftp
  30. (user: anonymous, password: your id username@machine) to node
  31. astro.caltech.edu (131.215.240.1).
  32.  
  33. The distribution file is a UNIX tar file compressed with Gzip. Issue the
  34. following ftp commands to retrieve the file:
  35.  
  36.  
  37.         cd pub/pgplot
  38.         binary
  39.  
  40. To get the PGPLOT distribution:
  41.  
  42.         get pgplot5.1.tar.gz
  43.  
  44. Step 2: Decompress the files
  45.  
  46. UNIX systems:
  47.  
  48. Use Gunzip and tar to decompress the archive and extract its contents. This
  49. will create directory pgplot (and subdirectories) in the current directory.
  50. Make sure that your current directory is where you want to create the
  51. ``PGPLOT distribution'' directory tree.
  52.  
  53.         gunzip -c pgplot5.1.tar.gz | tar xvof -
  54.  
  55. VMS systems:
  56.  
  57. You will need two programs to decompress and extract the contents of the
  58. distribution file: gunzip and vmstar. These programs are not part of VMS,
  59. but are widely available on the Internet. Use gunzip to decompress the
  60. distribution file, e.g.,
  61.  
  62.         $ gunzip pgplot.targz
  63.  
  64. (Substitute the name of the file that you copied in the ftp step). Then use
  65. vmstar to extract the contents of the archive:
  66.  
  67.         $ vmstar/extract/verbose pgplot.tar
  68.  
  69. This will create a subdirectory [.PGPLOT] (and lower-level subdirectories)
  70. in the current directory. Make sure that your current directory is where you
  71. want to create the ``PGPLOT distribution'' directory tree.
  72.  
  73. Step 3: Create the target directory
  74.  
  75. Create a writeable directory in which the PGPLOT library and associated
  76. files will be created. One such directory is needed for each different
  77. operating system and compiler combination (``target system'') that you wish
  78. to support, e.g.,
  79.  
  80. UNIX:   mkdir /usr/local/pgplot
  81. VMS:    create/directory USR:[LOCAL.PGPLOT]
  82.  
  83. Do not try to create the PGPLOT library in the source directory.
  84.  
  85. Step 4: Select device drivers
  86.  
  87. Configure PGPLOT by selecting device drivers from the available list. First
  88. copy the file drivers.list from the distribution directory to the target
  89. directory, and then use a text editor to select device drivers. This file
  90. contains one line for each available device driver: delete the exclamation
  91. mark (!) at the beginning of the line to include the driver, or ensure that
  92. an exclamation mark is present if you want to exclude the driver. Many of
  93. the drivers can be used only on certain operating systems (see notes in
  94. drivers.list), so include only the drivers you plan to use. PGPLOT can later
  95. be reconfigured by restarting the installation at this step. Most
  96. installations should include: the null device (/NULL), PostScript printers
  97. (/PS, /VPS, /CPS, and /VCPS), Tektronix terminals (/TEK, /XTERM, and
  98. possibly other variants), and, if the X window system is available on the
  99. target, the X window drivers (/XWIN, /XSERV). You may also wish to include
  100. drivers for GIF files (/GIF, /VGIF) or some of the other printers.
  101.  
  102. UNIX:   cd /usr/local/pgplot
  103.         cp /root/pgplot/drivers.list .
  104.         vi drivers.list                 (or use your preferred editor)
  105.  
  106. VMS:    set default usr:[local.pgplot]
  107.         copy root:[pgplot]drivers.list []
  108.         edit drivers.list
  109.  
  110. The PGPLOT distribution directory is here called /root/pgplot or
  111. root:[pgplot] by way of example.
  112.  
  113. Step 5 (UNIX systems): Compile the library
  114.  
  115. If your UNIX system is not one of the supported systems, see Porting PGPLOT,
  116. or consult tjp@astro.caltech.edu. If your system is supported, proceed as
  117. follows:
  118.  
  119.   1. Make the target directory your current default directory, e.g.,
  120.  
  121.              cd /usr/local/pgplot
  122.  
  123.   2. Execute the script makemake from the distribution directory: e.g.,
  124.  
  125.              /root/pgplot/makemake   /root/pgplot  sun4
  126.  
  127.      The first argument supplied to makemake is the name of the distribution
  128.      directory.
  129.  
  130.      The second argument is the name of the operating system; if you omit it
  131.      or supply an unrecognized name, makemake will indicate the allowed
  132.      values (currently these include: aix alliant convex cray freebsd hp
  133.      irix linux next osf1 sol2 sun4 ultrix vp2200).
  134.  
  135.      On some operating systems, where more than one Fortran or C compiler is
  136.      available, a third argument is required; usually this is composed of
  137.      the two compiler names separated by an underscore. If you omit it,
  138.      makemake will indicate the allowed values. Note that you need both a
  139.      Fortran compiler and a C compiler to install PGPLOT.
  140.  
  141.      Once you have supplied valid arguments, makemake may complain that it
  142.      can't find the drivers.list file. Go back to step 4!
  143.  
  144.   3. The script makemake generates a file makefile for subsequent use, a
  145.      Fortran file grexec.f that calls the selected device drivers, and a
  146.      text file rgb.txt that contains color definitions for use by routine
  147.      PGSCRN. (If you already have a file rgb.txt, possibly modified with
  148.      your own custom definitions, makemake does not modify it.) So at this
  149.      stage you will have at least the following files:
  150.  
  151.              drivers.list
  152.              grexec.f
  153.              makefile
  154.              rgb.txt
  155.  
  156.   4. Now use the UNIX make command to compile the PGPLOT library following
  157.      the instructions in makefile:
  158.  
  159.              make
  160.  
  161.      By default, make will generate: an object-module library, libpgplot.a;
  162.      a shareable library (if possible on the selected operating system), the
  163.      binary PGPLOT font file grfont.dat, the demonstration programs pgdemo*,
  164.      and a documentation file pgplot.doc. In addition, if the /XWIN and/or
  165.      /XSERV driver was selected in step 4, it will generate a program
  166.      pgxwin_server, and if the /XDISP driver was selected, it will generate
  167.      a program pgdisp.
  168.  
  169.      If this step proceeds satisfactorily, you may want to type
  170.  
  171.              make clean
  172.  
  173.      to remove unneeded intermediate files. You will then have the following
  174.      files in the current directory:
  175.  
  176.              drivers.list
  177.              grexec.f
  178.              grfont.dat              (binary font file)*
  179.              libpgplot.a             (PGPLOT library)*
  180.              libpgplot.so            (shared library, optional)*
  181.              makefile
  182.              pgdemo1 ... pgdemo14    (demonstration programs)
  183.              pgdisp                  (required by /XDISP driver)*
  184.              pgplot.doc              (ASCII documentation file)
  185.              pgxwin_server           (required by /XWIN driver)*
  186.              rgb.txt                 (color name database)*
  187.  
  188.      If you want to copy the compiled version of PGPLOT to another
  189.      directory, you must copy at least the files marked with an asterisk
  190.      (*). The documentation file contains the PGPLOT subroutine
  191.      descriptions, which are also available in the manual.
  192.  
  193.      Solaris 2.x users should define environment variable LD_LIBRARY_PATH (a
  194.      list of directories) to include the directory that contains the PGPLOT
  195.      shared library.
  196.  
  197.   5. A documentation file in HTML format that can be displayed with Mosaic,
  198.      Lynx, Netscape or another HTML reader can be created by typing:
  199.  
  200.              make pgplot.html
  201.  
  202.      This file is created by executing a perl program to extract the
  203.      documentation from the source code. If you do not have perl installed
  204.      on your system, you can access the file on the WWW at
  205.      http://astro.caltech.edu/~tjp/pgplot/subroutines.html. You may need to
  206.      edit the first line of file pgplot/makehtml to include the correct
  207.      commands for invoking perl on your system.
  208.  
  209.   6. A documentation file in LaTeX format (Appendix A of the manual) can be
  210.      created by typing
  211.  
  212.              make pgplot-routines.tex
  213.  
  214.      This file is also created by executing a perl program to extract the
  215.      documentation from the source code. You may need to edit the first line
  216.      of file pgplot/maketex to include the correct commands for invoking
  217.      perl on your system. To print this file, you will need to run LaTeX to
  218.      create a dvi file and a dvi interpreter to print it, e.g. (on Unix
  219.      systems)
  220.  
  221.              latex pgplot-routines
  222.              dvips pgplot-routines -o
  223.  
  224. Step 5 (VMS systems): Compile the library
  225.  
  226.   1. Make the target directory your current default directory, e.g.,
  227.  
  228.              set default USR:[LOCAL.PGPLOT]
  229.  
  230.   2. Don't forget to first copy DRIVERS.LIST into the target directory and
  231.      edit it to indicate which drivers are to be included in the PGPLOT
  232.      installation.
  233.  
  234.   3. Execute the script install.com from the VMS subdirectory of the
  235.      distribution directory, e.g.:
  236.  
  237.              @root:[pgplot.sys_vms]install root:[pgplot]
  238.  
  239.      The first argument supplied to install is the name of the distribution
  240.      directory.
  241.  
  242.      The install script issues messages as it proceeds: it usually takes
  243.      quite a long time. It should generate the following files:
  244.  
  245.              DRIVERS.LIST
  246.              GREXEC.F
  247.              GRFONT.DAT
  248.              GRPCKG.OLB
  249.              GRPSHR.EXE
  250.              GRPSHR.OLB
  251.              PGDEMO1.EXE ... PGDEMO14.EXE
  252.              PGXWIN_SERVER.EXE
  253.              RGB.TXT
  254.  
  255.      The script assumes that you have the current DEC Fortran and C
  256.      compilers installed. A C compiler is required for XWDRIV and X2DRIV and
  257.      the associated programs PGXWIN_SERVER and PGDISP, and for generating
  258.      the C wrapper library CPGPLOT.OLB. If you don't have the DEC C
  259.      compiler, the script will have to be modified.
  260.  
  261.      The script may fail if you redefine any of the common DCL commands like
  262.      PURGE or DELETE.
  263.  
  264.   4. To install the PGDISP program (optional, required if you selected the
  265.      /XDISP device driver):
  266.  
  267.              @root:[pgplot.sys_vms]install root:[pgplot] PGDISP
  268.  
  269.      This adds one file, PGDISP.EXE. The PGDISP program sometimes gives
  270.      compilation problems. Most of these are non-fatal warnings that can be
  271.      ignored.
  272.  
  273.   5. Unlike the UNIX installation procedure, the VMS installation procedure
  274.      does not generate documentation. A list of subroutine synopses in VMS
  275.      help format is available by anonymous ftp from
  276.      ftp://astro.caltech.edu/pub/pgplot/pgplot.hlp. This file can be
  277.      inserted in a help library with a DCL command like
  278.  
  279.              $ library/insert/help pgplot.hlb pgplot.hlp
  280.  
  281. Step 6: Run the demonstration programs
  282.  
  283. Run the demonstration programs on your selected devices and verify that they
  284. run satisfactorily.
  285.  
  286. Before running any PGPLOT program, you must ensure that the environment
  287. variable PGPLOT_DIR is correctly defined. This is the name of the directory
  288. in which PGPLOT will look for the files grfont.dat and rgb.txt (unless
  289. environment variables PGPLOT_FONT and PGPLOT_RGB are defined to override
  290. this default behavior), and, if needed, the X-window server program
  291. pgxwin_server:
  292.  
  293. UNIX csh:       setenv PGPLOT_DIR /usr/local/pgplot/
  294. UNIX sh:        PGPLOT_DIR="/usr/local/pgplot/"; export PGPLOT_DIR
  295. VMS dcl:        define PGPLOT_DIR usr:[local.pgplot]
  296.  
  297. It is also convenient, but not essential, to define a default PGPLOT device
  298. with environment variable PGPLOT_DEV, e.g.
  299.  
  300. UNIX csh:       setenv PGPLOT_DEV      /xwin
  301.  
  302. Other PGPLOT environment variables are described in the manual.
  303.  
  304. When using a UNIX shared library, you may also need to put the PGPLOT
  305. directory in your loader search path, defined in environment variable
  306. LD_LIBRARY_PATH.
  307.  
  308. To run a program in UNIX, type its name (with directory if the current
  309. directory is not in your path):
  310.  
  311.         ./pgdemo1
  312.  
  313. To run a program in VMS, use the RUN command:
  314.  
  315.         run pgdemo1
  316.  
  317. All the demonstration programs prompt for a device name and type. Type a
  318. question mark ? to see a list of the available device types and verify that
  319. PGPLOT has been configured properly.
  320.  
  321. Points to check for: the PGPLOT program correctly reads the font file and
  322. displays superscripts, subscripts and special characters (pgdemo2); the
  323. PGPLOT program can read the color database (pgdemo10); on interactive
  324. devices, the cursor works correctly (pgdemo5, pgdemo6).
  325.  
  326. Step 7: Install the C binding
  327.  
  328. Optionally, install and test the C binding for PGPLOT. This requires an ANSI
  329. C compiler (that understands function prototypes) and is not available on
  330. all systems.
  331.  
  332. UNIX:   make cpg
  333.  
  334. This creates three files:
  335.  
  336.         cpgplot.h       (ANSI C header file)
  337.         libcpgplot.a    (library containing the C binding)
  338.         cpgdemo         (demonstration program)
  339.  
  340. VMS:    @root:[pgplot.sys_vms]install root:[pgplot] CPG
  341.  
  342. This creates three files:
  343.  
  344.         CPGPLOT.H       (ANSI C header file)
  345.         CPGPLOT.OLB     (library containing the C binding)
  346.         CPGDEMO.EXE     (demonstration program)
  347.  
  348. To test, run cpgdemo in the same way as the other demonstration programs.
  349.  
  350. Step 8: Install the Motif support and example files [optional]
  351.  
  352. Available only in PGPLOT v5.1 and later versions.
  353.  
  354. If you plan to develop Motif applications that use the PGPLOT widget, or if
  355. you want to inspect a sample Motif application, you will need to do this
  356. step. You must first: (a) ensure that the Motif header files and libraries
  357. are installed on your system; (b) select XMDRIV in drivers.list before
  358. installing the PGPLOT library [step 4]; and (c) install the C binding [step
  359. 7].
  360.  
  361. UNIX
  362.  
  363. In Unix installations, the Motif support files and demonstration program are
  364. automatically installed by make if you have selected XMDRIV in drivers.lis
  365. before running makemake, and if Motif is installed on your system. The
  366. following files are installed:
  367.  
  368.         pgmdemo         (executable demo program)
  369.         libXmPgplot.a   (object library required by PGPLOT/Motif applications)
  370.         XmPgplot.h      (header file required by PGPLOT/Motif applications)
  371.  
  372. To test, run pgmdemo in the same way as the other demonstration programs.
  373. You must first ensure that an X-window display is available and that
  374. environment variable PGPLOT_DIR is correctly defined.
  375.  
  376. VMS
  377.  
  378. Execute the folliwing command:
  379.  
  380. @root:[pgplot.sys_vms]install root:[pgplot] PGMDEMO
  381.  
  382. This creates five files:
  383.  
  384.         PGMDEMO.EXE     (executable demo program)
  385.         PGMOTIF.OPT     (linker options file for linking PGPLOT/Motif applications)
  386.         PGXWIN.OBJ      (object module required by PGPLOT/Motif applications)
  387.         XMPGPLOT.OBJ    (object module required by PGPLOT/Motif applications)
  388.         XMPGPLOT.H      (header file required by PGPLOT/Motif applications)
  389.  
  390. To test, run PGMDEMO in the same way as the other demonstration programs.
  391. You must first ensure that an X-window display is available (use
  392. CREATE/DISPLAY if necessary) and that logical name PGPLOT_DIR is correctly
  393. defined.
  394.  
  395. (This step may not work on all VMS systems: there are many differences
  396. between the various available versions of the DEC C compiler and DECwindows
  397. Motif. If you get error messages, you may need to modify file
  398. [pgplot.sysvms]make_pgmdemo.com.)
  399.  
  400. ----------------------------------------------------------------------------
  401. Next: Appendix G
  402. ----------------------------------------------------------------------------
  403. PGPLOT
  404. Tim Pearson, California Institute of Technology, tjp@astro.caltech.edu
  405. Copyright ⌐ 1996 California Institute of Technology
  406.