doc/tech-notes/installation.html

   1 <HTML><HEAD><TITLE>Alpine Technical Notes: Building and Installation</TITLE></HEAD><BODY>
   2 <H1>Building and Installation</H1>
   3
   4 <H2><A NAME="compile">Compile-time Options</A></H2>
   5
   6 <EM>Alpine</EM>'s UNIX build environment
   7 is based on Autotools (the GNU Build System).
   8 Once you've unpacked the source distribution find the file
   9 <CODE>configure</CODE> in the top-level directory.
  10 You may look at the many options available by typing
  11 <P>
  12 <CENTER><SAMP>
  13                 ./configure --help
  14 </SAMP></CENTER>
  15
  16 <P>
  17 or you could just try building with the command
  18 <P>
  19 <CENTER><SAMP>
  20                 ./configure
  21 </SAMP></CENTER>
  22
  23 <P>
  24
  25 followed by
  26
  27 <P>
  28 <CENTER><SAMP>
  29                 make
  30 </SAMP></CENTER>
  31
  32 <P>
  33
  34 Note, while the UW IMAP Toolkit (whose c-client
  35 library <EM>Alpine</EM> uses for mailbox access) build is not based on
  36 Autotools, <EM>Alpine</EM>'s configure script should set an
  37 appropriate make target and compilation options for most systems.
  38
  39 <P>
  40
  41 Some of the following can only be set when you build.  Others,
  42 however, can be overridden by command-line flags to <EM>Alpine</EM> or settings in
  43 <EM>Alpine</EM>'s user or system configuration files.
  44 Some of the options which can be set when building:
  45
  46 <H3><A NAME="ldap-compile">Including LDAP Functionality</A></H3>
  47
  48 By default, the configure script will attempt to find the LDAP library
  49 support for you.
  50 If you are having trouble with LDAP take a look at the configure options
  51 <DL COMPACT>
  52 <DT> --with-ldap-dir=DIR
  53 <DD> Specify the root of the LDAP lib/include path.
  54 <DT> --with-ldap-include-dir=DIR
  55 <DD> Specify the LDAP include path.
  56 <DT> --with-ldap-lib-dir=DIR
  57 <DD> Specify the LDAP library path.
  58 <DT> --without-ldap
  59 <DD> Disable LDAP support.
  60 </DL> <P>
  61
  62 <EM>Alpine</EM> uses LDAPv3 protocol.
  63 When using the LDAPv3 protocol, the results are assumed to be in the
  64 UTF-8 character set, which <EM>Alpine</EM> handles well.
  65 If the LDAP server returns non-ascii data which is not encoded as UTF-8
  66 you will probably run into problems.
  67 <P>
  68
  69 <H3><A NAME="krb5-compile">Including Kerberos 5 Functionality</A></H3>
  70
  71 This works analogously to the LDAP build.
  72 By default, the configure script will attempt to find the Kerberos library
  73 support for you.
  74 If you are having trouble with Kerberos take a look at the configure options
  75 <DL COMPACT>
  76 <DT> --with-krb5-dir=DIR
  77 <DD> Specify the root of the Kerberos lib/include path.
  78 <DT> --with-krb5-include-dir=DIR
  79 <DD> Specify the Kerberos include path.
  80 <DT> --with-krb5-lib-dir=DIR
  81 <DD> Specify the Kerberos library path.
  82 <DT> --without-krb5
  83 <DD> Disable Kerberos support.
  84 </DL> <P>
  85
  86 <H3><A NAME="pine-compile">Other Alpine Compile-time Options</A></H3>
  87
  88 <DL COMPACT>
  89
  90 <DT> --disable-nls
  91 <DD> Do not use Native Language Support. NLS refers to the use of GNU
  92 gettext utilities to localize a program, in the sense that English
  93 is translated to some other language.
  94 At the time this was written the low-level support for NSL is included
  95 in <EM>Alpine</EM> but no translations have been done.
  96 If there is no translation available, that means that disabling NLS
  97 will make no difference. If you have trouble building which is due
  98 to gettext or libintl you could try this option, or one of the following.
  99
 100 <DT> --with-libintl-prefix[=DIR]
 101 <DT> --without-libintl-prefix
 102
 103 <DT> --with-ssl-dir=DIR
 104 <DD> Specify the root of the SSL lib/include path (OpenSSL).
 105 <DT> --with-ssl-include-dir=DIR
 106 <DD> Specify the SSL include path.
 107 <DT> --with-ssl-lib-dir=DIR
 108 <DD> Specify the SSL library path.
 109 <DT> --with-ssl-certs-dir=DIR
 110 <DD> Specify the path to the SSL certificates directory.
 111 <DT> --without-ssl
 112 <DD> Disable SSL support.
 113
 114 <DT> --without-pthread
 115 <DD> Do not test for nor build with POSIX thread support, which is used
 116 only for the Busy-Cue in the status line at this time.
 117
 118 <DT> --without-smime
 119 <DD> Disable S/MIME support.
 120
 121 <DT> --disable-debug
 122 <DD> Never create debug files.
 123
 124 <DT> --with-smtp-msa=PATH
 125 <DD> Local Mail Submission Agent (sendmail, by default).
 126 <DT> --with-smtp-msa-flags=FLAGS
 127 <DD> MSA flags for SMTP on stdin/stdout (-bs -odb -oem).
 128
 129 </DL> <P>
 130
 131 There are many more options which you can see using the
 132 <P>
 133 <CENTER><SAMP>
 134                 ./configure --help
 135 </SAMP></CENTER>
 136
 137 <P>
 138 command.
 139 <P>
 140
 141 <H3><A NAME="imapd-compile">IMAPd Compile-time Options</A></H3>
 142
 143 There are no options or settings required for the version of <EM>IMAPd</EM>
 144 distributed with <EM>Alpine</EM>.  If you need to be doing more complex modifications
 145 to IMAP, then you should pick up the IMAP development package and work
 146 with that code.  The developer's version of IMAP is available for
 147 anonymous ftp from <A
 148 HREF="ftp://ftp.cac.washington.edu"><CODE>ftp.cac.washington.edu</CODE></A>
 149 in the directory <CODE>mail</CODE>.  The file is called <A
 150 HREF="ftp://ftp.cac.washington.edu/mail/imap.tar.Z"><CODE>imap.tar.Z</CODE></A>.
 151 Unless it has changed since <EM>Alpine</EM> was released, the directory
 152 <CODE>imap</CODE> in the <EM>Alpine</EM> distribution is the IMAP
 153 development package.
 154 <P>
 155 The c-client library has not been converted to use the
 156 GNU Build System's autotools.
 157 The <EM>Alpine</EM> configure script will try to correctly guess
 158 the arguments needed for the c-client make command and will build
 159 the library, but if you need to change anything you should take a
 160 look at <CODE>imap/docs/BUILD</CODE> for more detailed instructions.
 161 <P>
 162
 163 <HR>
 164
 165 <H2><A NAME="build">Building the Alpine Programs</A></H2>
 166
 167 You may have already compiled <EM>Alpine</EM> and tried it out.  If so, great!  If
 168 not, you should be able to do it without too much trouble by following
 169 these step-by-step instructions: <P>
 170
 171 <OL>
 172
 173 <LI> Make sure you're in the root of the <EM>Alpine</EM> source.  When you type
 174 <CODE>ls</CODE> you should see the following files and directories (or
 175 something close to it):
 176
 177 <PRE>
 178 aclocal.m4    config.sub    imap        Makefile.am    packages  web
 179 alpine        configure     include     Makefile.in    pico
 180 build.bat     configure.ac  install-sh  mapi           pith
 181 build.cmd     contrib       LICENSE     missing        po
 182 config.guess  depcomp       ltmain.sh   mkinstalldirs  README
 183 config.rpath  doc           m4          NOTICE         VERSION
 184 </PRE>
 185 <P>
 186
 187 <LI> Give the command <CODE>./configure</CODE>
 188 Configure should grind away for a few minutes.  <P>
 189
 190 <LI> When configure is complete, give the command <CODE>make</CODE>.
 191 If make stops and asks
 192
 193 <P>
 194 <CENTER><SAMP>
 195   Do you want to build with IPv6 anyway? Type y or n please:
 196 </SAMP></CENTER>
 197
 198 <P>
 199 you should answer with a 'y'.
 200 The compiler should grind away for a few minutes. The <EM>Alpine</EM>
 201 binary will end up in <CODE>.../alpine/alpine</CODE> and the
 202 Pico and Pilot binaries in <CODE>.../pico/pico</CODE>
 203 and <CODE>.../pico/pilot</CODE>. Other binaries you may be interested
 204 in are <CODE>.../alpine/rpdump</CODE> and <CODE>.../alpine/rpload</CODE>
 205 and c-client binaries in the directories <CODE>.../imap/imapd</CODE>,
 206 <CODE>.../imap/ipopd</CODE>, <CODE>.../imap/mailutil</CODE>, and so on.
 207 <P>
 208
 209 <LI> If you need to try again, make sure you're getting a clean start by giving the command
 210 <CODE>make clean</CODE>. <P>
 211
 212 </OL>
 213 <P>
 214
 215 <HR>
 216
 217 <H2><A NAME="install-unix">Installing Alpine and Pico on UNIX Platforms</A></H2>
 218
 219 Installing <EM>Alpine</EM> and <EM>Pico</EM> is simple.  You take the program files
 220 which you have just transferred or built and you move them to the correct
 221 directory on your system.  Most often the binaries go in
 222 <CODE>/usr/local/bin</CODE> though sometimes they are placed in
 223 <CODE>/usr/bin</CODE>.  All the help text is compiled into <EM>Alpine</EM> so there
 224 are no <STRONG>required</STRONG> auxiliary files. Instead of copying the
 225 binaries manually, you may use <CODE>make install</CODE> to install
 226 them. <P>
 227
 228 There are three optional auxiliary files:
 229 <CODE>/usr/local/lib/pine.info</CODE>,
 230 <CODE>/usr/local/lib/pine.conf</CODE>, and
 231 <CODE>/usr/local/lib/pine.conf.fixed</CODE>.  The file
 232 <CODE>pine.info</CODE> contains text on how to get further help on the
 233 local system.  It is part of the help text for the
 234 main menu and should probably refer to the local help desk or the system
 235 administrator.  If this file doesn't exist a generic version which
 236 suggests ``talking to the computer support staff at your site'' is shown.
 237 The file <CODE>pine.conf</CODE> is used to set system-wide default
 238 configurations for <EM>Alpine</EM>.  The file <CODE>pine.conf.fixed</CODE> is also
 239 used to set system-wide default configurations for <EM>Alpine</EM>.
 240 The difference
 241 between these two files is that configuration variables set in the
 242 <CODE>pine.conf.fixed</CODE> file may not normally be over-ridden by a
 243 user.  See the section on <A HREF="config.html"><EM>Alpine</EM> Configuration</A>
 244 later in this document for details about
 245 the <CODE>pine.conf</CODE> and <CODE>pine.conf.fixed</CODE> files.  <P>
 246
 247 <HR>
 248
 249 <H2><A NAME="install-pc">Installing PC-Alpine</A></H2>
 250
 251 <P>
 252 The PC-Alpine distribution comes as a .zip file.  To install, unzip the
 253 files to a directory where you would like the program to reside.  Modern
 254 Windows versions come with the capability of unzipping .zip files.  Failing
 255 that, you can use one of the many .zip file extractors out there.
 256 Following current Windows conventions, a common directory into which the files
 257 could be extracted would be <CODE>C:\Program Files\PC-Alpine\</CODE>.
 258
 259 <P>
 260 Having extracted PC-Alpine's .zip file to the directory of choice, you can
 261 now run that directory's alpine.exe, which is the actual PC-Alpine program.
 262 For convenience, you could place shortcuts to it on the task bar, start
 263 menu, etc.
 264
 265 <P>
 266 Upon first running PC-Alpine, you may be asked where you would like to
 267 access your Configuration file (called the <I>pinerc</I>).  This
 268 is useful in accessing already existing configuration files, and it
 269 does not matter where this file gets created.  If you are connecting
 270 to an IMAP server to access your email, it is also possible to store
 271 this Configuration data on that server, which facilitates accessing
 272 the same configuration from multiple machines (in fact, your configuration
 273 may have already been set up this way for use with other <EM>Alpine</EM> programs).
 274
 275 <P>
 276 After having established the location of the configuration file, it may be
 277 necessary to specify a few configuration settings before reading or sending
 278 mail.  You may be prompted for the following (which may also be edited from
 279 the (S)etup (C)onfig screen from the Main Menu):
 280
 281 <LI><CODE>Folder to open as inbox</CODE> (or <I>inbox-path</I>) - This can
 282 be an inbox residing on an IMAP or POP3 server, or one residing locally.
 283 An example of an INBOX for an IMAP server is:
 284 <CODE>{server.example.com}INBOX</CODE>.
 285
 286 <LI><CODE>User-id</CODE>, <CODE>Personal name</CODE>, and
 287 <CODE>host/domain</CODE>, which are to be used as your email address.
 288
 289 <LI><CODE>SMTP server to forward message</CODE> - You must enter your SMTP
 290 server before you can send any messages.
 291
 292 <P>
 293 At this point, you will be able to read and send email messages.  There are,
 294 however, many more preferences that you can set in the Configuration
 295 screen.
 296 <HR>
 297
 298 <H2><A NAME="install-imapd">Installing IMAPd</A></H2>
 299
 300 When the <EM>Alpine</EM> distribution is built on a UNIX system, the IMAP server
 301 binary, <CODE>imapd</CODE>, is compiled.  Installing <CODE>imapd</CODE>
 302 requires placing the binary in the appropriate directory, usually
 303 <CODE>/usr/etc</CODE>, and adding entries to <CODE>/etc/services</CODE>
 304 and <CODE>/etc/inetd.conf</CODE> or their counterparts.
 305 <P>
 306 Instead of including installation instructions here we'll just include
 307 a pointer to detailed instructions in the c-client distribution.
 308 Please take a look at the file
 309 <CODE>imap/docs/BUILD</CODE> in the source tree.
 310
 311 <HR>
 312
 313 <H2><A NAME="files-unix">Support Files and Environment Variables:  UNIX Alpine</A></H2>
 314
 315 This section lists the various files which <EM>Alpine</EM> uses which are not email
 316 folders.  All of these are the default names of files, they may vary based
 317 on <EM>Alpine</EM>'s configuration.
 318
 319 <DL COMPACT>
 320
 321 <DT> /usr/local/lib/pine.conf
 322
 323 <DD> Pine's global configuration file.
 324
 325 <DT> /usr/local/lib/pine.conf.fixed
 326
 327 <DD> Non-overridable global configuration file.
 328
 329 <DT> /usr/local/lib/pine.info
 330
 331 <DD> Local pointer to system administrator.
 332
 333 <DT> ~/.pinerc
 334
 335 <DD> Personal configuration file for each user.
 336
 337 <DT> ~/.pinercex
 338
 339 <DD> Personal exceptions configuration file for each user.
 340
 341 <DT> ~/.addressbook
 342
 343 <DD> Personal addressbook
 344
 345 <DT> ~/.newsrc
 346
 347 <DD> Personal USENET subscription list.  This is shared with other
 348 newsreading programs.
 349
 350 <DT> ~/.pine-debugX
 351
 352 <DD> The files created for debugging <EM>Alpine</EM> problems.  By default, there are
 353 4 .pine-debug files kept at any time.
 354
 355 <DT> ~/.signature
 356
 357 <DD> A signature file which will be included in all outgoing email
 358 messages.
 359
 360 <DT> ~/.pine-interrupted-mail
 361
 362 <DD> The text of a message which was interrupted by some unexpected error
 363 which <EM>Alpine</EM> detected.
 364
 365 <DT> ~/mail/postponed-msgs
 366
 367 <DD> A folder of messages which the user chose to postpone.
 368
 369 <DT> /etc/mailcap
 370
 371 <DD> System-wide mail capabilities file.  Only used if
 372 <CODE>$MAILCAPS</CODE> not set.
 373
 374 <DT> ~/.mailcap
 375
 376 <DD> Personal mail capabilities file.  Combines with system-wide mailcap.
 377 Only used if <CODE>$MAILCAPS</CODE> not set.
 378
 379 </DL> <P>
 380
 381 The location of the following support files may be controlled by variables
 382 in the personal or global <EM>Alpine</EM> configuration file: signature, addressbook
 383 and its index file, postponed messages, and newsrc.  <P>
 384
 385 Unix <EM>Alpine</EM> uses the following environment variables:
 386
 387 <DL COMPACT>
 388
 389 <DT> TERM
 390
 391 <DD> Tells <EM>Alpine</EM> what kind of terminal is being used.
 392
 393 <DT> DISPLAY
 394
 395 <DD> Determines if <EM>Alpine</EM> will try to display IMAGE attachments.
 396
 397 <DT> TMPDIR, TMP, or TEMP
 398
 399 <DD> Specifies location of temporary storage area, first one set wins
 400
 401 <DT> SHELL
 402
 403 <DD> If not set, default is /bin/sh
 404
 405 <DT> MAILCAPS
 406
 407 <DD> A semicolon delimited list of path names to mailcap files.  <P>
 408
 409 </DL>
 410
 411 <HR>
 412
 413 <H2><A NAME="files-pc">Support Files, Environment Variables, and Registry Settings:  PC-Alpine</A></H2>
 414
 415 This section lists the various files which <EM>PC-Alpine</EM> uses which are not
 416 normal mail folders.  All of these are the default names of files, they
 417 may vary based on <EM>Alpine</EM>'s configuration.  <P>
 418
 419 <DL COMPACT>
 420
 421 <DT> $PINERC or &lt;PineRC registry value&gt; or $HOME\PINE\PINERC or
 422 &lt;PINE.EXE dir&gt;\PINERC
 423
 424 <DD> Path to (required) personal configuration file.
 425
 426 <DT> $PINERCEX or $HOME\PINE\PINERCEX or &lt;PINE.EXE dir&gt;\PINERCEX
 427
 428 <DD> Path to personal exceptions configuration file.
 429
 430 <DT> $PINECONF
 431
 432 <DD> Path of optional global configuration file.
 433
 434 <DT> &lt;PINERC directory&gt;\ADDRBOOK
 435
 436 <DD> Personal addressbook
 437
 438 <DT> &lt;PINERC directory&gt;\PINEDEBG.TXT
 439
 440 <DD> Location of <EM>Alpine</EM> debug file.
 441
 442 <DT> &lt;PINERC directory&gt;\MAILCAP and/or &lt;PINE.EXE dir&gt;\MAILCAP
 443
 444 <DD> These paths are only used if $MAILCAPS not set.
 445
 446 <DT> $HOME\NEWSRC or &lt;PINERC directory&gt;\NEWSRC
 447
 448 <DD> Personal USENET subscription list.  This may be shared with other
 449 newsreading programs.
 450
 451 <DT> $HOME\MAIL\INTRUPTD
 452
 453 <DD> The text of a message which was interrupted by some unexpected error
 454 which <EM>Alpine</EM> detected.
 455
 456 <DT> $HOME\MAIL\POSTPOND
 457
 458 <DD> A folder of messages which the user chose to postpone.
 459
 460 </DL> <P>
 461 Registry Values:
 462 <DL COMPACT>
 463
 464 <DT> HKEY_LOCAL_MACHINE\Software\University of Washington\Alpine\1.0
 465
 466 <DD> <EM>Pinedir</EM>: The directory that contains the <EM>Alpine</EM> executable.
 467
 468 <DD> <EM>PineEXE</EM>: The name of the <EM>Alpine</EM> executable (most commonly
 469 "alpine.exe").
 470
 471 <DT> HKEY_CURRENT_USER\Software\University of Washington\Alpine\1.0
 472
 473 <DD> <EM>PineRC</EM>: The path that points to the default pinerc to use.
 474
 475 <DT> HKEY_LOCAL_MACHINE\Software\Clients\Mail\Alpine
 476
 477 <DD> <EM>DLLPath</EM>: The path that points to <EM>Alpine</EM>'s pmapi32.dll.
 478
 479 <DT> HKLM\Software\Clients\Mail\Alpine\shell\open\command
 480
 481 <DD> <EM>(Default)</EM>: When set as the default mailer, this is the
 482 command that is run by external programs.
 483
 484 <DT> HKLM\Software\Clients\Mail\Alpine\Protocols\Mailto\DefaultIcon
 485
 486 <DD> <EM>(Default)</EM>: This points to the icon to display in relation to
 487 <EM>Alpine</EM>'s mailto URL rendering.
 488
 489 <DT> HKLM\Software\Clients\Mail\Alpine\Protocols\Mailto\shell\open\command
 490
 491 <DD> <EM>(Default)</EM>: This value is the command that gets run by external
 492 programs when a mailto URL is run with <EM>PC-Alpine</EM> set as the
 493 default mailer.
 494
 495 <DT> HKLM\Software\Clients\News\Alpine\shell\open\command
 496
 497 <DD> <EM>(Default)</EM>: When set as the default newsreader, this is the
 498           command that is run by external programs.
 499
 500 <DT> HKLM\Software\Clients\News\Alpine\Protocols\news\DefaultIcon
 501
 502 <DD> <EM>(Default)</EM>: This points to the icon to display in relation to
 503           <EM>Alpine</EM>'s news URL rendering.
 504
 505 <DT> HKLM\Software\Clients\News\Alpine\Protocols\news\shell\open\command
 506
 507 <DD> <EM>(Default)</EM>: This value is the command that gets run by external
 508 programs when a news URL is run with <EM>Alpine</EM> set as the
 509 default newsreader.
 510
 511 <DT> HKLM\Software\Clients\News\Alpine\Protocols\nntp\DefaultIcon
 512
 513 <DD> <EM>(Default)</EM>: This points to the icon to display in relation to
 514 <EM>Alpine</EM>'s nntp URL rendering.
 515
 516 <DT> HKLM\Software\Clients\News\Alpine\Protocols\nntp\shell\open\command
 517
 518 <DD> <EM>(Default)</EM>: This value is the command that gets run by external
 519 programs when a nntp URL is run with <EM>Alpine</EM> set as the
 520 default newsreader.
 521
 522 </DL> <P>
 523 <EM>Alpine</EM>'s personal configuration file
 524 may be in the same directory as the executable, or if that is inconvenient
 525 because the executable is on a shared or read-only drive, then it can be
 526 in a file named by the <CODE>$PINERC</CODE> environment variable, or in
 527 <CODE>$HOME\ALPINE\PINERC</CODE>, where if not set, <CODE>$HOME</CODE>
 528 defaults to the root of the current working drive.  <P>
 529
 530 Most of the other support files key off of the location of the
 531 <CODE>PINERC</CODE> file.  However, in the case of the NEWSRC file, the
 532 path <CODE>$HOME\NEWSRC</CODE> is checked first.  Also, the postponed
 533 messages and interrupted message folders are placed in the default folder
 534 collection, normally in the directory <CODE>$HOME\MAIL</CODE>.  <P>
 535
 536 The location of the following support files may be controlled by variables
 537 in the personal or global <EM>Alpine</EM> configuration file: signature, addressbook
 538 (and its index file), postponed messages, and newsrc.  <P>
 539
 540 <EM>PC-Alpine</EM> uses the following environment variables:
 541
 542 <DL COMPACT>
 543
 544 <DT> PINERC
 545
 546 <DD> Overrides default path to pinerc file.
 547
 548 <DT> PINERCEX
 549
 550 <DD> Overrides default path to personal exceptions configuration file.
 551
 552 <DT> PINECONF
 553
 554 <DD> Optional path to global <EM>Alpine</EM> config file.
 555
 556 <DT> HOME
 557
 558 <DD> If not set, <EM>Alpine</EM> uses the root of the current drive, e.g. C:
 559
 560 <DT> TMPDIR, TMP, or TEMP
 561
 562 <DD> Specifies location of temporary storage area, first one set wins
 563
 564 <DT> COMSPEC
 565
 566 <DD> Specifies shell for external commands.
 567
 568 <DT> MAILCAPS
 569
 570 <DD> A semicolon delimited list of path names to mailcap files.
 571
 572 </DL> <P>
 573
 574 <!-- pnuts -->
 575
 576 </BODY>
 577 </HTML>