Compilation and installation notes for tin - 94-12-22
-----------------------------------------------------

Note: The section 'News machine names' is now at the beginning as it 
      seemed to be the most sought after section.

This following Makefile & ./include/tin.h defines are documented in detail:
---------------------------------------------------------------------------
  DEBUG                    DEFAULT_ISO2ASC          DONT_HAVE_GETCWD
  DONT_HAVE_MKDIR          DONT_HAVE_NNTP_EXTS      DONT_HAVE_STRTOL
  DONT_LOG_USER            DONT_REREAD_ACTIVE_FILE  HAVE_FASCIST_NEWSADMIN
  HAVE_ISPELL              HAVE_LONG_FILENAMES      HAVE_MAIL_HANDLING
  HAVE_MMDF_MAILER         HAVE_POLL                HAVE_POSIX_JC
  HAVE_SELECT              HAVE_SETREUID            HAVE_STRFTIME
  HAVE_TIN_NNTP_EXTS       INDEX_DAEMON             INEWS_MAIL_DOMAIN
  INEWS_MAIL_GATEWAY       INEWSDIR                 LIBDIR
  NETLIBS                  NNTP_ABLE                NNTP_DEFAULT_SERVER
  NNTP_INEWS               NNTP_ONLY                NNTP_SERVER_FILE
  NOVROOTDIR               NO_PIPING                NO_POSTING
  NO_REGEX                 NO_SHELL_ESCAPE          SMALL_MEMORY_MACHINE
  SPOOLDIR                 USE_INN_NNTPLIB          USE_INVERSE_HACK


News machine names
------------------

INEWS_MAIL_GATEWAY
Defines the name of your news gateway machine. Useful if you don't want 
your internal network visible to the outside world, or if your inews script
or NNTP server rewrites your address for you.
If the first letter of the string is a '/' the gateway name will be read from 
the specified file.
If the first letter of the string is a '$' the gateway name will be read from 
the specified environment variable. The env. variable contents may be a path.
If the first letter of the string is a '%' the gateway name will be directly
appended to the username.  
The '%' hack will *only* be used if INEWS_MAIL_DOMAIN is not defined.
Note: don't define if INEWS_MAIL_DOMAIN is defined.

Example 1: If you are on machine 'tragic' at network domain 'confusion.com', 
Tin will assume your From: line should read "user@tragic.confusion.com".  If
your inews script instead rewrites your address as "user@confusion.com", you 
will be unable to cancel your own postings.  To make your posts and cancels 
work properly, define -DINEWS_MAIL_GATEWAY=\"confusion.com\"
Example 2: I use this define to make all my net postings appear from our news
gateway machine 'anl433' even though I post from my own workstation 'sony01'
i.e. -DINEWS_MAIL_GATEWAY=\"anl433\"
Example 3: -DINEWS_MAIL_GATEWAY=\"%anl433.uucp@Germany.EU.net\" (using the 
'%' hack) will create the net address "Iain.Lea%anl433.uucp@Germany.EU.net"

INEWS_MAIL_DOMAIN
Defines the name of your network domain. 
If the first letter of the string is '/' the domain name will be read from 
the specified file.
If the first letter of the string is a '$' the domain name will be read from 
the specified environment variable. The env. variable contents may be a path.
Note: don't define if INEWS_MAIL_GATEWAY is defined.

Example 1: I use this define to add our uucp domain '.uucp' to our news 
gateways machine address 'anl433.uucp'. Note the leading dot '.' which
is *always* needed before the domain name. 
i.e. -DINEWS_MAIL_DOMAIN=\".uucp\"


General Notes on Building Tin
-----------------------------

Tin has been compiled on a wide range of Un*x machines with cc and gcc.
A list of these machines can be found at the end of this file.

This file is long (so was the yellow brick road) but please read it all
as it could save you problems later and we don't want an unhappy ending
do we? :-)  

