# x3270 Build and Install Instructions

## Where Things Get Installed

By default, parts of x3270 are installed under two different directories.

Files which are specific to X11 (the x3270 binary, x3270 manual pages, and fonts) are installed in the system X11 directory (typically `/usr/X11R6` or `/usr/openwin`). This directory is defined when your system is installed and cannot be easily changed. This is referred to as xdir in the table below.

Files which are shared with other non-X11 3270 applications (the x3270if and pr3287 binaries and man pages, and the configuration files) are installed in the autoconf prefix directory, typically `/usr/local`. The autoconf prefix directory can be changed with options to the x3270 `configure` script. This is referred to as prefix in the table below.

Files | Installed In
Binary for x3270 | xdir`/bin`
Manual pages for x3270 | xdir`/man`
Fonts | xdir`/fonts/misc`
Binaries for x3270if and pr3287 | prefix`/bin`
Manual pages for x3720if and pr3287 | prefix`/man`
Configuration files (`ibm_hosts`, character set definitions) used by x3270 and other programs | prefix`/etc`

If you want everything installed in your system X11 directory, use the following `configure` command:

>     configure --with-all-xinstall

By contrast, if you want everyting to be installed in the autoconf prefix directory, use the default `configure` command, but use a different `make` target:

>     make install.byprefix

## Vanilla X11R6 or X11R5

x3270 is set up to build and install without modifications under any complete X11R6 or X11R5 implementation.

A "complete" R6 or R5 implementation means that xmkmf and imake are configured and installed on your system, and that the `Xaw` and `Xmu` libraries and header files are installed. Some vendors (HP, IBM, SCO) consider these optional software and do not always install them.

If you are running vanilla X11R6 or X11R5, then the build procedure is to ensure that your X11 `bin` directory is in your `$PATH`, then:

        ./configure         # probe for system dependencies and create the Makefile
        make depend         # add dependency information
        make                # build x3270 and its fonts

x3270 prefers that its fonts be installed in order to run. However, a script is provided for testing a local copy of x3270 in the current directory:

        ./dryrun            # test x3270

Once you are satisfied that x3270 is working, you can install it (as root) with the command:

        make install
        make install.man

Before running x3270, you will also need to (once):

        xset fp rehash

That's the easy way. Here are the exceptions:

## IBM AIX

AIX X11R5 does not include xmkmf or imake, but it includes the source code for them. If these have not been built and installed on your system (e.g., if there is no such file as `/usr/bin/X11/imake`), you must first build and install them by following the instructions in `/usr/lpp/X11/Xamples/README`.

Once these have been installed, you can use the standard X11R5 build procedure above.

The default installation of AIX may also not include the bdftopcf utility, which may need to be installed separately as part of the X11.fnt.util package.

## HP-UX A9.01, X11R5

HP's X11R5 distribution does not include the `Xaw` libraries or header files. As HP's X man page says,

> A number of unsupported core MIT clients and miscellaneous utilities are provided in /usr/contrib/bin. In addition, the entire core MIT distribution, compiled for Hewlett-Packard platforms, can be obtained from HP's users group INTERWORKS for a nominal fee. See the release notes for details.

What you need is the `Xaw` and `Xmu` libraries, imake, and xmkmf. Then you can follow the vanilla R5 build and install instructions.

## Sun Solaris 2.x

Follow the instructions for Vanilla X11R6, with the following changes.

### Using Sun's Unbundled C Compiler

Do not use Sun's "BSD-compatibility" C compiler, `/usr/ucb/cc`. This is good advice in general, and in particular, x3270 will not build under it. To build x3270 with Sun's unbundled C compiler, you should have `/opt/SUNWspro/SCx.x/bin` (replacing x.x with the actual version of the compiler) in your $PATH, before `/usr/ucb`.

You might also want to take advantage of the Sun compiler's optimization features. This can be done with the command line:

>     make CDEBUGFLAGS=-x02

### Using gcc

Sun's xmkmf configuration puts some compiler flags in the `Makefile` that are specific to Sun's unbundled C compiler, and you will get a number of harmless, but annoying error messages when compiling with gcc. To eliminate these, use the command:

        make CDEBUGFLAGS=-O CCOPTIONS="-DSYSV -DSVR4"

### Running x3270

To run x3270, your `LD_LIBRARY_PATH` environment variable must include `/usr/openwin/lib`.

## Mixed X Environments

If you are running a mixture of X environments, such as running a Sun XNews server but using X11R6 libraries and header files, the supplied `Imakefile` may not work properly, because it assumes that your server and libraries are of the same type. This is not an impossible situation, just a difficult one. It generally means that you will have to build and install the fonts separately, perhaps even by hand.

## Building Fonts for X Terminals

The Imakefile that comes with x3270 assumes that you plan to run the x3270 client on the same workstation as your X server. Therefore it builds fonts for that kind of X server. Compiled fonts (.snf or .pcf files) are not compatible between different servers, so if you run x3270 with its display somewhere else (such as on an X Terminal), you will need to compile the fonts for that server. It is impossible to give comprehensive instructions here; however, here is an outline for how to do it:

