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/lib/pine/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/lib/pine/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/lib/pine/pine.info, /usr/lib/pine/pine.conf, and /usr/lib/pine/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

Beginning with the Pine 3.90 release, there is a PC-Pine version that runs under windows using the Winsock network interface. For those who still need to run the DOS version of PC-Pine, there are versions for four different TCP/IP network stacks: FTP Inc's PC/TCP, Novell's LAN Workplace for DOS, Sun's PC/NFS, and WATTCP for packet drivers. PC-Pine needs to be able to interact closely with the stack loaded on your PC. Most of the time, this occurs automatically. However, there are certain modifications that need be made.

LAN Workplace for DOS Version 4.1
Set the environment variable EXCELAN in the PC's AUTOEXEC.BAT file. This provides the necessary links so that LAN Workplace for DOS 4.1 can translate domain names to IP numbers correctly. It is needed because Pine was developed for LAN Workplace 4.0 and this particular variable is treated differently in 4.1 than in 4.0. The EXCELAN variable must point to the directory in which LAN Workplace is installed.
PC/TCP versions before 2.2
You need a file called PCTCP.INI which contains a bare-minimum 2-line description of the PC's configuration. It looks like this:
		[pctcp ifcust 0]
		ip-address=xx.xx.xx.xx
Where xx.xx.xx.xx is the IP address of the PC. Pine also requires an environment variable, PCTCP, which points to this file. For example:
		set PCTCP=C:\PINE\PCTCP.INI
Packet Drivers
Pine needs to be made aware of the PC's network configuration file. Simply edit the file WATTCP.CFG included in the Pine distribution. The file includes 5 configuration settings--IP-address, gateway, netmask, nameserver(s) and domainslist. If you have a network configuration file for NCSA Telnet then WATTCP.CFG is just a pared down version of the CONFIG.TEL file you already made. Take a look at CONFIG.TEL to find the correct settings for WATTCP.CFG. Once the configuration file is made, the DOS environment variable WATTCP.CFG needs to point at it. For example:
		set WATTCP.CFG=C:\PINE

In addition to networking software issues, you might need to worry about setting the time zone. PC-Pine includes the time zone as part of outgoing email. There is a generic way for PC applications to get the time zone, but, because PC-Pine is one of a very few applications which requires this information, time zone might not be previously configured.

The trick is to add an environment variable, TZ, to your PC's AUTOEXEC.BAT file. The format for the TZ environment variable is as follows:

	ZZZ[+H]H[:MM:SSTTT]
First is the 3-letter code for your standard time, then a "+" or a "-" for direction of offset from GMT, then the amount of offset (hours, minutes, seconds) and finally the 3-letter code for your summer- or daylight savings time. Everything in [] brackets is optional.

The default time zone is "PST-8PDT" (U.S. Pacific Time). Coincidentally, Microsoft is headquartered in that time zone.

As an example, people in the Eastern part of the US should add this line to their AUTOEXEC.BAT files:

	TZ=EST-5EDT

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/lib/pine/pine.conf
Pine's global configuration file.
/usr/lib/pine/pine.conf.fixed
Non-overridable global configuration file.
/usr/lib/pine/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.