Tin can be compiled to read news in any of the following ways:

  o  locally from your machines news spool dir (default /usr/spool/news).

  o  locally and remotely (rtin or tin -r option) (-DNNTP_ABLE).

  o  remotely from another machine via NNTP but creating tin index files
     on local machine for each user in $HOME/.tin/.index (-DNNTP_ONLY).

  o  remotely from another machine via NNTP and also retrieving tin index
     files from remote machine via NNTP (-DNNTP_ONLY). This
     option requires that my nntp patch be applied to your NNTP 1.5.11t5 
     server nntpd. On the NNTP server the index daemon of tin
     'tind' needs to be run from cron to update the index files at regular 
     intervals (not required if INN/Cnews generate NOV index files).

  o  remotely from another machine via NNTP and retrieving NOV style index
     files from remote machine via the NNTP XOVER extension (-DNNTP_ONLY). 

Many machines require the name of the news gateway machine or the news
domain to be set via the -DINEWS_MAIL_GATEWAY or the -DINEWS_MAIL_DOMAIN 
defines.  This is true of both NNTP and local news systems.

The -DNNTP_ABLE or -DNNTP_ONLY define must be added to COPTS in 
Makefile and the correct libraries need to be linked to produce
an NNTP aware tin.


Building Tin (Normal & Daemon versions) 
---------------------------------------

Normal version

1)  Type 'make' and a few system types will be displayed.
2)  Edit Makefile if you want to add/change -D<defines>.  As noted 
    above, some changes may be required for your system.
3)  Type 'make <system type>' to compile for your system.
4)  Type 'make install' / 'make install_setuid' to install.

Index daemon version

Note1: If you want to retrieve tin index files from your NNTP server,
      or if you don't run NNTP but want to install tin setuid and have
      a central index rather than each user keeping his/her own index
      and want tind to automatically keep the index up-to-date, then
      you will need the tind index file daemon; create it using the
      following steps:

  1)  Build and install the 'Normal version' of tin as specified by the
      above 4 points.
  2)  Run "make clean" to delete the *.o files from the normal version.
  3)  The tind index daemon needs to be installed on your NNTP server,
      or on your standalone news server if you're not using NNTP.
      More info. concerning my NNTP patches & the tin daemon can be
      found in the INSTALL.NNTP file.  If you don't use NNTP, just
      install tind on the machine that has the news spool directory.
  4)  Apply my NNTP patches to your nntpd server or this will not work 
      with NNTP!!!. (If you want tind locally read Note3).
  5)  Edit the Makefile and add -DINDEX_DAEMON to your COPTS entry and
      remove any -DNNTP_* defines. Also remove -lcurses, -ltermcap, and
      any other screen-handling libraries used, as tind does not need to
      be linked with curses and it will save a good 30-50K on the size of
      tind.
  6)  Type 'make <system type>' to compile tind daemon for your NNTP server
      or standalone news server.  This creates tind as the file "tin".
  7)  Rename the file "tin" to "tind" (i.e. mv tin tind).
  8)  Type 'make install_daemon' to install tind daemon on your NNTP server
      or standalone news server.
  9)  Add the following line to your system cron to run tind every 30 mins:
        00,30 * * * * su news -c '/usr/lib/news/tind'

  Note2: tind must be run as user 'news' and the normal tin must have
         the correct permissions to read the central index files!
  Note3: tind can also be used to update a copy of all index files

Testing Tin
-----------

Of course you _were_ going to test it before installing it for anyone else
to use, weren't you?  This is just a little reminder and some suggestions 
on what to test first, and where to look first if it's broken.

Things to test:

1) Check that you can read news from several local and world-wide groups.
   If this fails, check that the NNTP define directives are correctly set, 
   and for local news systems, that the News directory structure define 
   directives are correctly set.  For NNTP versions, check that the server is
   actually running and can be connected to from your machine.  This should 
   help you find and fix some of the most common problems.

   If reading news works fine, then:

2) Check that you can post a test message to a local distribution group, 
   preferably a test-only group.  (Remember, the world does not care to 
   know whether you are testing Tin.)  If it fails, check that the 
   INEWSDIR define is correctly set, that NNTP_INEWS is correctly set, and 
   that the News machine name define directives are correctly set.  If 
   possible, check whether you can post via some other mechanism, such as 
   Pnews.  This should help you isolate and fix the most common problems.

   If posting news works fine, then:

