Pine Technical Notes: Building and Installation

# Building and Installation

## Compile-time Options

The files you may need to modify are `./{pico,pine}/makefile.xxx`, `./{pico,pine}/osdep/os-xxx.h`, and possibly `./{pico,pine}/osdep/os-xxx.ic`, where xxx is the 3-letter code for your platform. You can give the command `build help` to see the list of ports incorporated into Pine and their associated 3-letter codes. The files `./{pico,pine}/makefile.xxx` are where you would set compiler options. By default, Pine will be compiled with debugging on, optimization and profiling off. Note that if you compile with DEBUG off, then Pine will not create its normal debug files, no matter how the debug-level and debug command line flag are set.

Some of these can only be set when you compile. Others, however, can be overridden by command-line flags to Pine or settings in Pine's user or system configuration files. Some of the options which can be set when compiling:

### Including LDAP Functionality

In order to build Pine with LDAP functionality included you need to supply the LDAP library and include files. Pine has been successfully built with OpenLDAP 2.0.x, OpenLDAP 1.x, the University of Michigan LDAP library (ldap-3.3), and with the Netscape Directory SDK 1.0 LDAP library.

Set up a symlink called `ldap` in the top-level `pine` directory (the directory where the Pine `build` script is located). The `build` script will call `contrib/ldap-setup` to help figure out how to use the LDAP libraries. It expects to find directories `ldap`, `ldap/include`, `ldap/libraries`, and file `ldap/include/ldap.h`.

There are at least two slightly different styles of LDAP libraries. One style uses two libraries, libldap and liblber, the other uses just libldap. The script is not very smart, but it attempts to figure out which of these two cases is being used. Modify the script to fit your situation if you need to.

When using OpenLDAP as the library (or the older University of Michigan libary), set up the symlink so that it points to the base of the ldap source tree. The ldap-setup script looks for the directory `ldap/libraries/liblber` and the libraries `ldap/libraries/libldap.a` and `ldap/libraries/liblber.a`.

To use the Netscape Directory SDK library, make a directory called `ldap` in the top-level `pine` directory (where the Pine `build` script is located). That directory should contain two subdirectories, `include` and `libraries`. The `include` directory is where you should put the include files from the Netscape SDK. The `libraries` directory is where you should put the library, `libldap.a`.

The `build` script will run the script `contrib/ldap-setup` if you have created an `ldap` symlink or directory. It tries to figure out if the setup is the Univ. of Michigan code or not. If it is Univ. of Michigan ldap-3.3 or the library from `mozilla.org`, then it will link against both `libldap.a` and `liblber.a`. If it isn't, it will link against only `libldap.a`. You may find you have to do some tweaking to get this to work with the libraries you are using. If you find that a change to `contrib/ldap-setup` works for you, you might think about sending that to us for inclusion in the next Pine release.

If there is no `ldap` symlink, there is still an attempt to automatically include LDAP support if certain conditions exist. At this point, the check includes a check for Solaris 8, otherwise the automatic inclusion is not done. You may override the automatic inclusion of LDAP with the `build` argument `NOLDAP`.

Pine uses LDAPv2 protocol. When using LDAPv3 protocol, the results are returned in the utf8 character set. Pine is not yet ready to deal with that, so it tells the server to use the LDAPv2 protocol.

### Including Kerberos 5 Functionality

In order to build Pine with Kerberos functionality included you should place a symlink called `krb5` to the directory where your Kerberos5 include files and libraries are located. That is, `krb5/include` and `krb5/lib` should exist. Place the symlink in the top-level `pine` directory (where the Pine `build` script is located). See the comments in the script `contrib/krb5-setup` if you have trouble.

### Pine Compile-time Options

USE_QUOTAS
  Determines whether quotas are checked on startup. Default is to not check the quota.
ALLOW_CHANGING_FROM
  This is now a hidden runtime feature called allow-changing-from. Even with this feature turned on, users still have to include From in their default-composer-hdrs or customized-hdrs in order to be able to edit the From line.

  Beginning with version 4.10, a user may also change their From address by using Roles.

  A system administrator may disallow editing of the From line by putting the feature no-allow-changing-from in the system-wide fixed configuration file. The paranoid system administrator can compile in this behavior by defining NEVER_ALLOW_CHANGING_FROM in `./pine/osdep/os-xxx.h`.

