DPUSER - The Next Generation: Installing
Author: Thomas Ott

# Installing DPUSER

There are two ways to install DPUSER: Either you grab the binary, or you compile it yourself. Both steps are described in the following.

### Binary installation

Binary versions of DPUSER are available for Linux and Windows. Grab either the dpuser.tgz (Linux) or dpuser.zip (Windows) files. Note that the Linux binary is statically linked (to avoid problems with missing libraries) which means it is rather big (several MB). If you want to avoid this, you have to compile DPUSER yourself.

- Linux: Extract the files to a directory in your PATH. Also, you have to set an environment variable PGPLOT_DIR to this directory. The tar-file contains the following files:

- dpuser - This is the DPUSER program itself
- pgxwin_server - PGPLOT server program for X-Windows
- rgb.txt, grfont.dat - PGPLOT support files

- Windows: Extract the files somewhere in a directory, e.g. C:\Programme\dpuser. Start the dpuser.exe programme. The zip-file contains the following files:

- dpuser.exe - This is the DPUSER console application
- cygwin1.dll, cygpng2.dll, cygz.dll - Support libraries
- rgb.txt, grfont.dat - PGPLOT support files

### Compiling DPUSER

If you want to compile DPUSER yourself, grab the dpusersrc.tgz file. Priour to compiling DPUSER itself, you have to compile support libraries which are used by DPUSER (the link in the following list points to where you can get the library):

- pgplot - Plotting package. DPUSER uses version 5.2.2
- fftw - the Fastest Fourier Transform in the West. DPUSER uses version 2.1.3
- cdl - Client Display Library - see note below
- zlib - Library for reading compressed files
- readline - User input library
- QT - Some platform-independent functions. DPUSER uses version 2.2.3 or higher

These are the detailed steps (these apply to LINUX and WINDOWS using the cygwin environment). Replace `DPUSERDIR` by the directory name where you extracted the dpusersrc.tgz archive:

1. Unpack the DPUSER source archive:
   `tar -xvzf dpusersrc.tgz`
2. Create two additional directories:
   `mkdir DPUSERDIR/lib
   mkdir DPUSERDIR/include`
3. Compile FFTW: I usually do the following:
   `./configure --prefix=/tmp/brgx --enable-i386-hacks
   make` (You can drink some coffee now)
   `make install
   cp /tmp/brgx/include/*.h DPUSERDIR/include
   cp /tmp/brgx/lib/*.a DPUSERDIR/lib
   rm -rf /tmp/brgx`
4. Compile PGPLOT. If you are using WINDOWS, follow the steps described at the end.
   `cp *.a DPUSERDIR/lib
   cp cpgplot.h DPUSERDIR/include`
5. Compile CDL, but first replace the file `cdl.c` by an updated version:
   `cp Makefile.generic Makefile
   make
   cp libcdl.a DPUSERDIR/lib
   cp cdl.h DPUSERDIR/include`
6. Now compile DPUSER itself:
   `cd DPUSERDIR/src
   cp config.[whatever your system is] config.h
   cd ..
   make`

Compiling these libraries should be straight-forward and is well documented. Note that for pgplot, you need a Fortran77 Compiler. Place all the libraries together with their include files in a directory named "external". If you already have some of these libraries on your system, you of course don't need to compile them again.

Next step is to untar the dpusersrc.tgz file. This will create three more directories: dpuser, libfits, and utils. A top-level Makefile is generated and can be used to compile DPUSER. At the end, you should end up with a dpuser executable. After compiling, follow the instructions in the "Binary installation" section of this document to get going.

### Notes on specific platforms

- Windows: The Client Display Library does not work with the Microsoft Compiler. If you need that functionality, you have to use the Cygwin environment. Also, the readline library is not compatible with Windows. Use the windpuser.exe programme which provides similar functionality.
- All platforms: The cdl library lacks a feature to display images without zScale-ing. Grab an updated cdl.c.
- Compiling PGPLOT using Visual Studio: Do the following:

- Create a Directory "vcpgplot"; Copy the following files to this directory:

- all files in the pgplot/src directory
- the selected drivers from pgplot/drivers (nudriv.f, psdriv.f, widriv.c in my case)
- all Fortran files in the pgplot/sys directory
- the file pgplot/sys/grdate.c
- the file pgplot/sys_dos/gruser.f
- a suitable grexec.f file (Create yourself or copy from here)
- the files pgplot/cpg/pgbind.c and pgplot/cpg/pgbind_prototypes
- the files pgplot/fonts/grfont.txt and pgplot/fonts/pgpack.f
- the file pgplot/rgb.txt

- Get f2c for windows and copy the files f2c.exe, f2c.h, and vcf2c.lib to the directory
- In Visual Studio, create a project "pgbind" (Console Application) and add the pgbind.c file. Compile and execute "pgbind bsd -h -w -suffix "_" -case lower pgbind_prototypes" (I add this as a post-build step)
- Create another Console Application "pgpack", add pgpack.f with Custom Build Rule (running f2c), add pgpack.c, compile and execute "pgpack < grfont.txt" (I add this as a post-build step)
- Create a new project "libpgplot" (Static Library) and add all Fortran files (except pgpack.f). Select all of them and edit the Custom Build Settings:

- Commands: f2c $(InputPath)
- Outputs: $(InputName).c

- Compile the library. Then add all C-Files (except pgbind.c and pgpack.c) and all H-Files to the project. In the project Settings, the C preprocessor must define a symbol PG_PPU (This is in the C/C++ Tab, Category General). Compile the library again. Now you have created a "libpgplot.lib".
- As a last step, you can compile the example programs. Note that the Fortran files again need the f2c Custom Build Setting.

### PGPLOT with WINDOWS

PGPLOT comes without satisfactory display driver for WINDOWS. I have written a simple one which you can download here (widriv.c). To get PGPLOT going, do the following:

1. Follow the standard instructions first:
   `mkdir pgdist
   cp pgplot/drivers.list pgdist`
   Edit `pgdist/drivers.list` and include the drivers you want (I use NUDRIV, PSDRIV, and PNDRIV
   `cd pgdist
   ../pgplot/makemake ../pgplot linux g77_gcc`
2. Now you have to edit the file `grexec.f`:
   - Locate the line
     `PARAMETER (NDEV=7)`
     Replace this by:
     `PARAMETER (NDEV=8)`
   - In the line where it says something like
     `GOTO(1,2,3,4,5,6,7) IDEV`
     add one more number (in this example `GOTO(1,2,3,4,5,6,7,8) IDEV`)
   - Just before the end of the file, add the following lines:
     `8 CALL WIDRIV(IFUNC,RBUF,NBUF,CHR,LCHR)
     RETURN`
3. You also have to edit `makefile`:
   Locate these lines:
   `#
   # Loader command for PGPLOT library
   #
   ` and add `-lgdi32` to both `PGPLOT_LIB` and `CPGPLOT_LIB`
   Locate the `DRIVERS=` line and add `widriv.o`
   Locate these lines:
   `#-----------------------------------------------------------------------
   # Rules for compiling the .o files
   #-----------------------------------------------------------------------
   ` At the end of this section (which is pretty long), add these lines:
   `widriv.o: widriv.c
   $(CCOMPL) -c $(CFLAGC) widriv.c
   `
4. Copy the file widriv.c to the pgdist directory.
5. Do a
   `make`
   For me, this bails out when trying to build the shared library. You can safely ignore this error.
   `make cpg`
6. Now copy the files `libpgplot.a`, `libcpgplot.a` to `DPUSERDIR/lib` and `cpgplot.h` to `DPUSERDIR/include`