Compilation and installation notes for tin - 1998-12-27 (still incomplete!)
-------------------------------------------------------

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

This following configure options and defines are documented in detail:
----------------------------------------------------------------------
  --enable-8bit-keys	     --enable-posting      --with-metamail
  --enable-color	     --enable-piping       --with-ncurses
  --enable-curses	     --enable-shell-escape --with-nntp-default-server
  --enable-debug	     --enable-xhdr-xref    --with-nov-dir
  --enable-etiquette	     --with-defaults-dir   --with-pgp
  --enable-fascist-newsadmin --with-domain-name    --with-spooldir
  --enable-inverse-video     --with-inews-dir      FORGERY
  --enable-locale	     --with-inn-nntplib    HAVE_LIBUU
  --enable-mh-mail-handling  --with-iso-to-ascii   INDEX_DAEMON
  --enable-mmdf-mailer       --with-ispell         NNTP_INEWS
  --enable-nntp		     --with-libdir         NNTP_SERVER_FILE
  --enable-nntp-only	     --with-local-charset  (SMALL_MEMORY_MACHINE)
  --enable-broken-listgroup-fix                    KILL_READ
  --enable-printing

Not yet documented configure options and defines:
-------------------------------------------------

TIN related:
  --enable-append-pid              --with-editor
  --enable-break-long-lines        --with-mailbox
  --enable-echo                    --with-mailer
  --enable-mime-strict-charset     --with-mime-default-charset
  --enable-pgp                     --with-nov-fname
  --enable-prototypes              --with-socks
  --enable-warnings                --with-socks5
  --with-dbmalloc                  --with-sum
  --with-dmalloc                   --with-trace

  DEBUG                            MATCH_TAR_PATTERN
  DEBUG_NEWSRC                     NEW_HASH_METHOD
  DEBUG_NEWSRC_FIXME               OPTIMIZE_JUST_STAR
  DEBUG_REFS (see doc/DEBUG_REFS)  PROFILE
  ENFORCE_RFC1034                  REQUIRE_BRACKET_IN_DOMAIN_LITERAL
  JUST_TESTING                     TINC_DNS
  KILL_READ


System related:
  --bindir              --libexecdir          --program-transform-name
  --datadir             --localstatedir       --sbindir
  --exec-prefix         --mandir              --sharedstatedir
  --includedir          --oldincludedir       --srcdir
  --infodir             --prefix              --sysconfdir
  --install-prefix      --program-prefix
  --libdir              --program-suffix


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

--with-domain-name
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.

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, configure using --with-domain-name="confusion.com".

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

Tin has been compiled on a wide range of Un*x machines with cc and gcc.
It has even been ported to other systems like the Amiga.
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 /var/spool/news).

  o  locally and remotely via NNTP (rtin or tin -r option) (--enable-nntp).

  o  remotely via NNTP (--enable-nntp-only).

If the remote server supports NOV overview indexing, then tin will retrieve
overview data on the fly using the NNTP XOVER extension.
Otherwise tin will create its own NOV style index files on the local machine
for each user in $HOME/.tin/.index

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


Building the Normal version:
----------------------------

1)  Type './configure --help' to see which options are needed for your
    local setup. These options are described below, too.

2)  Change conf-tin for your needs or run ./configure with all needed
    options.

3)  type 'make build' to build tin in the src/ directory.
    Alternatively goto the src subdirectory and type 'make'

4)  Type 'make install' to install.

Building the Index daemon version:
----------------------------------

!!! This feature is deprecated and unsupported. So is this part of the
!!! the file. The patches and some of the files mentioned below are not
!!! part of the standard distribution of TIN. Future releases may
!!! (will!) obsolete this feature.

Use it only if your server doesn't support NOV overview files.

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 stand-alone 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.
       [These mentioned files are not included in the distribution of
        TIN.]

   4)  Apply my NNTP patches to your nntpd server or this will not work
       with NNTP!!!. (If you want tind locally read Note3). [Again:
       These patches are not included any longer.]

   5)  Edit the Makefile in the src/ tree and add remove the # before
       the -DINDEX_DAEMON in the declaration of the DAEMON variable and
       remove any -DNNTP_* defines. Also remove -lcurses, -ltermcap,
       and any other screen-handling libraries used in the LIBS
       variable, as tind does not need to be linked with curses and it
       will save a good 30-50K on the size of tind.
       [This doesn't work anymore - just don't remove the
        screen-handling libraries and it builds fine]

   6)  Type 'make <system type>' to compile tind daemon for your NNTP server
       or stand-alone news server.  This creates tind as the file "tin".
       [Actually, this won't work. Just try to run 'make' in the src/
        tree instead.]

   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 stand-alone 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 above and below.

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



