doc/tech-notes/porting.html

   1 <HTML><HEAD><TITLE>Pine Technical Notes: Notes for Porting and Modification</TITLE></HEAD><BODY>
   2 <H1>Notes for Porting and Modification</H1>
   3
   4 <H2><A NAME="new-port">Porting Pine to Other Platforms</A></H2>
   5
   6 Substantial effort has gone into making <EM>Pine</EM>/<EM>Pico</EM> portable.
   7 There are
   8 still, of course, a number of machine dependencies.  Some of the ports are
   9 well-tested and some are untested.  In particular, the most heavily used
  10 ports are the Ultrix, AIX, NeXT, Windows, and Dec Unix ports.  <P>
  11
  12 Each platform is given a three letter name (see the file
  13 <CODE>doc/pine-ports</CODE>).  Make up a new one for your new port.  We've
  14 attempted to bring all potential platform dependencies into the files:
  15 <CODE>{pico,pine}/osdep/os-xxx.h</CODE>,
  16 <CODE>{pico,pine}/osdep/os-xxx.ic</CODE>,
  17 and <CODE>{pico,pine}/makefile.xxx</CODE>, where <EM>xxx</EM>
  18 is the three letter name of the port.  Thus any new port will hopefully
  19 just result in new versions of these files and some notes for the
  20 <EM>pine-ports</EM> file.
  21 There are separate dependencies in the c-client source, but that
  22 is handled in separate documentation there.
  23 Regrettably, the source code is also full of instances of <EM>ifdef DOS</EM>.
  24 Most of these are due to memory limit problems on <EM>DOS</EM> as
  25 opposed to actual system dependencies.  <P>
  26
  27 The makefiles are kept as simple and straight-forward as possible, because
  28 many previous attempts at automatically figuring out what to do seem to
  29 have become complex and ineffective in what they set out to do:  which is
  30 to make compiling and installing the program easy.  Each port is for a
  31 specific hardware/software platform, also because past attempts to
  32 generalize on versions of Unix or some CPU architecture don't seem to have
  33 gained much.  Thus, there is a separate makefile for each platform that
  34 calls the appropriate compiler and linker with the appropriate flags.
  35 Most of these makefiles are pretty similar.  The makefile also specifies
  36 which of the <EM>os-xxx.c</EM> and <EM>os-xxx.h</EM> files to use.
  37 It is
  38 the root from which most platform dependencies are selected.  In most cases
  39 the makefile also defines a symbol named after the platform on which there
  40 can be dependencies in the source code, though we've tried to minimize
  41 relying on this where reasonable.
  42 When different "ports" are very similar, it is sometimes possible to use
  43 the same pine code (for example) with only a small change in the c-client
  44 or pico code. In those cases, that kind of dependency is reflected in
  45 the top-level <EM>build</EM> script.
  46 The <EM>build</EM> script can usually be
  47 used to invoke the various makes correctly.
  48 It may set some variables before running make so look to see what <EM>build</EM>
  49 does before trying a make in one of the subdirectories. This is especially true
  50 if LDAP is being included. <P>
  51
  52 It is almost always easier to start with an existing port when trying to port
  53 to a new system. There is a port called <EM>gen</EM> (generic) which may be
  54 a good starting point. On the other hand, if another port is close to what
  55 you want, start with it instead.
  56 <P>
  57
  58 The file <CODE>pico/osdep/os-xxx.h</CODE> contains most of the general
  59 platform dependent <EM>#include</EM>'s and <EM>#defines</EM>.
  60 There are a number
  61 of <EM>Pine</EM> configuration settings that are defined in
  62 <CODE>pine/osdep/os-xxx.h</CODE>, as well, such as the
  63 place it looks for certain files, defaults for the printer and folder
  64 names, the maximum screen size, and so on.
  65 Start by looking at the generic <CODE>pico/osdep/os-gen.h</CODE> file
  66 and comparing it to some of the specific <CODE>os-xxx.h</CODE> files there. <P>
  67
  68 The <CODE>osdep/os-xxx.c</CODE> files contain functions that are potentially
  69 platform dependent.  Again, the idea is to gather all the dependencies in
  70 one place.
  71 We use a complicated looking method to produce
  72 the <EM>os-xxx.c</EM> files from a set of included files.  Each included
  73 file usually contains a single implementation method and we've
  74 found that there are
  75 usually only two or three different methods in the
  76 ports we've done so far.  Hopefully, coming up with an <CODE>os-xxx.c</CODE>
  77 for a new port will usually be a matter of including the right set of
  78 these already written functions.  This is done by writing a new
  79 <CODE>os-xxx.ic</CODE> file in the <CODE>osdep</CODE> subdirectories.
  80 Starting with the generic <CODE>os-gen.ic</CODE>, as you did with
  81 the <CODE>os-gen.h</CODE> file above, may be a useful strategy.  <P>
  82
  83 We strongly encourage that no changes be made to the general source when
  84 porting and that all changes be contained in the system
  85 dependent files if possible.  The object is to maintain source code
  86 integrity and assimilate ports to new platforms rapidly.  The more
  87 conventional way to do this is with a large collection of
  88 <EM>#ifdefs</EM>.  The problem with this is that adding a port for a new
  89 platform implies changing the source code for all the other platforms and
  90 thereby risks breaking them.  (We readily admit that there are still too
  91 many <EM>ifdefs</EM> in the code.) <P>
  92
  93 If you do port <EM>Pine</EM> to a new platform we hope that you will send us the
  94 changes required so that we may attempt to include it in a later release.
  95 Thanks!  <P>
  96
  97 <HR>
  98
  99 <H2><A NAME="checklist">Test Checklist</A></H2>
 100
 101 The following is a checklist of some things to check when testing a new
 102 port:  <P>
 103
 104 <DL COMPACT>
 105 <DT>
 106  ___
 107 <DD>
 108 Sending mail, check that headers are correct
 109 <DT>
 110  ___
 111 <DD>
 112 Sending mail with attachments
 113 <DT>
 114  ___
 115 <DD>
 116 Sending mail with SMTP server
 117 <DT>
 118  ___
 119 <DD>
 120 Sending mail without SMTP server
 121 <DT>
 122  ___
 123 <DD>
 124 Sending mail with list of two SMTP servers, first one doesn't answer
 125 <DT>
 126  ___
 127 <DD>
 128 Replying to and forwarding a message
 129 <DT>
 130  ___
 131 <DD>
 132 Postponing messages under composition
 133 <DT>
 134  ___
 135 <DD>
 136 Composer operations
 137 <DT>
 138  ___
 139 <DD>
 140 Alternate editor, <EM>enable-alternate-editor-implicitly</EM>
 141 <DT>
 142  ___
 143 <DD>
 144 Make sure local user names are expanded
 145 <DT>
 146  ___
 147 <DD>
 148 Test spelling checker
 149 <DT>
 150  ___
 151 <DD>
 152 Catching of SIGHUP while message is being composed
 153 <DT>
 154  ___
 155 <DD>
 156 Setting of variables in <CODE>.pinerc</CODE>
 157 <DT>
 158  ___
 159 <DD>
 160 New mail notification.  Should happen with <EM>Pine</EM> idle to check timeouts
 161 <DT>
 162  ___
 163 <DD>
 164 Reading mail (attachments, MIME, MIME with mailcap viewers)
 165 <DT>
 166  ___
 167 <DD>
 168 Deleting, undeleting, expunging, sorting
 169 <DT>
 170  ___
 171 <DD>
 172 Expunge to empty folder
 173 <DT>
 174  ___
 175 <DD>
 176 Make sure that <EM>~</EM> expansion works in config files
 177 <DT>
 178  ___
 179 <DD>
 180 Make sure that $VAR expansion works in config files
 181 <DT>
 182  ___
 183 <DD>
 184 Save message to folder, check error conditions such as permission denied
 185 <DT>
 186  ___
 187 <DD>
 188 Export message with FullHeaderMode on and off
 189 <DT>
 190  ___
 191 <DD>
 192 Checkpointing (see the section on checkpointing)
 193 <DT>
 194  ___
 195 <DD>
 196 Open IMAP and RIMAP folders
 197 <DT>
 198  ___
 199 <DD>
 200 Default-fcc on remote IMAP server
 201 <DT>
 202  ___
 203 <DD>
 204 Fcc-name-rule, fcc in addrbook (while composing)
 205 <DT>
 206  ___
 207 <DD>
 208 Test opening bogus folders:  invalid format, no permission
 209 <DT>
 210  ___
 211 <DD>
 212 Open a USENET news group, list in folder-lister, read news, post news
 213 <DT>
 214  ___
 215 <DD>
 216 Command line arguments
 217 <DT>
 218  ___
 219 <DD>
 220 Change password
 221 <DT>
 222  ___
 223 <DD>
 224 Lock keyboard
 225 <DT>
 226  ___
 227 <DD>
 228 Address book operations (edit, delete, add, lists, whereis, composeto)
 229 <DT>
 230  ___
 231 <DD>
 232 ReadOnly address book
 233 <DT>
 234  ___
 235 <DD>
 236 Look at addrbook, change addrbook-sort-rule in Config, go back to
 237 addrbook screen
 238 <DT>
 239  ___
 240 <DD>
 241 No permission to write in same directory as addrbook, should create
 242 addrbook.lu in a temp directory
 243 <DT>
 244  ___
 245 <DD>
 246 Multiple address books
 247 <DT>
 248  ___
 249 <DD>
 250 Address book loops from one addrbook to another and back
 251 <DT>
 252  ___
 253 <DD>
 254 TakeAddr command with one address, with multiple addresses
 255 <DT>
 256  ___
 257 <DD>
 258 TakeAddr command with ReadOnly address books
 259 <DT>
 260  ___
 261 <DD>
 262 TakeAddr command with one of two address books ReadOnly
 263 <DT>
 264  ___
 265 <DD>
 266 Send mail with empty address book
 267 <DT>
 268  ___
 269 <DD>
 270 Config Screen operation, does pinerc get written?
 271 <DT>
 272  ___
 273 <DD>
 274 Make sure SIGTSTP, ^Z works
 275 <DT>
 276  ___
 277 <DD>
 278 Sent-mail pruning (set back <EM>last-time-prune-questioned</EM> variable)
 279 <DT>
 280  ___
 281 <DD>
 282 Printing using all three printer configurations, various screens
 283 <DT>
 284  ___
 285 <DD>
 286 View help text and news
 287 <DT>
 288  ___
 289 <DD>
 290 Folder list operations (rename, create, delete...)
 291 <DT>
 292  ___
 293 <DD>
 294 Saved-msg-name-rule
 295 <DT>
 296  ___
 297 <DD>
 298 Screen redrawing in various screens (^L)
 299 <DT>
 300  ___
 301 <DD>
 302 Window resizing in various screens
 303 <DT>
 304  ___
 305 <DD>
 306 Error messages for incorrect terminal types (try "foo" and "vt52")
 307 <DT>
 308  ___
 309 <DD>
 310 Reading of <CODE>/usr/local/lib/pine.conf</CODE>
 311 <DT>
 312  ___
 313 <DD>
 314 Fixing variables and features in <CODE>/usr/local/lib/pine.conf.fixed</CODE>
 315 <DT>
 316  ___
 317 <DD>
 318 Flag command (check message status changed in mail folder)
 319 <DT>
 320  ___
 321 <DD>
 322 Initial-keystroke-list
 323 <DT>
 324  ___
 325 <DD>
 326 Aggregate operations (save, delete, export, takeaddr, ...)
 327 <DT>
 328  ___
 329 <DD>
 330 Build xxx from scratch, build clean
 331 </DL>
 332
 333 <!-- pnuts -->
 334
 335 </BODY>
 336 </HTML>