Husky Installation Instructions
===============================
$Header: /cvsroot/husky/huskybse/INSTALL,v 1.9 2002/11/29 10:18:32 stas_degteff Exp $
This file covers all basic questions that you might have if you are new to
the Husky software. Please read those sections that are of interest to you
carefully.
Compiling Husky source is a little more complicated than compiling standard
Unix software. In particular, there is no configure script. So even if you
are an experienced user, please have a look at section II of this document.
(Editors note: This file is to be edited with Emacs with text-mode and
auto-fill-mode, and fill-column set to 77. Please indent all text that is to
be set in a fixed-width font with two spaces.)
Contents
========
I. Overview
II. Compiling the Source Code
III. How to Configure and Use the Software
I. Overview
===========
The Husky Fidonet software package is split into different "modules". A
module is a library or a program. In order to compile any Husky program, you
will at least have to download the following modules:
huskybse Husky Base, contains instructions, a template compilation
configuration file, and sample configs.
smapi The Squish Message API library.
fidoconf The Fidoconfig library.
In addition, you need the programs that you want to use, like "hpt" (the
tosser), "htick" (the ticker), "msged" (the mail editor), and others. For a
full list of available modules, refer to the husky homepage.
The distribution filenames of the modules are named
MODULENAME-VERSION.tar.gz e.g. smapi-1.6.4-stable.tar.gz
for the release versions or
MODULENAME-yymmdd.tar.gz e.g. smapi-000521.tar.gz (snapshot from 21st May 2000)
MODULENAME-latest.tar.gz e.g. smapi-latest.tar.gz (current snapshot)
for the daily snapshots. Unless you are a very experienced user, or have
explicitly been instructed, you should use the release versions. They are
available at the Husky homepage at http://husky.sourceforge.net.
Note that IF you really want to get daily snapshots from
http://husky.sourceforge.net/cvs2, you should fetch all modules that
you need at once, i.E. use snapshots from the same day for all libraries and
programs.
II. Compiling the Source Code
=============================
Download all the modules that you want to use, and untar them in a common
directory. E.g:
mkdir ~/husky
cd ~/husky
tar xzf ~/download/huskybse-latest.tar.gz
tar xzf ~/download/smapi-latest.tar.gz
tar xzf ~/download/fidoconf-latest.tar.gz
tar xzf ~/download/hpt-latest.tar.gz
Replace -latest with the actual file name extension. This could be "-latest"
if you download from our CVS site, but it could also be something like
"-1.2.0-stable", "-1.2.1-release", etc.
Then, there are two basic ways of building Husky source: You can use the
standard Makefile with huskymak.cfg, or you can use the platform dependent
Legacy Makefiles. Usually, the former will be your primary choice.
II.1 Compiling and installing with the standard Makefile and huskymak.cfg
-------------------------------------------------------------------------
II.1.1 Overview
This is the standard way of compiling Husky source code on Unix-style
operating systems. It will also work on OS/2 if you have the EMX compiler and
a more or less complete chain of GNU tools installed. You should use this
method if you are a Unix user.
If you compile Husky in this way, the default path of the configuration file
and other specialties will be compiled into your executables based onto your
individual needs, and shared libraries will be used if possible to decrease
hard disk space requirements and improve flexibility.
In order to use the standard Makefiles with huskymak.cfg, you must use GNU
make (gmake). GNU make is the standard make program on Linux, while on most
other Unix systems (including FreeBSD, NetBSD, Tru64, Solaris and others),
the standard "make" command will NOT work with the Husky standard
Makefiles. You should obtain a copy of GNU make and use that one to build
Husky. Or, if you can't get GNU make, refer to section II.2 and use the
legacy Makefiles.
The drawback of this way is that it only works on Unixish systems, and that
it requires some of the libraries to be installed before the rest of the
software can be compiled. If you don't want to install anything while
compiling, you should use the Legacy Makefiles (Section II.2)
II.1.2 Configuring
Every Module is supplied with a "Makefile". This is the standard Makefile,
and will only work with GNU make.
In order to use it, you need to create a file named "huskymak.cfg" in the top
level directory below which you extracted the individual module sources,
which you will use to configure the peculiarities of your system. In the
example from above, this file would be named "~/husky/huskymak.cfg".
You don't need to create this file by hand - the huskybse module contains
template huskymak configuration files. Select one, copy it to the top-level
directory, and then edit it to adapt it to your needs. The following example
files are currently provided:
File Platform
-------------------------------------------------------------------
huskymak.cfg Generic UNIX (will work as is on Linux, contains
documentation on what to change for other Unices)
huskymak.cfg.bsd FreeBSD (possible OpenBSD and NetBSD)
huskymak.cfg.sun SunOS (Solaris), using GNU C & GNU make
So, for example, you would do
cd ~/husky
cp huskybse/huskymak.cfg ./huskymak.cfg
emacs huskymak.cfg # or would you rather like vi? ;-)
Note that the "huskybse" subdirectory, like any other subdirectory mentioned
from now on, might also have a version number as prefix, like
"huskybse-0.10", depending from where you got the source files from.
Please read the comments in the template huskymak.cfg and change all values
according to your needs.
II.1.3 Compiling and Installing
Now, you can build smapi and fidoconfig (please do it in this order) using
cd ~/husky/smapi
make clean
# or use "gmake" if "make" does not invoke GNU make on your system!
make all install
cd ~/husky/fidoconf
make clean
make all install
It is important that you a) INSTALL (gmake install) smapi before you try to
COMIPLE fidoconf, because otherwise the smapi library - which is required for
building fidoconfig - will not be found, and likewise, that you INSTALL
fidoconf before you try to COMPILE anything else. For the other modules, you
don't have to take care about any particular order. You can build and install
any module using the command sequence
cd ~/husky/MODULENAME
make clean
make all install
After you did this with all modules, read on in section III of this document.
II.2 Compiling with the Legacy Makefiles
----------------------------------------
II.2.1 Overview
---------------
Besides the standard "Makefile", most Husky modules deliver additional
makefiles, named "makefile.XXX", where "XXX" is a platform dependent
suffix. Those makefiles are called legacy makefiles by us. They differ from
the standard Makefile in the following ways:
+ You don't need to edit huskymak.cfg, the makefiles work for themselves
+ You can compile everything without having to install anything
+ Many non-UNIX systems are supported
+ You don't need neither GNU make nor gcc if not specified other
+ Sometimes gives less trouble than the standard Makefile
- You cannot install anything with these makefiles (usualy). It is within
your responsibility to copy the programs that you compiled to the
proper directories.
- No support for shared libraries, everything is linked statically.
II.2.2 List of platforms supported by the legacy makefiles
----------------------------------------------------------
The following is a list of platforms that are supported by legacy
makefiles.
Makefile Sup. Platform Compiler
---------------------------------------------------------------------------
makefile.unx 1 Unix Any (standard "cc" is enough!)
makefile.be 1 BeOS BeOS R5 with gcc
makefile.bsd 1 BSD (tested: FreeBSD) GNU gcc
makefile.lnx 1 Linux GNU gcc (2.7..2.95, 3.x)
makefile.djg 1 DOS/32 DJ Delorie GNU gcc (DJGPP)
makefile.cyg 1 Win32 Mingw32 on Cygwin: http://www.cygwin.com
makefile.mvc 1 Win32 Microsoft Visual C
makefile.mvcdll 1 Win32 Microsoft Visual C - dll build
makefile.emo 2 OS/2 EMX; OMF static (standalone) binaries
makefile.emx 2 OS/2 EMX; a.out dynamic (EMXRT) binaries
makefile.mgw 2 Win32 Mingw32 or Mingw32/CPD gcc: www.mingw32.org
makefile.rxw 2 Win32 EMX/RSXNT gcc with -Zwin32
makefile.sun 2 Solaris GNU gcc
makefile.wco 2 OS/2 Watcom C
makefile.wcw 2 Win32 Watcom C
makefile.wcx 2 DOS/32 Watcom C with DOS extender
makefile.aix 3 AIX IBM xlC
makefile.bcd 3 DOS Borland C / Turbo C (requires TASM)
makefile.bco 3 OS/2 Borland C 2.0
makefile.bcw 3 Win32 Borland C
makefile.ibo 3 OS/2 IBM CSet or VACPP
makefile.hco 3 OS/2 Metaware High C
makefile.osf 3 TRU64 Compaq CC (or DEC Unix with DEC cc)
makefile.wcd 2 DOS Watcom C
makefile.qcd 2 DOS Quick C / Microsoft MSC 6.0 (req. MASM)
The "Sup." classification has the following meaning:
1 Means this makefile is the primary one used by Husky developers
for this particular platform, e.g. for building binary releases. It is
very well supported and should work without problems. Every Husky
module that has left beta phase should have this makefile.
2 At least one Husky developer is sometimes using this file, so it will
be more or less up to date and should mostly work. Most projects will
have this makefile.
3 Only some projects have this makefile, it is not known if anybody
currently uses this or if it works at all. (Note this does not mean
that Husky will not work on this PLATFORM, but only that this MAKEFILE
probably is highly outdated).
As a rule of thumb, if you have any Unix OS with a "make" and a "cc" command,
you should first try to use "makefile.unx". "makefile.unx" is a very
troublefree way of building everything!
II.2.3 Compiling
----------------
First, if your subdirectories contain version number suffixes, you need
to rename the smapi and fidoconf subdirectories to the base name with
out version number suffix. E.g., if, after extracting the sources, you have
directories called like "smapi-1.6.4" and "fidoconf-0.10", you must rename
them to "smapi" and "fidoconf", respectively. This is so that the other
projects are able to find the include files etc. You do not need to rename
the directories for the other projects.
Now that you have chosen the proper makefile, build smapi and fidoconfig like
this (let's assume you have chosen makefile.unx):
cd ~/husky/smapi
make -f makefile.unx clean
make -f makefile.unx
cd ~/husky/fidoconf
make -f makefile.unx clean
make -f makefile.unx
You can then directly proceed to build any program like this:
cd ~/husky/MODULENAME
make -f makefile.unx
This also works with Non-UNIX systems, e.g.:
C:
CD \HUSKY\SMAPI
imake -f makefile.ibo clean
imake -f makefile.ibo
CD \HUSKY\FIDOCONF
imake -f makefile.ibo clean
imake -f makefile.ibo
CD \HUSKY\MSGED
imake -f makefile.ibo clean
imake -f makefile.ibo
II.2.4 Installing
-----------------
As already noted, the legacy makefiles usually do not contain an "install"
target. Therefore, you have to "install" the programs manually if you use
legacy makefiles (you don't need to install the libraries, as the programs
are linked against those statically). For most Husky programs, installing is
just copying the executables to a directory of your choice. For some others,
it is more complicated, in particular Msged, where you must also install the
recoding tables, help files etc.. Please refer to the individual programs'
documentation for more information.
III How to Configure and Use the Software
=========================================
We assume you have now a set of executables of the Husky software. Either
compiled manually, or downloaded in binary form from somewhere. Now - where
do you go from here?
III.1 Creating the configuration file
-------------------------------------
The good news is that all Husky programs only need a single configuration
file. It's filename is "config", and you should put it into the directory
that you have configured as CFGDIR in huskymak.cfg.
If you don't know the value of CFGDIR, because you compiled the source with
legacy makefiles (no CFGDIR setting) or because you have downloaded binary
versions, you should set up an environent variable FIDOCONFIG which should
contain the path and filename of that config file. E.g., on Unix with
ksh/bash, you would put something like
FIDOCONFIG=/etc/fido/config; export FIDOCONFIG
to /etc/profile, while you would use
SET FIDOCONFIG=c:\fido\config
for config.sys on OS/2 or autoexec.bat for Win9x. On Windows NT, you would
use the System Control Panel.
Now what do you write into this configuration file?
III.2 Fidoconfig documentation
------------------------------
Each and every configuration value that you can put into the fidoconfig
configuration file is described in the fidoconfig documentation. If you have
a binary distribution of the Husky software, you should have received this
documentation in HTML or a similar format.
If you have compiled with huskymak.cfg / standard Makefiles, you should
theoretically be able to type "info fidoconfig" on the command line to view
the fidoconfig documentation. However, this will not work on all Linux
distributions.
You can manually build and view the fidoconfig documentation as follows:
Change to the documentation subdirectory:
cd ~/husky/fidoconf/doc
Then type this to build the GNU info version:
makeinfo fidoconfig
info -f ./fidoconfig.info
This requires a working TEXINFO installation on your Unix system. TEXINFO is
also available for OS/2 and cygwin.
Or, you can try to build the HTML version:
makeinfo --html fidoconfig
(or texi2html fidoconfig)
lynx ./fidoconfig_toc.html
III.3 Examples
--------------
Not everybody likes to build a config file from scratch using only a keyword
reference. Therefore, the "huskybse" module contains various example
configuration files. Have a look at these!
The "fidoconfig" module contains a script "fidoInst" which asks you some parameter
of your system and will create a basic config file. This script is tested
on linux with bash.
III.4 Other Documentation
-------------------------
Some of the Husky tools have their own documentation. Go and search for it in
their source directory. In particularly, you should read the "installation
instructions" part of the Msged TE manual if you want to use Msged. The Msged
TE manual can be build similar to the fidoconfig manual, but you can also
simply download it in various formats from the Msged TE homepage
(http://www.physcip.uni-stuttgart.de/tobi/msged).
On the Husky homepage (http://husky.sourceforge.net), you will also
find some pointers to FAQ's and other helpful documents.
III.5 Operations Guide
----------------------
With the information mentioned so far, you should be able to get a Fido point
or node going if you are already somewhat familiar with running a Fido
system. Most tools will show some information if you invoke them without
parameter. Unfortunately, there currently is no full Husky operations
guide. Perhaps you want to write one?
Again, a look into the sample files in the "huskybse" module could be
helpful. There are also some scripts.
[EOF]