Detailed list of configure options (beginning with '--') and compiler flags
(-D<name> directives)

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

--with-libdir=PATH
Define if news software is not in /usr/lib/news.
(only needed if not running --enable-nntp-only)

--with-spooldir=PATH
Define if news articles are not in /var/spool/news.
(only needed if not running --enable-nntp-only)

--with-nov-dir=PATH
Define if news overview (NOV) files are not stored in SPOOLDIR.
(only needed if not running --enable-nntp-only)

--with-inews-dir=PATH
Define if 'inews' program is not in NEWSLIBDIR.

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

--enable-nntp (default: on)
Enable if you wish to read news locally and remotely via an NNTP
server. Disable if you only want to read from local spool. Note: If you
disable this feature, you won't be able to connect to any NNTP server.

--enable-nntp-only (default: off)
Enable if you [want to | can] ONLY read news remotely via an NNTP server.

--with-nntp-default-server (default: news.$DOMAIN_NAME)
Defines the name of the default NNTP server that tin should connect to.
Can be overridden by setting the environment variable NNTPSERVER.

--enable-broken-listgroup-fix (default: off)
Bypass a bug in some broken NNTPservers which need an extra
GROUP command before accepting a LISTGROUP command.

NNTP_INEWS
Define if you want to use my built-in 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 DOMAIN_NAME is 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 NNTP-server file is other than /etc/nntpserver.

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

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

INDEX_DAEMON
!!! Using this define is deprecated and unsupported.
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
---------------------

--enable-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.

--enable-8bit-keys
Define if your terminal generates 8-bit controls.  For Unix systems we
assume this may imply your arrow keys begin either with CSI (0x9b) or SS3
(0x8f).  Most ANSI terminals generate 7-bit controls (e.g., CSI is
"<esc>["), but some such as VT220 can be configured more efficiently to
generate 8-bit prefix codes, saving a byte per control sequence.  This
applies to cursor movement at the same time.  The actual codes are read
from termcap (this does not affect the curses configuration).

--enable-color
Define if you want to have ANSI-color support.  This works on most
color displays and the color xterm.  The color mode can be switched
on/off in ~/.tin/tinrc (use_color) and can be toggled with option -a
or key '&'.

--with-defaults-dir=PATH

--with-ispell=PATH
Define if you have ispell (interactive spell-checker) installed and want the
option of checking your articles, mails before posting/mailing them.
If found in search path, this is used automatically.

--with-metamail=PATH
Define if you want metamail display your MIME messages.
If found in search path, this is used automatically.

--enable-mh-mail-handling
Enable 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 option so
let me know the problems by sending me a bug report ('R' bug command
from within tin).

--with-pgp=PATH
Define if you have PGP (Pretty Good Privacy encryption system)
installed and want the option of checking signatures, extract keys,
sign messages and add public key to messages.  This is bound to the
key 'g' or '^G'.
If found in search path, this is used automatically (pgp-5 (HAVE_PGP_5 set)
is prefered over pgp-2 (HAVE_PGP_2 set)).

--with-inn-nntplib=PATH
Define if you want to use the INN library functions GetConfigValue()
& GetFQDN(). PATH must be the correct path to the INN library.

--with-iso-to-ascii
Define if you want tin to do ISO-8859-1 Charset to ASCII conversions
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 CPPOPTS 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".

--with-local-charset
LOCAL_CHARSET
Define LOCAL_CHARSET if you like charset conversions.
set LOCAL_CHARSET to one of the following values:
	437	ibm437<->iso-8859-1 conversion
	850	ibm850<->iso-8859-1 conversion
	1	next<->iso-8859-1 conversion
	unset	no conversion (default)

--with-ncurses
Define this if you want to link with ncurses instead of termcap.

