pine.tar.z README Last changed: 18 January 2005 ----------------------------------------------------------------------- Pine/Pico/Pilot/Imapd Distribution ----------------------------------------------------------------------- Pine and Pico are registered trademarks of the University of Washington. No commercial use of these trademarks may be made without prior written permission of the University of Washington. Pine, Pico, and Pilot software and its included text are Copyright 1989-2005 by the University of Washington. The full text of our legal notices is contained in the file called CPYRIGHT, included with this distribution. For the latest info about Pine, see http://www.washington.edu/pine ----------------------------------------------------------------------- DISTRIBUTION CONTENTS ----------------------------------------------------------------------- This Pine distribution includes: bin - Compiled binaries are found here build - Shell script to compile Pine and Pico contrib - Contributed ports and additions doc - Documentation directory. The main documentation is tech-notes.txt imap - Source tree containing C-Client IMAP implementation makefile - In case make is tried to build Pine and Pico packages - Scripts for building packages for various Linux distributions pico - The Pico and Pilot source directory pine - The Pine source directory Most of the documentation is in doc/tech-notes.txt. It is not user level documentation, but there are things in it some users might find useful. There are also instructions for building and porting Pine. The directory doc/tech-notes contains source for doc/tech-notes.txt in HTML format which can be viewed via a Web browser by opening doc/tech-notes/index.html. ----------------------------------------------------------------------- PRELIMINARIES ----------------------------------------------------------------------- If you are reading this, you have presumably succeeded in extracting the distribution from the compressed tar archive file, via the following command, or equivalent: tar zxf pine.tar.z Some of the instructions that follow assume that your current workding directory is the pineX.XX directory created by the un-tar process above. ----------------------------------------------------------------------- BUILD SYNTAX ----------------------------------------------------------------------- A shell interpreter script called "build" is used to compile Pine and the other programs in the distribution. The build script is also responsible for building operating system specific symbolic links into the imap/c-client source tree. Usage: build may be one of the ports listed in doc/pine-ports or clean Clean up object files and such. Also, a good way to rebuild Pine/Pico from scratch. "Build" by itself with no arguments is the same as typing in the previous build command with the arguments used then. To build Pine and Pico the command "build xxx" should work where xxx is one of the targets. For example "build gul" to build Pine for Ultrix. There are three pieces of Pine which are optionally included. When you build Pine, the three lines Including SSL functionality Including LDAP functionality Including Kerberos5 functionality should be printed early in the build process if the corresponding piece is being included. (See below for more about these options.) ----------------------------------------------------------------------- INCLUDING LDAP ----------------------------------------------------------------------- If you are attempting to compile in the LDAP functionality in pine, you should get the OpenLDAP source, set up the libldap and liblber libraries, and the include files. A usually easy way to do that is ./configure --disable-slapd --disable-slurpd --without-kerberos --without-threads make depend make The configure line may not be right for you. Add a symlink called ldap to this directory (the directory with this build file in it) which points to the ldap installation. That is, the directory ldap points to should contain the directories include and libraries. For example, the command to create the symlink might be something like ln -s /path/to/openldap/source/openldap-2.0.7 ldap Alternatively, you may use the older Univ. of Michigan ldap-3.3 source and put it in a directory called "ldap" in this top-level pine directory. Or you could put a symlink pointing from here to the actual location. The include files should show up in ldap/include and the libraries in ldap/libraries. Alternatively, you can try using the Netscape Directory SDK 1.0 (or probably 3.0 when it is ready) by putting the include files in ldap/include and libldap.a in ldap/libraries. This build script will attempt to notice that you are not using ldap-3.3 and leave out liblber.a, which is required when using ldap-3.3. Alternatively, OpenLDAP may already be included in your system libraries. Solaris 8 is apparently set up this way. The script contrib/ldap-setup, which is called by the build script, tries to detect this automatically. It causes ldap-setup to exit with value 3 and the build script notices that and sets the appropriate arguments. ----------------------------------------------------------------------- INCLUDING KERBEROS ----------------------------------------------------------------------- If you are attempting to compile in Kerberos5 functionality, put a symlink called krb5 pointing from the directory containg the "build" script, to the location of the Kerberos includes and libraries. The expected files should be in krb5/include and krb5/lib. On many systems, this would be accomplished with ln -s /usr/local krb5 However, the location (as well as the tools available to find the needed files) will vary from one system to another. For example, on RedHat Linux 7.2, you could try the command locate krb5.h and discover that the Kerberos libraries are in the directory /usr/kerberos (e.g. /usr/kerberos/include/krb5.h ) Therefore the needed command for this system would be: ln -s /usr/kerberos krb5 ----------------------------------------------------------------------- INCLUDING SSL ----------------------------------------------------------------------- An attempt is made to include SSL support automatically. If OpenSSL is installed in /usr/local/ssl then it is used. It doesn't make sense to use the same "linking" mechanism as is used for LDAP and Kerberos, since the SSLDIR is used at run-time, not just compile-time. You can change the directory with the build argument: SSLDIR=/some/directory In other words, the build command would be: ./build SSLDIR=/some/directory target where target is one of the 3-letter target names found in doc/pine-ports. The assumption is that the certs directory is in SSLDIR/certs, the include directory is SSLDIR/include, and the library directory is SSLDIR/lib. Note that for some ports different assumptions are made. In the instances different from the default, the difference will be noted in the description of that port in doc/pine-ports. Also, you can change the assumptions for any of the directories by adding options to the command line such as the following: SSLCERTS=certs_directory SSLINCLUDE=include_directory and SSLLIB=ssl_library_directory You can override the automatic inclusion of SSL by including the argument NOSSL. For example: ./build NOSSL target The possible values for SSLTYPE are: none no SSL support, the default unix SSL support using OpenSSL nopwd SSL support using OpenSSL, and plaintext authentication permitted only in SSL or TLS sessions. sco link SSL before other libraries for SCO sco.nopwd same as nopwd Usually SSLTYPE will get set automatically by the script. Note: The "nopwd" SSLTYPE is similar to "unix" except that it compiles the IMAP server (imapd) so that plaintext authentication is only permitted if the session is encrypted via SSL or TLS. The short description here is not complete. The definitive text is part of the c-client distribution (which is included here). Take a look at the file imap/docs/SSLBUILD. In particular, look at STEP 3 to learn about setting up certificates. ----------------------------------------------------------------------- EXTRAS ----------------------------------------------------------------------- There are some other arguments which you may find useful. EXTRACFLAGS= EXTRALDFLAGS= As an example, it should be ok to move string constants into a read-only area because we don't think there are any instances where Pine modifies a string constant. So you could pass a flag to your compiler telling it to do this. With the AIX a41 port, you could pass the extra build argument EXTRACFLAGS=-qro to accomplish this. Another place where you might need to use EXTRACFLAGS is if the code that makes the NewMail-FIFO-Path work is causing problems. There is a define called LEAVEOUTFIFO which will do this. If the fifo code is causing trouble (for example, you don't have a mkfifo() function on your system) then adding EXTRACFLAGS=-DLEAVEOUFIFO to the build command should fix it. DEBUG applies only to pico and pine sub-makes. It typically defaults to DEBUG="-g -DDEBUG" which causes symbol table information and debugging code to be compiled into pine. That is what we use in our production versions of pine, because the symbol table information makes it easier to analyze core dumps, and the debugging code makes it possible to have Pine produce debug files. But if you wanted an optimized version that produced no debug files you could use the argument DEBUG=-O Setting DEBUG to DEBUG="-g -DDEBUG -DDEBUGJOURNAL" adds a DebugLevel subcommand to the Journal command. This allows you to look at all of the debugging output from within Pine without having to run Pine at a high debugging level. In other words, you have a chance to see the level 9 (or whatever) debugging without running pine -d9. This will only work on ports that have a debugjournal routine defined. This is normally in pine/osdep/debuging.tim. If your port uses pine/osdep/debuging instead of debuging.tim then DEBUGJOURNAL will fail to compile. The argument EXTRASPECIALS= can be used to pass arguments to the c-client make which aren't provided for in this build script. For example, if you want to change the FRIZZLE parameter (a made-up argument name which the c-client make uses) you might be tempted to type something like build FRIZZLE=cruft target 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. build EXTRASPECIALS="FRIZZLE=cruft" target 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. ----------------------------------------------------------------------- RESULTING EXECUTABLES ----------------------------------------------------------------------- The executables built by the build script are: pine The Pine mailer. Once compiled this should work just fine on your system with no other files than this binary, and no modifications to your system. Optionally you may create two configuration files, /usr/local/lib/pine.conf and /usr/local/lib/pine.info. See the documentation for details. pico The standalone editor similar to the Pine message composer. This is a very simple straight forward text editor. pilot The standalone file system navigator. imapd The IMAP daemon. If you want to run Pine in client/server mode, this is the daemon to run on the server. Installing this requires system privileges and modifications to /etc/services. See doc/tech-notes for more details. mtest The test IMAP client, an absolutely minimal mail client, useful for debugging. rpload Utility for uploading a local pinerc or address book to an IMAP server. rpdump Utility for downloading a pinerc or address book to the local machine. mailutil Utility for performing various operations on mailboxes, be they local or remote. In general you should be able to just copy the Pine and Pico binaries to the place you keep your other local binaries. /usr/local/bin is a likely place. ----------------------------------------------------------------------- END OF pine.tar.z README -----------------------------------------------------------------------