Pine Technical Notes: Notes for Porting and Modification

# Notes for Porting and Modification

## Porting Pine to Other Platforms

Substantial effort has gone into making Pine/Pico portable. There are still, of course, a number of machine dependencies. Some of the ports are well-tested and some are untested. In particular, the most heavily used ports are the Ultrix, AIX, NeXT, Windows, and Dec Unix ports.

Each platform is given a three letter name (see the file `doc/pine-ports`). Make up a new one for your new port. We've attempted to bring all potential platform dependencies into the files: `{pico,pine}/osdep/os-xxx.h`, `{pico,pine}/osdep/os-xxx.ic`, and `{pico,pine}/makefile.xxx`, where xxx is the three letter name of the port. Thus any new port will hopefully just result in new versions of these files and some notes for the pine-ports file. There are separate dependencies in the c-client source, but that is handled in separate documentation there. Regrettably, the source code is also full of instances of ifdef DOS. Most of these are due to memory limit problems on DOS as opposed to actual system dependencies.

The makefiles are kept as simple and straight-forward as possible, because many previous attempts at automatically figuring out what to do seem to have become complex and ineffective in what they set out to do: which is to make compiling and installing the program easy. Each port is for a specific hardware/software platform, also because past attempts to generalize on versions of Unix or some CPU architecture don't seem to have gained much. Thus, there is a separate makefile for each platform that calls the appropriate compiler and linker with the appropriate flags. Most of these makefiles are pretty similar. The makefile also specifies which of the os-xxx.c and os-xxx.h files to use. It is the root from which most platform dependencies are selected. In most cases the makefile also defines a symbol named after the platform on which there can be dependencies in the source code, though we've tried to minimize relying on this where reasonable. When different "ports" are very similar, it is sometimes possible to use the same pine code (for example) with only a small change in the c-client or pico code. In those cases, that kind of dependency is reflected in the top-level build script. The build script can usually be used to invoke the various makes correctly. It may set some variables before running make so look to see what build does before trying a make in one of the subdirectories. This is especially true if LDAP is being included.

It is almost always easier to start with an existing port when trying to port to a new system. There is a port called gen (generic) which may be a good starting point. On the other hand, if another port is close to what you want, start with it instead.

The file `pico/osdep/os-xxx.h` contains most of the general platform dependent #include's and #defines. There are a number of Pine configuration settings that are defined in `pine/osdep/os-xxx.h`, as well, such as the place it looks for certain files, defaults for the printer and folder names, the maximum screen size, and so on. Start by looking at the generic `pico/osdep/os-gen.h` file and comparing it to some of the specific `os-xxx.h` files there.

The `osdep/os-xxx.c` files contain functions that are potentially platform dependent. Again, the idea is to gather all the dependencies in one place. We use a complicated looking method to produce the os-xxx.c files from a set of included files. Each included file usually contains a single implementation method and we've found that there are usually only two or three different methods in the ports we've done so far. Hopefully, coming up with an `os-xxx.c` for a new port will usually be a matter of including the right set of these already written functions. This is done by writing a new `os-xxx.ic` file in the `osdep` subdirectories. Starting with the generic `os-gen.ic`, as you did with the `os-gen.h` file above, may be a useful strategy.

We strongly encourage that no changes be made to the general source when porting and that all changes be contained in the system dependent files if possible. The object is to maintain source code integrity and assimilate ports to new platforms rapidly. The more conventional way to do this is with a large collection of #ifdefs. The problem with this is that adding a port for a new platform implies changing the source code for all the other platforms and thereby risks breaking them. (We readily admit that there are still too many ifdefs in the code.)

If you do port Pine to a new platform we hope that you will send us the changes required so that we may attempt to include it in a later release. Thanks!

## Test Checklist

The following is a checklist of some things to check when testing a new port:

___
  Sending mail, check that headers are correct
___
  Sending mail with attachments
___
  Sending mail with SMTP server
___
  Sending mail without SMTP server
___
  Sending mail with list of two SMTP servers, first one doesn't answer
___
  Replying to and forwarding a message
___
  Postponing messages under composition
___
  Composer operations
___
  Alternate editor, enable-alternate-editor-implicitly
___
  Make sure local user names are expanded
___
  Test spelling checker
___
  Catching of SIGHUP while message is being composed
___
  Setting of variables in `.pinerc`
___
  New mail notification. Should happen with Pine idle to check timeouts
___
  Reading mail (attachments, MIME, MIME with mailcap viewers)
___
  Deleting, undeleting, expunging, sorting
___
  Expunge to empty folder
___
  Make sure that ~ expansion works in config files
___
  Make sure that $VAR expansion works in config files
___
  Save message to folder, check error conditions such as permission denied
___
  Export message with FullHeaderMode on and off
___
  Checkpointing (see the section on checkpointing)
___
  Open IMAP and RIMAP folders
___
  Default-fcc on remote IMAP server
___
  Fcc-name-rule, fcc in addrbook (while composing)
___
  Test opening bogus folders: invalid format, no permission
___
  Open a USENET news group, list in folder-lister, read news, post news
___
  Command line arguments
___
  Change password
___
  Lock keyboard
___
  Address book operations (edit, delete, add, lists, whereis, composeto)
___
  ReadOnly address book
___
  Look at addrbook, change addrbook-sort-rule in Config, go back to addrbook screen
___
  No permission to write in same directory as addrbook, should create addrbook.lu in a temp directory
___
  Multiple address books
___
  Address book loops from one addrbook to another and back
___
  TakeAddr command with one address, with multiple addresses
___
  TakeAddr command with ReadOnly address books
___
  TakeAddr command with one of two address books ReadOnly
___
  Send mail with empty address book
___
  Config Screen operation, does pinerc get written?
___
  Make sure SIGTSTP, ^Z works
___
  Sent-mail pruning (set back last-time-prune-questioned variable)
___
  Printing using all three printer configurations, various screens
___
  View help text and news
___
  Folder list operations (rename, create, delete...)
___
  Saved-msg-name-rule
___
  Screen redrawing in various screens (^L)
___
  Window resizing in various screens
___
  Error messages for incorrect terminal types (try "foo" and "vt52")
___
  Reading of `/usr/local/lib/pine.conf`
___
  Fixing variables and features in `/usr/local/lib/pine.conf.fixed`
___
  Flag command (check message status changed in mail folder)
___
  Initial-keystroke-list
___
  Aggregate operations (save, delete, export, takeaddr, ...)
___
  Build xxx from scratch, build clean