--enable-curses
Define this if you wish to use the curses screen optimizing rather than
termcap.  This has been tested well only with ncurses 4.1; it should work
(except for mouse support and screen resizing) with SVr4 curses (Solaris
2.5 is known to have a bug in libc which prevents use of curses, ncurses
works well on that platform).  To build with ncurses screen optimizing,
you must give both the --with-ncurses and --enable-curses options.

--enable-etiquette (default: on)
If enabled, prints netiquette before posting.

--enable-locale (default: on)
If enabled, tin uses multi language support, as described in
locale(7).  If you don't have locale support installed on your system,
try --disable-locale, otherwise you won't see any 8-bit-characters.

--enable-piping (default: on)
Disable if your system does not support piping of articles to shell commands
or if you don't want your users to have such support. Note: There may still
be possibilities for users to "pipe" an article to a command, even if you
disable this feature. They are just not able to use the '|' key to do so.

--enable-printing (default: on)
Disable if your system does not support printing or if you don't want your
users to have such support. Note: There may still be possibilities for users
to print an article, even if you disable this feature. They are just not
able to use the 'o' key to do so.

--enable-fascist-newsadmin (default: off)
Enable 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.

[FIXME: Find another name for this option.		-dn, 1998-12-27]

--enable-mmdf-mailer (default: off, except on SCO Unix)
If enabled, MMDF type mail handling is used as the default (instead of
mbox format). On SCO Unix this is always the case, no matter what you use
here. It can be dynamically changed by setting the tinrc variable
save_to_mmdf_mailbox to ON or OFF, respectively.

[NOTE: To change the default behaviour on SCO Unix, have a look to
 include/tin.h and search for HAVE_MMDF_MAILER.]

--enable-posting (default: on)
If disabled, TIN does not allow posting/followup of articles.

--enable-shell-escape (default: on)
If disabled, do not allow shell escapes. Note: There may still be
possibilities for users to start a shell (e.g. from within an editor or
using a shell as the "editor"), even if you disable this feature here.
They are just not able to use the '!' key to do so.

--enable-inverse-video (default: on)
Disable if you want inverse video and highlighted bar disabled. Can be
toggled in tin by the 'I' command and highlight bar by 'M' command.

[FIXME: Is this still true? 'M' command is for entering the config menu
 ... Is the support for disabling of this feature complete?
							-dn, 1998-12-27]

--enable-xhdr-xref (default: on)
If disabled, don't allow using XHDR XREF if XOVER doesn't work to mark
crossposted articles as read in all groups.

FORGERY
Define if you want to be able to cancel postings you did not write
yourself.  The !cyberspam and cancel conventions are supported.  Be
careful with this feature, it should not be used in an free accessible
tin.  This feature does not work with INN using the INN-inews (when
using without NNTP), because INN-inews rejects these cancels.

SMALL_MEMORY_MACHINE (not supported anymore)
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.


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

1)	i486 & Linux 0.99.14w with gcc 2.5.7
	i486 & Linux 1.2.13 with gcc 2.7.0
	i586 & Linux 2.0.36 with gcc 2.7.2.3
	i586 & Linux 2.2.6 with fcc 1.0
	i586 & Linux 2.2.10-ac9 with gcc 2.7.2.3
	i586 & Linux 2.3.9 with egcs-egcs-2.91.66
	Amiga 4000/040 & Linux 2.0.29 with gcc 2.7.2
	Power Macintosh 7200/75 & Linux 2.0.30 with gcc 2.7.2.1
	DEC Alpha AXP & Linux 2.0.0 with gcc 2.7.1
	Cobalt Microserver 27 (MIPS Nevada V10.0) & Linux 2.0.34 with gcc 2.7.2
	DEC Station 5000/xx (MIPS R3000A V3.0) & Linux 2.2.1 with egcs 2.90.27

2)	HP 9000/835 & HP-UX 8.00 with cc
	HP 9000/825 & HP-UX 8.00 with gcc 2.7.2
	HP 9000/735 & HP-UX 9.02 with gcc 2.6.3
	HP 9000/720 & HP-UX 9.05 with cc
	HP 9000/720 & HP-UX 9.05 with gcc 2.7.2
	HP 9000/715 & HP-UX 9.07 with cc
	HP 9000/715 & HP-UX 9.07 with gcc 2.7.2
	HP 9000/375 & HP-UX 9.10 with gcc 2.7.2.3
	HP 9000/819 & HP-UX 10.10 with cc
	HP 9000/819 & HP-UX 10.10 with gcc 2.7.2
	HP 9000/829 & HP-UX 10.20 with cc
	HP 9000/829 & HP-UX 10.20 with gcc 2.8.1

