source: trunk/doc/third-party @ 15326

For the most part, third-party software is easy to locate because it
is found in the third hierarchy.  Nevertheless, it's a good idea to
keep track of what we get from outside, especially for things outside
of third.  There are also some notes at the end of this file on how we
deal with building third-party software.

Third-party stuff not under third
---------------------------------

        * athena/etc/xlogin/bitmaps/menu16

                This is from the X11 release; it probably never
                changes.  We have a copy of it here because xlogin
                needs all its bitmaps locally in /etc/athena/login,
                and fetching it out of the vendor X distribution at
                build time is contrary to principles.

        * packs/build/autoconf/

                The files in this directory are copied from
                third/autoconf and used by do.sh.

        * packs/config/named.root

                This is a copy of the named.root file available at
                rs.internic.net:/domain/named.root.

        * packs/config/Dash.fallback

                A fallback copy of
                /afs/athena.mit.edu/system/config/dash/Dash.menus for
                when the master copy is inaccessible.  This should be
                updated at release time.

        * packs/dotfiles/arch/sgi_*/cshrc

                A line to set XUSERFILESEARCHPATH in .cshrc is derived
                from a piece of the IRIX file /var/X11/xdm/Xsession.dt.

        * packs/dotfiles/{README.mail,dot.cshrc,dot.login,dot.logout,
                dot.mh_profile,welcome}

                These should be kept in sync with the copies on
                moira's local disk (/moira/dotfiles/*), which are
                what actually get copied into new home directories.

        * Modified operating system files

                We keep some modified configuration files from the
                operating systems we use in the os and arch
                subdirectories of packs/config and packs/maint.
                The files and their origins are:

                Solaris files in packs/config:

                Athena4.kt      /usr/openwin/share/etc/keytables/US4.kt.Z
                Athena5.kt      /usr/openwin/share/etc/keytables/US_UNIX5.kt.Z
                devlink.tab     /etc/devlink.tab
                inetd.conf      /etc/inet/inetd.conf
                inittab         /etc/inittab
                logindevperm    /etc/logindevperm
                keytable.map    /usr/openwin/share/etc/keytables/keytable.map
                minor_perm      /etc/minor_perm
                name_to_sysnum  /etc/name_to_sysnum
                nsswitch.conf   /etc/nsswitch.conf
                services        /etc/inet/services
                su              /etc/default/su
                system          /etc/system

                Solaris files in packs/maint:

                nfs.client      /etc/init.d/nfs.client
                rpc             /etc/init.d/rpc

                IRIX files in packs/config:

                4DWm            /usr/lib/X11/app-defaults/4DWm
                Mwm             /usr/lib/X11/app-defaults/Mwm
                Toolchest       /usr/lib/X11/app-defaults/Toolchest
                crontab.root    /var/spool/cron/crontabs/root
                fonts.alias     /usr/lib/X11/fonts/100dpi/fonts.alias
                fonts.dir       /usr/lib/X11/fonts/100dpi/fonts.dir
                inetd.conf      /etc/inetd.conf
                services        /etc/services
                system.chestrc  /usr/lib/X11/system.chestrc

                IRIX files in packs/maint:

                network         /etc/init.d/network