DEFAULT_DEBUG
  Sets the level of debugging output created in Pine's debug files. Default is level 2. The command-line flag -d may also be used to change the debug level. For example, `-dverbose=7`.
NUMDEBUGFILES
  Sets the number of debug files kept per user. Default is 4. The command-line flag -d may also be used to change this. For example, `-dverbose=3,numfiles=2`.
BACKGROUND_POST
  Define this if you want to allow users to turn on the feature that enables sending to take place in a fork()'d child. This may reduce the time on the user's wall clock it takes to post mail. NOTE: You'll also have to make sure the appropriate `./pine/osdep/postreap.*` file is included in the `./pine/osdep/os-xxx.ic` file for your system.
NEW_MAIL_TIME
  Interval between new-mail checks. Default is 150 seconds. This is obsolete. This should be set in a configuration file by setting the variable mail-check-interval.
OVERLAP
  Number of lines overlap when user views the next page of a message. Default is 2 lines. This is obsolete. This should be set in a configuration file by setting the variable viewer-overlap.
PASSFILE
  WARNING! Turning this on is very dangerous and should probably not be done, except on single user systems! For PC-Pine, this is turned on by default and set to the filename `PINE.PWD`. It may be overridden by the -passfile command-line argument. You may enable it for Unix systems by defining PASSFILE to be a filename which will be located in the same directory as the pinerc file, usually the home directory.

  The file is used to save passwords from one session to the next. Even if you define PASSFILE when you compile Pine, password saving will not be enabled by default, but requires the existence of the file (the name of which is the value of PASSFILE). Even with the existence of this file, the user must still acknowledge a prompt before the password is saved to the file. If Pine is configured to access several different IMAP servers, each password entered will be kept (associated with the corresponding host name) in memory during the current session, and optionally, in the PASSFILE file for use in subsequent sessions.

  WARNING! Use this feature with caution! It effectively makes the user's mail no more secure than the physical security of the machine running Pine. What's more, while the password is cloaked by a mild (some might say, feeble) encryption scheme, it is nonetheless sitting in a file on the disk and subject to cracking by anyone with access to it. BEWARE!

SENDMAIL
SENDMAILFLAGS
  Sets the name and flags for the local program that will be called to handle outgoing email. Default is `/usr/lib/sendmail -oi -oem -t`. See the SMTP and Sendmail section for more details.
SYSTEM_PINERC
  The name of the file which holds Pine configuration information for all users on the system. Default on UNIX systems is `/usr/local/lib/pine.conf`.
SYSTEM_PINERC_FIXED
  The name of the file which holds the same type of information as for SYSTEM_PINERC, but only for variables that the administrator wants to keep fixed. That is, users are not allowed to change variables that are specified in the FIXED file. Default on UNIX systems is `/usr/local/lib/pine.conf.fixed`.

There are a couple of more obscure options which are in the source code because a few people have asked for them or because we changed our minds about them being a good idea in general.

ENCODE_FROMS
  Use Quoted-printable encoding so that `From`'s at the beginning of lines don't end up being escaped by >'s. Most people seem to dislike the Q-P encoding more than the > escapes so this is off by default. Once everyone has MIME mail readers, we'll turn this on by default.
NO_KEYBOARD_LOCK
  Disable the keyboard locking function in the main menu. Keyboard locking is enabled by default. An easier way to turn off Keyboard locking is to add the feature disable-keyboard-lock-cmd to the feature list variable in the global `pine.conf` or `pine.conf.fixed` file.

### Pico Compile-time Options

There is really only one option settable specifically for Pico. It is for the UNIX Pico versions only. The file that may need some changing is `./pico/osdep/os_xxx.h.`. Whatever is set will effect the behavior of the Pico stand-alone program as well as the composer within Pine.

SPELLER
  Names the program called to do "normal" spell-checking. This can be set in a configuration file instead by setting the speller configuration variable.

### OS Dependent Compile-time Settings