3)	VAX 8350 & Ultrix 4.0 with gcc 1.4.0
	VAX 8350 & Ultrix 4.0 with gcc 2.7.2
	DEC Station ??? & Ultrix 4.3 with gcc 2.6.3

4)	AlphaStation 3000 & Digital UNIX 3.2c with gcc 2.7.2
	AlphaStation 600 5/266 & Digital UNIX 3.2 with cc
	AlphaStation 3000/M800 & Digital UNIX V4.0B OSF/1 with cc

5)	AlphaStation ??? & OSF/1 v3.2 with cc
	AlphaStation ??? & OSF/1 v3.2 with gcc 2.7.2

6)	Sun SPARCstation 10 & SunOS 5.5 with cc 3.0.1
	Sun UltraSPARC Enterprise 2 & SunOS 5.5.1 with gcc 2.7.2
	Sun SPARCserver 1000 & SunOS 5.5 with cc 3.0
	Sun SPARCsystem 10/30 & SunOS 5.4 with gcc 2.6.3
	sparc-sun-solaris2.5.1 with Sun Sparcworks compiler (v 4.2)
	Sun 3/60 & SunOS 4.1.1_U1 with gcc 2.7.2.2
	Sun SPARCsystem 600 & SunOS 5.5.1 with WorkShop Compilers 5.0
	Sun SPARCsystem 600 & SunOS 5.5.1 with gcc 2.8.1
	i686 & SunOS 5.6 with gcc 2.8.1
	i586 & SunOS 5.7 with gcc 2.8.1
	i586 & SunOS 5.7 with WorkShop Compilers 5.0

7)	Intergraph Clipper & CLIX 7.5 with gcc 2.7.1

8)	i486 & BSDI 2.0 with gcc 1.42
	i486 & BSDI 2.0 with gcc 2.6.3

9)	i486 & NetBSD 1.1 with gcc 2.4.5
	i486 & NetBSD 1.2 with gcc 2.7.2
	Amiga 4000 & NetBSD 1.2 with gcc 2.7.2
	Sun 3/60 & NetBSD 1.2G with gcc 2.7.2.2

10)	i386 & FreeBSD 2.1.0 with gcc 2.7.2
	i586 & FreeBSD 2.2.7 with tcc 4.0 (TenDRA-4.1.2)
	i486 & FreeBSD 2.2.7 with gcc 2.7.2.1
	i586 & FreeBSD 3.0-SNAP-971208 with gcc 2.7.2.1

11)	IBM PowerPC RS6000/40p & AIX 4.1.5.0 with gcc 2.8.1
	IBM RS6000/990 & AIX 4.1.5 with xlc
	IBM 7012/320H & AIX 3.2 with gcc 2.3.3

12)	i586 & SCO OpenServer Enterprise System (ver 5.0.0b)
	with SCO OpenServer Development System (ver 5.0.0a)
	i486 & SCO System V Rel 3.2v4.2 with cc

13)	i386 & XENIX 2.3.3 with gcc 1.37.1

14)	NeXT Computer & NeXTSTEP 3.3 with gcc 2.5.8

15)	SGI SC900 Power Challenge & IRIX 6.2 with gcc 2.7.2
	SGI SC900 Power Challenge & IRIX 6.2 with cc -32
	SGI Indigo2 & IRIX 5.3 with gcc 2.7.2
	SGI 4D/35 & IRIX 5.2 with IDO 5.2
	SGI 4D/35 & IRIX 5.2 with gcc 2.8.1

16)	m88k mc88110 & UNIX_System_V 4.0 R40V4.4
	with Motorola Configurable C Compilation System (CCCS) 1.0

17)	Amiga 4000 & AmigaOS 3.0 with SAS/C 6.57

18)	OpenVMS/Alpha 6.2, DEC C V5.0-003,                  SOCKETSHR_TCP
	OpenVMS/Vax   5.3, GCC 2.7.2 (Pat Ranking edition), SOCKETSHR_TCP

19)	i586 & Windows95 with CYGWIN_95-4.0/20.1
	i686 & WindowsNT with CYGWIN_NT-4.0/20.1
