Building and Installation

UNIX Pine Compile-time Options

The files you may need to modify are ./pine/makefile.xxx and ./pine/osdep/os-xxx.h 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 file ./pine/makefile.xxx is where you would set your compiler options. By default, Pine will be compiled with debugging on, optimization and profile 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.

Most of Pine's behaviors are set in the file ./pine/osdep/os-xxx.h, which includes comments that explain each setting. 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:

USE_QUOTAS
Determines whether quotas are checked on startup. Default is to not check the quota.
ALLOW_CHANGING_FROM
Determines whether users are allowed to modify the From line on outgoing mail. Even with this turned on, users will have to include From in their default-composer-hdrs or customized-hdrs in order to be able to edit the From line. Default is to not allow any changing.
DEFAULT_DEBUG
Sets the level of debugging output created in Pine's debug files. Default is level 2.
NEW_MAIL_TIME
Interval between new-mail checks. Default is 150 seconds.
OVERLAP
Number of lines overlap when user views the next page of a message. Default is 2 lines.
USE_TERMINFO
Instructs Pine to use the terminfo database instead of termcap. Default varies by system.
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.
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. (Keyboard lock may also be turned off by adding disable-kblock-cmd to the feature list variable in the global pine.conf file.)


Pico Compile-time Options

There are even fewer options needed when compiling Pico. The two interesting ones are for UNIX Pico versions only. The file that may need some changing is ./pico/os_unix.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.
TERMCAP
TERMINFO
Determines which of these terminal databases will be used.


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 to see the list of ports incorporated into Pine. What you need is the three letter code for the platform. Some examples are nxt for the Next operating system and ult for Ultrix. 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. 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 four binaries built (pine, mtest, imapd, pico) 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.


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 presented as the first page 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 station, 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.
~/.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.
SHELL
If not set, default is /bin/sh
MAILCAPS
A semicolon delimited list of path names to mailcap files.


Support Files and Environment Variables: 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 $HOME\PINE\PINERC or <PINE.EXE dir>\PINERC
Path to (required) personal 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.

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.
PINECONF
Optional path to global pine config file.
HOME
If not set, Pine uses the root of the current drive, e.g. C:
TMP or TEMP
Specifies location of temporary storage area
COMSPEC
Specifies shell for external commands.
MAILCAPS
A semicolon delimited list of path names to mailcap files.