Distribution sites for software under third
-------------------------------------------

        afsbin          See below.
        bind            ftp.isc.org:isc/bind/src
        db              http://www.sleepycat.com/download.html
        emacs           ftp.gnu.org:pub/gnu/emacs; see also "leim"
        gcc             ftp.gnu.org:pub/gnu/gcc
        gettext         ftp.gnu.org:pub/gnu/gettext
        glib            ftp.gtk.org:pub/gtk
        gtk             ftp.gtk.org:pub/gtk
        gmake           ftp.gnu.org:pub/gnu/make
        gmp             ftp.gnu.org:pub/gnu/gmp
        gnome-libs      ftp.gnome.org:pub/GNOME/stable/sources/gnome-libs
        imlib           (Formerly www.rasterman.com; imlib 1 is dead now)
        inetd           From NetBSD (ftp.netbsd.org), usr.sbin/inetd
        intlfonts       ftp.gnu.org:pub/gnu/intlfonts
        ispell          ftp.cs.ucla.edu:pub/ispell-3.1
        jot             From NetBSD (ftp.netbsd.org), usr.bin/jot
        jpeg            ftp://ftp.uu.net/graphics/jpeg/
        kermit          http://www.columbia.edu/kermit
        krb5*           http://web.mit.edu/network/kerberos-form.html
        lam             From NetBSD (ftp.netbsd.org), usr.bin/lam
        leim            ftp.gnu.org:pub/gnu/emacs; see below
        libglade        ftp.gnome.org:pub/GNOME/stable/sources/libglade
        libpng          http://www.libpng.org/pub/png/libpng.html
        libungif        prtr-13.ucsc.edu:pub/libungif
        look            From NetBSD (ftp.netbsd.org), usr.bin/look
        lprng           ftp.astart.com:pub/LPRng; see below
        mdoc            From NetBSD (ftp.netbsd.org), share/tmac
        nmh             ftp.math.gatech.edu:pub/nmh
        nvi             http://www.bostic.com/vi/
        ORBit           ftp.gnome.org:pub/GNOME/stable/sources/ORBit
        patch           ftp.gnu.org:pub/gnu/patch
        perl            ftp.cpan.org:pub/CPAN/src
        readline        ftp.gnu.org:pub/gnu/readline
        rcs             ftp.gnu.org:pub/gnu/rcs
        read-edid       http://web.onetel.net.uk/~elephant/john/programs\
                        /linux/read-edid/
        rep             librep.sourceforge.net:pub/librep
        rep-gtk         rep-gtk.sourceforge.net:pub/rep-gtk
        rs              From NetBSD (ftp.netbsd.org), usr.bin/rs
        sawfish         sawmill.sourceforge.net:pub/sawmill
        sendmail*       ftp.sendmail.org:pub/sendmail
        ssh*            ftp.cs.hut.fi:pub/ssh
        sysinfo         http://www.magnicomp.com/
        talk            From NetBSD (ftp.netbsd.org)
                        usr.bin/talk goes in the talk subdirectory
                        libexec/talkd goes in the talkd subdirectory
                        protocols/talkd.h is from include/protocols,
                         with some modifications for portability.
        tcp_wrappers*   ftp.porcupine.org:/pub/security
        tcsh            ftp.astron.com:pub/tcsh
        tex             See below
        top             ftp.groupsys.com:pub/top
        traceroute      ftp.ee.lbl.gov (top level)
        transcript      From Adobe
        wcl             ftp.x.org:contrib/devel_tools
                        (seems to have disappeared; older versoins than
                        what we have are available in R5contrib)
        whois           From NetBSD (ftp.netbsd.org), usr.bin/whois
        x3270           ftp.x.org:contrib/applications
        xmh             From X11R5
        xpm             ftp.x.org:contrib/libraries
        xscreensaver    http://www.jwz.org/xscreensaver/
        zlib            ftp.info-zip.org:pub/infozip/zlib

PGP Signatures
--------------

The (*)ed packages above come PGP-signed. Note that some packages have
signatures of the .tar.gz files, and others have signatures of the .tar
files themselves even though you can only download the .tar.gz files.

Local copies of the PGP signing keys, are kept in doc/pgpkeys. You can
add them to your PGP keyring by doing:

        pgp -ka pgpkeys [PGP 2.6]
        pgpk -a pgpkeys [PGP 5]

And you can verify the signature of a package with

        pgp sigfile  [PGP 2.6]
        pgpv sigfile [PGP 5]

(You will be prompted for the name of the file to compare the
signature against.)

AFS Binaries
------------

AFS binaries are placed under arch/<architecture name> for each
architecture.  For each platform, you should do an import of the
"include" and "lib" directories of the dest tree, using the vendor tag
"transarc" and a release tag like "afs-3_4a_patches_2".  For "lib",
you will have to use the option "-I \!".  At the top level, you should
have afsd, fs, tokens, unlog, and possibly afs.rc; we don't bother
with "cvs import" for these files.  You will also need the kernel
module itself, which varies per platform.

You must do "cvs admin -kb" (or import/checkin with the -kb option) on
binary files so that they won't get trashed by RCS ID mangling.

LPRng
-----

We import three packages: the LPRng sources themselves
(LPRng/LPRng-x.tgz) into third/lprng/lprng, the LPRng documentation
(LPRng/LPRng_DOC-x.tgz) into third/lprng/doc, and the ifhp filter
(FILTERS/ifhp-x.tgz) into third/lprng/ifhp.

LEIM
----

LEIM (Library of Emacs Input Methods) is built as part of Emacs, but
distributed separately. New versions of LEIM should be imported along
with new versions of Emacs, in third/emacs/leim.

TeX
---

