Building and Installation

Compile-time Options

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

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

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/etc/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/etc/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

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

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

Building the Pine Programs

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

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

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:

To turn on the optimizer

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:

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

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

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

Similarly,

The argument

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

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.

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

There are, however, three optional auxiliary files: /usr/local/etc/pine.info, /usr/local/etc/pine.conf, and /usr/local/etc/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

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]

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

  imap         143/tcp         # Mail transfer 

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

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

/usr/local/etc/pine.conf

Pine's global configuration file.

/usr/local/etc/pine.conf.fixed

Non-overridable global configuration file.

/usr/local/etc/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

<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.