Most of Pine's (and Pico's) operating system dependent behaviors are set in the files `./pico/osdep/os-xxx.h` and `./pico/osdep/os-xxx.ic`. The flags in the makefiles are also system dependent. See the comments in `./pico/osdep/os-xxx.h` for more details. One that may come up is:

USE_TERMINFO
USE_TERMCAP
  Instructs Pine to use the terminfo (or termcap) database. Default varies by system. This has been moved from `./pine/osdep/os-xxx.h` to `./pico/osdep/os-xxx.h`. If you change this you will also have to change the file `./pico/osdep/os-xxx.ic` so that it includes the file `term.inf` instead of `term.cap` (or vice versa) and you will probably have to change the libraries included by the makefiles `./{pico,pine}/makefile-xxx`. Hopefully, it is already set correctly for each system.

### IMAPd Compile-time Options

There are no options or settings required for the version of IMAPd distributed with Pine. If you need to be doing more complex modifications to IMAP, then you should pick up the IMAP development package and work with that code. The developer's version of IMAP is available for anonymous ftp from `ftp.cac.washington.edu` in the directory `mail`. The file is called `imap.tar.Z`.

## Building the Pine Programs

You may have already compiled Pine and tried it out. If so, great! If not, you should be able to do it without too much trouble by following these step-by-step instructions:

1. Figure out what platform you're building for. You can give the command `build help` or look at the list in `./doc/pine-ports` to see the list of ports incorporated into Pine. What you need is the three letter code for the platform. Some examples are `a41` for the AIX 4.1 operating system, `os4` for Digital Unix 4.0, and `lnx` for Linux. There are sometimes several variants for a single operating system (different compilers, shadow passwords or not, etc.) so look through the whole list in `./doc/pine-ports` for the one you want. If your platform is not in the list of ports, then you might have some work ahead of you. First, check the file `doc/pine-ports` to see if there are others working on a port for your platform or to see if the port is included in the `contrib` section of the source code. Ports in the `contrib` directory were contributed by Pine administrators from around the world, but the Pine development team has not been able to test the code. Some of these ports are very old and are based on old versions of Pine. If Pine has not yet been ported to your platform at all, read the section on Porting Pine in this document.

2. Make sure you're in the root of the Pine source. When you type `ls` you should see the following files and directories (or something close to it):

       	README	build	doc 	makefile	pine
       	bin	contrib	imap	pico

3. Make sure you're getting a clean start by giving the command `./build clean`. This should take only a few seconds to run.

4. Give the command `./build` xxx where xxx is the three letter code you picked in step 1. The compiler should grind away for a few minutes.

5. When the compilation is complete the sizes of the binaries built will be displayed. The actual binaries are in the various source directories. In addition, the `bin` directory contains a link to each program compiled. You can just copy them out of `bin` or try them from there.

The `build` command can be given some options which it passes on to the subordinate makes. Some that may be useful are `EXTRACFLAGS`, `DEBUG`, and `EXTRALDFLAGS`. There are also some SSL-related arguments: `SSLDIR`, `SSLCERTS`, `SSLINCLUDE`, and `SSLLIB`. You should also read the comments in the `build` script itself, which are possibly more up-to-date than this text.

Here are some examples of options you may want to pass to `build`. This will turn off the debugging files that Pine produces, while leaving the symbol table information. We believe a better way to do this is to have an alias for `pine` which executes `pine -d0` instead. This turns off debugging at runtime while preserving the possibility of using the debugging if a problem turns up. But if you wanted to turn it off unconditionally you could use the build argument

`DEBUG=-g`

In other words, the command to build a Pine with no debugging would be

`./build DEBUG=-g target`

where target is one of the 3-letter port names found in doc/pine-ports. To also leave out the symbol table information you could pass:

`DEBUG=`

To turn on the optimizer

`DEBUG=-O`

It should be ok to move string constants into a read-only area. We don't think there are any instances where Pine modifies a string constant. So you could pass a flag to your compiler that tells it to do this. This could cause several hundred K of strings to be moved from the data area of the program into the text area of the program, and that should allow that text to be shared among all instances of Pine. To do this, for example, with the AIX a41 port, you could pass this to `build`:

`EXTRACFLAGS=-qro`