There is no single distribution of what we install from TeX.  The
files we install were retrieved from the CTAN (Comprehensive TeX
Archive Network) archive, mirrors of which are at several places
including ftp.duke.edu:/tex-archive and ftp.cdrom.com:pub/tex/ctan.
A list of CTAN mirrors is available via "finger ctan@ftp.dante.de".
Here is a list of what we got and what subdirectories they were
imported into:

        web, web2c from systems/web2c           web2c
        dvips from dviware/dvips                dvips
        xdvi from diware/xdvi                   xdvi
        fonts/cm/mf                             lib/mf/typefaces/cm
        fonts/latex/mf/* (ignore symlinks)      lib/mf/typefaces/latex
        fonts/amsfonts/sources/euler            lib/mf/typefaces/euler
        fonts/amsfonts/sources/symbols          lib/mf/typefaces/ams
        fonts/amsfonts/sources/extracm          lib/mf/typefaces/cm-ams
        fonts/amsfonts/sources/cyrillic         lib/mf/typefaces/cyrillic
        fonts/punk                              lib/mf/typefaces/other
        fonts/tengwar                           lib/mf/typefaces/tolkien
        fonts/cirth                             lib/mf/typefaces/tolkien
        fonts/oca                               lib/mf/typefaces/ocr
        fonts/ocr-a                             lib/mf/typefaces/ocr
        fonts/ocr-b                             lib/mf/typefaces/ocr
        fonts/amsfonts/sources/*.mf             lib/mf/macros
        systems/knuth/lib/*.mf* (must gunzip)   lib/mf/macros
        systems/knuth/lib/*.tex (must gunzip)   lib/tex/macros
        macros/amstex/ams* (include amssym)     lib/tex/macros
        biblio/bibtex/distribs/styles           lib/tex/macros/bib
        macros/latex/unpacked                   lib/tex/macros/latex
        macros/latex/packages/amslatex          lib/tex/macros/amslatex

This is pretty complicated (especially when you add in our own files,
plus the stuff in lib/tex/macros/other which we don't bother
identifying the source of).  Ideally, the contents of lib should be
organized around distributions rather than installed directories, but
the CTAN archive is not especially well-organized in that respect.  If
anyone ever attempts a reorganization around distributions, they
should probably just create a new hierarchy and delete the contents of
the "lib" hierarchy.

Imports of new versions
-----------------------

CVS (at least as of version 1.9) has the irritating weakness that
import operations never delete files; you have to delete the removed
files in a new version of a package by hand.  If the import command
was "cvs import module vendor-branch release-tag", then to delete
files you do:

        cvs co -r vendor-branch module
        cd module
        cvs -n update -r release-tag |& \
                awk '/no longer/ { print $3; }' > /tmp/files
        xargs cvs rm < /tmp/files
        cvs ci
        awk '{print "module" $0; }' /tmp/files > /tmp/files2
        xargs cvs rtag -r vendor-branch release-tag < /tmp/files2

Yuck.  But it works.  For each deleted file, a dead revision will be
checked in on the vendor branch and tagged with release-tag.  (The
tagging part may be unnecessary, but should not be undesirable.)

If, after an import, there are files which have been modified on the
mainline but do not need to be locally modified any more, you can run
"cvs admin -bvendor-branch" on the files to make them revert to the
vendor branch.  But first, check in an unmodified copy of the vendor
branch file onto the mainline, so that the version history of the file
is clear.

Third-party build systems
-------------------------

There are two avenues one can take for building third-party software:

        * You can use the native build system.

        * You can declare the native build system a loss, and use one
          of the two Athena build systems described in the file
          "build-system" in this directory.  This option is not
          preferred, but is necessary in cases like afsbin (where we
          are simply installing target files) or software imported
          from NetBSD.

In a some cases, the native build system may already conform to the
Athena build system (a configure script which needs no special options
for the Athena environment besides those given in our config.site
file), but generally you will have to write either a configure.athena
or a Makefile.athena file specifying how to build and install the
program.

configure.athena is used when the package builds and installs
normally, but needs to have extra options passed to configure (or has
a configure script which isn't named "configure", or needs additional
steps performed before or after the configure script).

Makefile.athena is needed if the package needs to do anything unusual
at any of the other steps.  A Makefile.athena must have the following
targets:

        prepare         Prepare to build the source tree
        clean           Remove files generated by the all target
        all             Generate all automatically build files
        check           Perform automatic tests, if any
        install         Install the software in $SRVD.

A Makefile.athena file may rely on the following environment variables
(it is most robust to use `"$$VARNAME"' instead of `"${VARNAME}"' in
rules to get the value of such variables):

        ATHENA_SYS      Architecture name for this system
        HOSTTYPE        Platform name for this system
        SRVD            Install destination directory (e.g. /srvd)
        SOURCE          Source tree (e.g. /mit/source)
        COMPILER        Appropriate compiler/linker for this system
        CONFIGDIR       Location of Athena Imake templates
        XCONFIGDIR      Location of X-style Imake templates
        ATHTOOLROOT     Root of installed Athena tree

Following is a sample Makefile.athena file, used to build a package
which uses an X-style Imakefile:

        # $Id: $

        SHELL=/bin/sh

        prepare:
                imake "-I$$XCONFIGDIR" -DUseInstalled "-DSRCDIR=$$SOURCE"
                ${MAKE} Makefiles

        clean:
                ${MAKE} clean

        all:
                ${MAKE} includes depend all

        check:

        install:
                ${MAKE} install DESTDIR="$$SRVD"