3) Check that you can cancel one of your test postings.  If not, it is 
   almost certain that your News machine defines need to be set correctly, 
   because Tin thinks your From: line is different from what has actually
   been posted.  See the section on News machine names below.

Further testing is desirable, but left to your individual conscience and
ingenuity.

Compiler flags (-D<name> define directives)
-------------------------------------------

News directory structure
------------------------

LIBDIR
Define if news software is not in /usr/lib/news.

SPOOLDIR
Define if news articles are not in /usr/spool/news.

NOVROOTDIR
Define if news overview (NOV) files are not stored in SPOOLDIR.

INEWSDIR
Define if bnews/cnews program 'inews' is not in LIBDIR.

NNTP - Reading & posting news
----------------------------- 

NNTP_ABLE
Define if you wish to read news locally and remotely via an NNTP server.

NNTP_ONLY
Define if you [want to | can] ONLY read news remotely via an NNTP server.

NNTP_INEWS
Define if you want to use my builtin NNTP POST routine so that you no
longer have to rely on the mini-inews from NNTP to be installed on each
client machine. Also check that INEWS_MAIL_GATEWAY & INEWS_MAIL_DOMAIN 
are correctly set to produce a correct From: headers for your site.
If defined then the ~/.tin/tinrc variable "use_builtin_inews" default will
be set to OFF rather than ON. The tinrc file is created automatically for
each user the first time they use tin.

NNTP_SERVER_FILE
Only define if your nntpserver file is other than /etc/nntpserver.

NNTP_DEFAULT_SERVER
Defines the name of the default nntp server that tin should connect to.
Overrides the value of NNTP_SERVER_FILE. Can be overridden by setting the
environment variable NNTPSERVER.

NETLIBS
Contains the networking libraries needed to link with nntplib.o file.

HAVE_TIN_NNTP_EXTS
Define if you have a NNTP server that supports my XMOTD & XUSER patches.


Daemon options
--------------

INDEX_DAEMON
Define to make an index file updating daemon version of tin. Note that
no -lcurses or screen libraries need to be linked with tin when this
#define is specified. If defined this will automatically undefine all
NNTP_* defines as the daemon has to be installed on the NNTP server.


Miscellaneous options
---------------------

DEBUG
Define if you want tin to log debug info. to files in /tmp. Activated
by tin -Dn where n is 1 for NNTP only debug logging and n is 2 for 
logging all debug info. Debug files written to /tmp are ARTS, ACTIVE,
BASE and NNTP.

DONT_HAVE_MKDIR
Define if your machine does not have the mkdir() system call.

DONT_HAVE_STRTOL
Define if your machine does not have the strtol() system call.

DONT_HAVE_GETCWD
Define if you don't have the getcwd() system call. getwd() will be used.

DONT_LOG_USER
Log username & info to /tmp/.tin_log for usage statistics. If reading via
NNTP the NNTP XUSER extended command will log user info to NNTP server.
If -DNNTP_XUSER is defined it will define LOG_USER automatically.

DONT_REREAD_ACTIVE_FILE
Define if you do not want the active file to be reread periodically.
The reread period can be set in seconds by setting the tinrc variable
'reread_active_file_secs='

HAVE_FASCIST_NEWSADMIN
Define if you want users articles to be posted to groups that your site 
receives.  This will change the warning that a group that the user is 
posting to was not found in the sites active file to an error in the 
article checking routine therefore causing the user to remove the group
from his/her posting or to abort the posting of the article.

HAVE_ISPELL
Define if you have ispell (interactive spellchecker) installed and want the
option of checking your articles, mails before posting/mailing them.

HAVE_LONG_FILENAMES
Define if your machines filesystem supports filenames longer than 14
chars (default for BSD type systems).

HAVE_MAIL_HANDLING
Define if you want to use the MH style mail handling & reading code in mail.c
It should be noted that mail handling is not well tested and not yet fully
implemented. You can expect errors if you use this define so let me know the
problems by sending me a bug report ('R' bug command from within tin).