If you are using OpenSSL but have decided to use a non-standard directory (standard one is `/usr/local/ssl`) for the location then you can cause Pine to use that directory with

`SSLDIR=/some/other/dir`

The assumption is that the certs directory is in SSLDIR/certs, the include directory is SSLDIR/include, and the library directory is SSLDIR/lib. You can change those assumptions with

`SSLCERTS=certs_directory`
`SSLINCLUDE=include_directory and`
`SSLLIB=ssl_library_directory`

If you are having trouble with the SSL compilation you may explicitly exclude SSL code with `NOSSL`.

`NOSSL`

Similarly,

`NOLDAP`

The argument

`EXTRASPECIALS`

can be used to pass arguments to the c-client make which aren't provided for in the Pine build script. For example, if you want to change the `FRIZZLE` parameter (a made up argument which the c-client make uses) you might be tempted to type something like

`./build FRIZZLE=cruft target`

This does work with make on some platforms, but not on others. Some makes seem to pass the arguments on to sub-makes, others don't. If that doesn't work, then EXTRASPECIALS is for you.

`./build EXTRASPECIALS="FRIZZLE=cruft" target`

An additional warning. There are some arguments which are overridden unconditionally in the sub-makes. Hopefully none of the arguments mentioned above falls in this category, but it is something to look out for if you are having trouble.

## Installing Pine and Pico on UNIX Platforms

Installing Pine and Pico is remarkably simple. You take the program files which you have just transferred or built and you move them to the correct directory on your system. Most often the binaries go in `/usr/local/bin` though sometimes they are placed in `/usr/bin`. All the help text is compiled into Pine so there are no required auxiliary files.

There are, however, three optional auxiliary files: `/usr/local/lib/pine.info`, `/usr/local/lib/pine.conf`, and `/usr/local/lib/pine.conf.fixed`. The file `pine.info` contains text on how to get further help on the local system. It is part of the help text for the main menu and should probably refer to the local help desk or the system administrator. If this file doesn't exist a generic version which suggests ``talking to the computer support staff at your site'' is shown. The file `pine.conf` is used to set system-wide default configurations for Pine. The file `pine.conf.fixed` is also used to set system-wide default configurations for Pine. The difference between these two files is that configuration variables set in the `pine.conf.fixed` file may not normally be over-ridden by a user. See the section on Pine Configuration later in this document for details about the `pine.conf` and `pine.conf.fixed` files.

## Installing PC-Pine