Copy all of the `.bdf` files from the x3270 distribution into a new directory, say `XXX`.

cd into `XXX`.

For each `.bdf` file, run the server-specific version of bdftosnf or bdftopcf to create a `.snf` or `.pcf` file. For example, for to build an NCD font on a Sun-4, the command is:

            /usr/local/NCD/binSun4/bdftosnf 3270.bdf >3270.snf

Run the server-specific version of mkfontdir. For example:

            /usr/local/NCD/binSun4/mkfontdir .

Then tell your X server to use this directory:

            xset fp+ XXX
            xset fp rehash

## SCO Open Desktop 3

x3270 requires the Athena Widgets library, which is available from sosco.sco.com.

## Building on FreeBSD

FreeBSD's iconv library is installed in `/usr/local`, so the the following options must be passed to the `configure` script:

           ./configure LDFLAGS=-L/usr/local/lib CPPFLAGS=-I/usr/local/include

## Using an app-defaults File

Earlier versions of x3270 required a separate app-defaults file. The app-defaults file contains definitions for options, text strings, fonts, colors, etc. The file allows x3270 to be reconfigured without recompiling by simply editing the file.

Unfortunately, using an app-defaults file is a pain. The mechanism for finding the file is so flexible as to be almost incomprehensible, and it is difficult to run the program without doing a full installation, requiring root access to your system. Also, the app-defaults file generally changes whenever the program changes, and making sure that x3270 finds the correct app-defaults file compounds the above problems.

Starting with version 3.1.0.0, x3270 no longer uses a separate app-defaults file. Instead, the file is compiled into x3270 itself. If however, you prefer to have a separate app-defaults file, you can compile x3270 to use it.

First, you must decide whether you want app-defaults for a color display or a monochrome display. For a color display, the commands are:

            ./configure --enable-app-defaults
            make clean
            make

For a monochrome display, the commands are:

            ./configure --enable-app-defaults=-UCOLOR
            make clean
            make

## Summary of `configure` Options

The x3270 `configure` script accepts the following options:

`--help` | Print a help message.
`--with-all-xinstall` | Install all files (even those that are common with other non-X11 3270 programs) in the system's X11 directory. This is compatible with earlier releases of x3270. It is equivalent to `--prefix='$(PROJECTROOT)'`.
`--prefix=prefix` | Install common architecture-independent files under prefix (defaults to `/usr/local`). When using `make install`, this affects only pr3287 and the configuration files. When using `make install.byprefix`, this affects all files.
`--exec-prefix=eprefix` | Install common architecture-dependent files (executables) under eprefix (defaults to same as prefix). See the note under `--prefix`, above.
`--bindir=dir` | Install common user executables in dir (defaults to eprefix`/bin`). See the note under `--prefix`, above.
`--sysconfdir=dir` | Install configuration files (`ibm_hosts`, character sets) in dir`/x3270` (defaults to prefix`/etc`). See the note under `--prefix`, above.
`--enable-app-defaults` `--enable-app-defaults=-UCOLOR` | Use a separate app-defaults file, instead of compiling one into the x3270 executable. With the `=-UCOLOR` option, builds for a monochrome display.
`--without-pr3287` | Don't build pr3287. Useful if you don't need printer session support, or if you want to build pr3287 separately or with different configuration options.
`--with-fontdir=/full-path` `--with-fontdir=relative-path` | Install fonts in an alternate directory. If the parameter starts with "/", it specifies the full pathname of a directory. If not, it specifies a subdirectory of the system's X11 font directory (if using `make install`) or of the `fonts` subdirectory of the architecture-dependent install directory (if using `make install.byprefix`). The default is `misc`.
`--disable-ansi` | Leave out NVT (ANSI) support. Note that NVT support is required for TN3270E support.
`--disable-apl` | Leave out APL character support.
`--disable-dbcs` | Leave out DBCS (Double Byte Character Set) support.
`--disable-ft` | Leave out IND$FILE file transfer support.
`--disable-keypad` | Leave out pop-up keypad support.
`--disable-local-process` | Leave out local process (connecting to "-e shell_command") support. This will be automatically disabled if the local system does not support the forkpty() library call.
`--disable-menus` | Leave out menu support. This is helpful for building kiosk applications where the user cannot reconfigure x3270.
`--disable-printer` | Leave out printer session (pr3287) support.
`--disable-script` | Leave out scripting support.
`--disable-ssl` | Leave out SSL/TLS (Secure Sockets Layer / Transport Layer Security) support. SSL/TLS support requires the OpenSSL library.
`--with-ssl=dir` | Specify the directory where the OpenSSL library is installed.
`--disable-tn3270e` | Leave out TN3270E support.
`--disable-trace` | Leave out tracing support.

Leaving out all of the optional features will result in a binary that's about 40% smaller, and doesn't do a whole lot more than a single session of basic TN3270.