HAVE_MMDF_MAILER
Define if your machine uses a MMDF type mailer instead of sendmail.
It is defined as default on SCO Unix machines. It can be dynamically 
changed by setting the tinrc variable save_to_mmdf_mailbox to ON. 

HAVE_POLL
Define if you have the poll() system call that is required to abort 
the indexing of a group in the function input_pending(). Don't define
if HAVE_SELECT is already defined.

HAVE_SELECT
Define if you have the select() system call that is required to abort 
the indexing of a group in the function input_pending(). Don't define
if HAVE_POLL is already defined.

HAVE_POSIX_JC
Define if your machine uses Posix style sigaction() signal handling.

HAVE_SETREUID
Define if problems occur when running tin as setuid news. Only define if
your system supports the setreuid() system call.

HAVE_STRFTIME
Define if date shown at article viewer level is incorrect (i.e. 1970...).
Only define if your system supports the strftime() system call.

NO_PIPING
Do not allow piping of articles to shell commands.

NO_POSTING
Do not allow posting/followup of articles.

NO_REGEX
Define if you do not want to use regular expression pattern matching.

NO_SHELL_ESCAPE
Do not allow shell escapes.

SMALL_MEMORY_MACHINE
Define if you are running a machine with little memory (<4MB). Tin will
run slightly slower but be more efficient in how memory is allocated and
reclaimed.
 
USE_INN_NNTPLIB
Define if you want to use the INN library functions GetConfigValue()
& GetFQDN().  The INN_NNTPLIB variable in the Makefile must contain
the correct path to INN library.

USE_INVERSE_HACK
Define if you want inverse video and highlighted bar disabled. Can be 
toggled in tin by the 'I' command and highlight bar by 'M' command.

DEFAULT_ISO2ASC
Define if you want tin todo ISO-8859-1 Charset to Ascii conversations
by default for all groups. You must specify a value of "0-6" to get tin
to use one of the 7 conversion tables for different languages.
i.e., Adding -DUSE_ISO2ASC=\"2\" to the COPTS line in the Makefile would 
be useful in the german language newsgroups. For more detailed info
read the file ./doc/iso2asc.txt. Default value for USE_ISO2ASC is "-1".


Compiled & installed on the following machines
----------------------------------------------

1) * i386 & Linux 0.99p12 (main development machine)
2) * i386 & BSDI 1.0/Xenix 2.3.2/SCO SVR3.2/ISC SVR3.2/ATT SVR4.0
3)   Sony News & NewsOS 4.1
4)   SNI MX300/MX500 & Sinix 5.24/5.4
5) * Sun 3/4/IPC/SS1/SS2/SS10 & SunOS 4.0.3/4.1.1/4.1.2/4.1.3 
6)   Dec 5000/Vax & Ultrix 4.1/4.2
7)   Vax 11/785 & BSD 4.3
8)   DG Aviion 300 & DG-UX 4.30
9)   Apollo DN5500 & DomainOS 10.3
10)  ICL DRS6000 & SVR4.0 
11)  Apricot VX/FT & SCO 3.2.2
12)  DIAB DS90 & D-NIX 5.3
13)  Amdahl 5890 & UTS 5.2.6b
14)  HP 720/845 & HP-UX 7.0/8.0
15)  IBM RS/6000 & AIX 3.1.5
16)  NCR Tower & SysV
17)  Atari STe & Minix 1.5.10.3b
18)  Powerbook 140 & MacMinix
19)  386 PC & Minix 386
20)  Sequent S81 & PTX 1.3 / Dynix
21)  Convex C220 & Convex Un*x
22)  Harris HCX & CX/UX
23)  SGI 4D35/Challenge & IRIX 4.0.1/5
24)  Pyramid 9810 & OSx96N
25)  Alliant FX/2800 & Concentrix 2.2
26)  Stratus i860 & FTX 2.0
27)  Apple A/UX 3.0 & gcc 2.2 (?)
28)  Motorola Delta 3200 & SysVR3V6
29)  Gould Powernode 9050 & utx/32
30)  Acorn R260 & RISCiX 1.2
31)  DDE Supermax & ATT SysVr3

* = compiled, installed and used by author 