The PC-Pine distribution comes as a .zip file. To install, unzip the files to a directory where you would like the program to reside. Modern Windows versions come with the capability of unzipping .zip files. Failing that, you can use one of the many .zip file extractors out there, or the pkunzip.exe program that resides on our FTP server. Following current Windows conventions, a common directory into which the files could be extracted would be `C:\Program Files\PC-Pine\`.

Having extracted PC-Pine's .zip file to the directory of choice, you can now run that directory's pine.exe, which is the actual PC-Pine program. For convenience, you could place shortcuts to it on the task bar, start menu, etc.

Upon first running PC-Pine, you may be asked where you would like to access your Configuration file (called the pinerc). This is useful in accessing already existing configuration files, and it does not matter where this file gets created. If you are connecting to an IMAP server to access your email, it is also possible to store this Configuration data on that server, which facilitates accessing the same configuration from multiple machines (in fact, your configuration may have already been set up this way for use with other pine programs).

After having established the location of the configuration file, it may be necessary to specify a few configuration settings before reading or sending mail. You may be prompted for the following (which may also be edited from the (S)etup (C)onfig screen from the Main Menu):

- `Folder to open as inbox` (or inbox-path) - This can be an inbox residing on an IMAP or POP3 server, or one residing locally. An example of an INBOX for an IMAP server is: `{server.example.com}INBOX`.
- `User-id`, `Personal name`, and `host/domain`, which are to be used as your email address.
- `SMTP server to forward message` - You must enter your SMTP server before you can send any messages.

  At this point, you will be able to read and send email messages. There are, however, many more preferences that you can set in the Configuration screen.

  ## Installing IMAPd

  When the Pine distribution is built on a UNIX system, the IMAP server binary, `imapd`, is compiled. Installing `imapd` requires placing the binary in the appropriate directory, usually `/usr/etc`, and adding entries to `/etc/services` and `/etc/inetd.conf` or their counterparts. The following line is appropriate for `/etc/services`:

        imap         143/tcp         # Mail transfer

  and the next line is appropriate for `/etc/inetd.conf`:

        imap  stream  tcp     nowait  root    /usr/etc/imapd imapd

  The `/etc/inetd.conf` file entry may vary on different versions of UNIX. Some have a slightly different set of fields. Also the pathname in `/etc/inetd.conf` must match the path where `imapd` is installed.

  With this configuration, the IMAP server runs without pre-authentication. Each new IMAP connection requires a correct username and password. IMAP can also be run with pre-authentication based on the standard rsh mechanism. To enable this, the user account on the IMAP server must contain a valid file which grants access to the client machine. Enabling rimap authentication is done by creating a link called `/etc/rimapd` to `imapd`. Basically, what is happening is that Pine is taking advantage of the ability that `rsh` has to use privileged TCP ports so it doesn't have to run in privileged mode. If the `rimap` authentication fails it will drop back to plain password authentication.

  PC-Pine cannot take advantage of rimap authentication. Also, if your system uses a distributed configuration database, like NIS, Yellow Pages or Netinfo, be sure that appropriate steps are taken to ensure the above mentioned information is updated.

  ## Support Files and Environment Variables: UNIX Pine

  This section lists the various files which Pine uses which are not email folders. All of these are the default names of files, they may vary based on Pine's configuration.
  /usr/local/lib/pine.conf
    Pine's global configuration file.
  /usr/local/lib/pine.conf.fixed
    Non-overridable global configuration file.
  /usr/local/lib/pine.info
    Local pointer to system administrator.
  ~/.pinerc
    Personal configuration file for each user.
  ~/.pinercex
    Personal exceptions configuration file for each user.
  ~/.addressbook
    Personal addressbook
  ~/.addressbook.lu
    Personal address book lookup file (index file to speed up lookups).
  ~/.newsrc
    Personal USENET subscription list. This is shared with other newsreading programs.
  ~/.pine-debugX
    The files created for debugging Pine problems. By default, there are 4 .pine-debug files kept at any time.
  ~/.signature
    A signature file which will be included in all outgoing email messages.
  ~/.pine-interrupted-mail
    The text of a message which was interrupted by some unexpected error which Pine detected.
  ~/mail/postponed-msgs
    A folder of messages which the user chose to postpone.
  /etc/mailcap
    System-wide mail capabilities file. Only used if `$MAILCAPS` not set.
  ~/.mailcap
    Personal mail capabilities file. Combines with system-wide mailcap. Only used if `$MAILCAPS` not set.

  The location of the following support files may be controlled by variables in the personal or global Pine configuration file: signature, addressbook and its index file, postponed messages, and newsrc.

  Unix Pine uses the following environment variables:

  TERM
    Tells Pine what kind of terminal is being used.
  DISPLAY
    Determines if Pine will try to display IMAGE attachments.
  TMPDIR, TMP, or TEMP
    Specifies location of temporary storage area, first one set wins
  SHELL
    If not set, default is /bin/sh
  MAILCAPS
    A semicolon delimited list of path names to mailcap files.

  ## Support Files, Environment Variables, and Registry Settings: PC-Pine

  This section lists the various files which PC-Pine uses which are not normal mail folders. All of these are the default names of files, they may vary based on Pine's configuration.

  <PINE.EXE directory>\PINE.HLP
    File containing Pine's internal help text.
  <PINE.EXE directory>\PINE.NDX
    Index of Pine's help text used by PC-Pine to locate entries.
  $PINERC or <PineRC registry value> or $HOME\PINE\PINERC or <PINE.EXE dir>\PINERC
    Path to (required) personal configuration file.
  $PINERCEX or $HOME\PINE\PINERCEX or <PINE.EXE dir>\PINERCEX
    Path to personal exceptions configuration file.
  $PINECONF
    Path of optional global configuration file.
  <PINERC directory>\ADDRBOOK
    Personal addressbook
  <PINERC directory>\ADDRBOOK.LU
    Personal address book lookup file (index file to speed up lookups).
  <PINERC directory>\PINE.SIG
    A signature file which will be included in all outgoing email messages.
  <PINERC directory>\PINE.PWD
    A file containing encrypted password for remote mail server.
  <PINERC directory>\PINEDEBG.TXT
    Location of Pine debug file.
  <PINERC directory>\MAILCAP and/or <PINE.EXE dir>\MAILCAP
    These paths are only used if $MAILCAPS not set.
  $HOME\NEWSRC or <PINERC directory>\NEWSRC
    Personal USENET subscription list. This may be shared with other newsreading programs.
  $HOME\MAIL\INTRUPTD
    The text of a message which was interrupted by some unexpected error which Pine detected.
  $HOME\MAIL\POSTPOND
    A folder of messages which the user chose to postpone.

  Registry Values:

  HKEY_LOCAL_MACHINE\Software\University of Washington\PC-Pine\4.0
    Pinedir: The directory that contains the Pine executable.
    PineEXE: The name of the Pine executable (most commonly "pine.exe").
  HKEY_CURRENT_USER\Software\University of Washington\PC-Pine\4.0
    PineRC: The path that points to the default pinerc to use.
  HKEY_LOCAL_MACHINE\Software\Clients\Mail\PC-Pine
    DLLPath: The path that points to Pine's pmapi32.dll.
  HKLM\Software\Clients\Mail\PC-Pine\shell\open\command
    (Default): When set as the default mailer, this is the command that is run by external programs.
  HKLM\Software\Clients\Mail\PC-Pine\Protocols\Mailto\DefaultIcon
    (Default): This points to the icon to display in relation to Pine's mailto URL rendering.
  HKLM\Software\Clients\Mail\PC-Pine\Protocols\Mailto\shell\open\command
    (Default): This value is the command that gets run by external programs when a mailto URL is run with PC-Pine set as the default mailer.
  HKLM\Software\Clients\News\PC-Pine\shell\open\command
    (Default): When set as the default newsreader, this is the command that is run by external programs.
  HKLM\Software\Clients\News\PC-Pine\Protocols\news\DefaultIcon
    (Default): This points to the icon to display in relation to _Pine_'s news URL rendering.
  HKLM\Software\Clients\News\PC-Pine\Protocols\news\shell\open\command
    (Default): This value is the command that gets run by external programs when a news URL is run with PC-Pine set as the default newsreader.
  HKLM\Software\Clients\News\PC-Pine\Protocols\nntp\DefaultIcon
    (Default): This points to the icon to display in relation to Pine's nntp URL rendering.
  HKLM\Software\Clients\News\PC-Pine\Protocols\nntp\shell\open\command
    (Default): This value is the command that gets run by external programs when a nntp URL is run with PC-Pine set as the default newsreader.

  PC-Pine's help text and help text index file are expected to reside in the same directory as the `PINE.EXE` executable, as they are essentially extensions of the executable. The personal configuration file may be in the same directory as the executable, or if that is inconvenient because the executable is on a shared or read-only drive, then it can be in a file named by the `$PINERC` environment variable, or in `$HOME\PINE\PINERC`, where if not set, `$HOME` defaults to the root of the current working drive.

  Most of the other support files key off of the location of the `PINERC` file. However, in the case of the NEWSRC file, the path `$HOME\NEWSRC` is checked first. Also, the postponed messages and interrupted message folders are placed in the default folder collection, normally in the directory `$HOME\MAIL`.

  The location of the following support files may be controlled by variables in the personal or global Pine configuration file: signature, addressbook (and its index file), postponed messages, and newsrc.

  PC-Pine uses the following environment variables:

  PINERC
    Overrides default path to pinerc file.
  PINERCEX
    Overrides default path to personal exceptions configuration file.
  PINECONF
    Optional path to global Pine config file.
  HOME
    If not set, Pine uses the root of the current drive, e.g. C:
  TMPDIR, TMP, or TEMP
    Specifies location of temporary storage area, first one set wins
  COMSPEC
    Specifies shell for external commands.
  MAILCAPS
    A semicolon delimited list of path names to mailcap files.