\documentclass[a4paper,10pt]{article}
%, twocolumn
\usepackage{graphicx}

\title{store-extra: Useful Store admin and config applications}
\author{Petter Reinholdtsen $<$pere@td.org.uit.no$>$}
\date{2000-06-27}

\begin{document}
\maketitle

\section{Introduction}

The {\tt store-extra} Store application is my collection of useful
Store admin and config scripts which is not part of the Store base
({\tt perl-internal}).  Most of it used to be part of smaller
applications, but I decided to collect it into one application
instead.

This is the collection of what used to be {\tt store-pere}, {\tt
env-config}, {\tt mime-config}, {\tt emacs-info}, {\tt build-all} and
some scripts from NTNUs {\tt emacs} application.

I did not write all these scripts.  I have lost track of all the
authors, but some of them were written by Espen Skoglund, Bjørn
Stabell, Arne H. Juul, and more.  If your credit is missing here,
please let me know.

\section{Compiling new applications and versions}

The build-all scripts provides the simplest way to compile new
programs in store.  It works best with source using GNU autoconf and
Perl modules.  It has limited support for X imake source and normal
makefiles.  If the application fails to compile using build-all, the
original method described in the original Store documentation must be
used instead.

When everything works as it should, this sequence would give a
compiled version of a new application:

\begin{enumerate}

\item Make new application subdirectory in {\tt /store/store/<master>/}.

\item Fetch source and update {\tt registration} with source location.
  FTP sites are better then HTTP sites.  Replace version number with
  {\tt \$version} to allow automatic detection of new versions.

{\small
\begin{quote}\begin{verbatim}
echo 'Source: ftp://ftp.gnu.org/pub/gnu/gcc-${version}.tar.gz' >> registration
\end{verbatim}\end{quote}
}


\item Unpack source in application subdirectory.  Rename source
  subdirectory to {\tt src-<version>}.

\item Check source to find out if there is a {\tt configure} script
  (=buildtype GNU) or a {\tt Makefile.PL} file (=buildtype pm).  If
  not, build-all is likely to fail.


\item Create a file {\tt buildinfo} in the applicatio subdirectory

  with the information required to get build-all to compile this
  application.  The absolute minimum file contains {\tt appname}, {\tt
  version} and {\tt buildtype}.

{\small
\begin{quote}\begin{verbatim}
appname=nasm
version=0.98
buildtype=GNU
\end{verbatim}\end{quote}
}

\item Run {\tt build-all [archs]} in application subdirectory and
  check the current compile status in the files {\tt out.<arch>} to
  find out if everything works as planned.

{\small
\begin{quote}\begin{verbatim}
tail -f out.<arch>
\end{verbatim}\end{quote}
}

\item If this was a perl module, run {\tt pm-touch-compiled} to make
  sure platform dependent subdirectories are properly marked in Store.

\item Check content of ver-<version> to make sure everything looks OK.

\item Run {\tt chkapp} to make sure everything went OK., {\tt
  register} to insert and update the info on the application and to
  log what was done.

\item Run {\tt linkup} and test if the program is working.

\end{enumerate}


\section{Common environment settings}

Two files are generated with the common environment settings, {\tt
/store/etc/src.sh} and {\tt /store/etc/src.csh}.  One file for the
Bourne shell family (sh, ksh, zsh, bash, etc) and one for the C shell
family (csh, tcsh).  These files are generated by {\tt
/store/etc/internal/make-env.pl} based on the content in {\tt
/store/etc/ENV/ENV-*}.  They are regenerate every time the nightly
commands are being run.

The format is quite simple, with '\#' as the comment marker, and the
fields in the env lines being
'username;group;priority;type;variable=content.

\begin{quote}
\begin{verbatim}
#
# Set path, check if directories exists.
*:*:1:p:PATH=/store/gnu/bin:/store/opt/*/bin
*:*:2:p:PATH=/store/bin:/store/sbin
!0:*:5:p:PATH=/usr/games
#
# Include in path without checking for the directories
*:*:1:n:XFILESEARCHPATH=/store/lib/X11/app-defaults/%N
*:*:9:n:XFILESEARCHPATH=/usr/local/lib/X11/%L/app-defaults/%N
#
# Single variable
*:*:9:s:PAGER=more
\end{verbatim}
\end{quote}

Username and group must be '*' or user or group id number.  '!'
negates the test.  In the example, this make sure user root (0) do not
get /usr/games as part of the PATH.

The path environment type 'p' and 'n' will remove duplicate entries,
and only keep the highest priority entry.  The single entry
environment 's' will only keep the highest priority entry.  The
priorities is sorted as perl strings, '12' having lower priority then
'9'.

The 'p' env type content might use filename globbing, as shown with
{\tt /store/opt/*/bin}.

If you are installing an application which requires special
environment settings, the best way to handle this is to use a small
shell wrapper to set the environment and then call the program.
Renaming the binaries from {\tt file} to {\tt file.exe} and making a
new shell script {\tt file} which sets the environment is the best
way.  Only when this is no option, you should use the
etc/ENV/ENV-application files.  I suggest naming the files en ENV/
after the application they belong to, i.e ENV-netscape for netscape
env settings and ENV-less for less env settings.

\section{MIME mailcap files}

When installing MIME content handlers, one wants to make them
automatically available in mail programs and web browsers.  This is
done by placing a file in {\tt /store/etc/mailcaps/}.  The files are
named {\tt mailca-<app>-<priority>}, and looks like normal MIME
mailcap entries:

\begin{quote}\begin{verbatim}
audio/x-mpeg; /store/bin/mpg123 %s;
\end{verbatim}\end{quote}

Based on these files, a list of MIME content handlers are generated
into {\tt /store/etc/mailcap} by {\tt
/store/etc/internal/make-mailcap.pl}.  The priorities are sorted as
numbers.

\section{Emacs info and default.el files}

\subsection{Emacs info directory}

All emacs info files should be installed in {\tt /store/info/}.  These
files can (and probably should) be compressed with {\tt gzip}.  Based
on the content of this subdirectory, a emacs info directory file ({\tt
/store/info/dir}) is generated by {\tt
/store/etc/internal/make-emacs-dir.pl}.  This program requires a
section like this in the info files:

\begin{quote}\begin{verbatim}
INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* Cpp: (cpp).                  The GNU C preprocessor.
END-INFO-DIR-ENTRY
\end{verbatim}\end{quote}

All emacs info and texinfo files should have a section like this.  If
it is missing, send a patch to the author.  When working with .texi
files, a section like this will make sure the resulting info files
will be included in the info/dir file:

\begin{quote}\begin{verbatim}
@dircategory Programming
@direntry
* Cpp: (cpp).                  The GNU C preprocessor.
@end direntry
\end{verbatim}\end{quote}

\subsection{Emacs default.el}

Generates {\tt /store/lib/emacs/site-lisp/default.el} and {\tt
/store/share/emacs/site-lisp/default.el} from {\tt default.el-<app>}
in the same directory.

\section{Netscape plugins}

To make sure Netscape finds the installed plugins, they must be
installed in a common directory, and environment {\tt
NPX\_PLUGIN\_PATH} must be set to point to this directory.  The
environment should be set in a wrapper shell to make sure it is always
set when netscape is running.

I propose using {\tt /store/opt/ns-plugins/} as this common directory.
I suggest naming the Netscape plugin applications with prefix '{\tt
nsp-}', to make it easier to track the different netscape plugins
available.

\section{GIMP plugins}

[I do not know enough about gimp to make a suggestion here.]

\section{List of recently installed applications}

To make it easier for the users to keep track of the applications
available in /store, the script {\tt /store/etc/internal/news.pl}
generates UNIX news files in {\tt /store/news}.  These files can then
be accessed by news(1) to get a list of recently installed
applications.

\section{Various tools}

- store-pere

  check-libtool-libs.pl  findold.pl      nightly-fix-suid.pl  sourcewatch.pl
  chkapps.pl             fix-docdirs.pl  prognews.pl          usage.pl
  collectusage.pl        showusage.pl    vusage.pl

  compare-linktrees  store-app-dependson


\section{Build-all -- parallel multiplatform autocompile}

The buildall system consist of the following configuration files:

\begin{itemize}

\item[\~{}store/etc/master.conf]

        Site specific configuration (information about master store
        etc).

\item[\~{}store/etc/buildhosts]

        The list Store architectures to compile for, and the hosts to
        compile the application for this architecture.

\item[\$appdir/buildinfo]

        The application specific information, located in the
        application master directory.

\end{itemize}

The following programs are part of buildall:

\begin{itemize}

\item[/store/bin/build-all]

        The program called when starting to compile.  This must be run
        in the application master directory.

\item[/store/etc/internal/buildsubs]

        Script called by build-all to do the work required.

\item[/store/bin/pm-touch-compiled]

        Perl module compile support script.

\item[/store/etc/internal/etc/pm-a-by-a]

        Mapping mellom store-arkitektur og Perl5 arkitekturnavn

\end{itemize}

\subsection{buildinfo variables}

\section*{References}

Store documentation, http://www.pvv.org/\~{}arnej/store/storedoc.html

Automatisk kompilering av Store-programmer på alle plattformer

==============================================================

Petter Reinholdtsen <pere@td.org.uit.no>, 1999-07-27

IT-avdelingen bruker et system kalt 'build-all' hentet fra NTNU for
dette.  Når det virker går kompilering mye raskere enn før.  Når det
ikke virker gjøres kompilering som før.  Kopi av NTNUs buildinfo filer
ligger i store-applikasjon build-all/ntnu-buildinfo/

For å autokompilere for flere arkitekturer lager du et /bin/sh script
'buildinfo' i applikasjonskatalogen på master, parallelt med fila
'registration', for å sette endel variabler.  Deretter kjører du
'build-all'.  Hvis alt gikk bra, har du etter en stund kompilert opp
applikasjonen for alle plattformer.  Sjekk out.* for å se hvordan det
går med bygging av applikasjonen.

Når kompileringen er ferdig på alle plattformer (siste linje i out.*
er "...done"), så kjøres chkapp og register på vanlig måte.

Eksempelfil for GNU configure programmer:

  appname=zsh
  version=3.1.5
  buildtype=GNU

Eksempelfil for Perl5 moduler:

  appname=Net-Netmask.pm
  version=1.6
  buildtype=pm

Følgende variabler kan settes:

  appname
        Navn på applikasjonen som skal genereres, dvs katalognavnet i
        Master Store.  Må settes, ingen default. 
  version
        Versjon på applikasjonen som skal genereres.  Må settes, ingen
        default. 
  buildtype
        Hvordan kompilering av applikasjonen skal gjøres.  Må settes,
        ingen default.  Følgende er støttet:

                X       xmkmf og make
                GNU     GNU Autoconf oppsett
                pm      Perl5 module, dvs applikasjon med 'Makefile.PL'
                make    ???.  Forutsetter at konfigurering allerede er gjort.

  prefix
        Kan være blank.  Default er '/store'.
  confstring
        Kan være blank.  Parameter til configure for buildtype GNU.
        Default er '--prefix=\$prefix'.
  confcmd
        Kan være blank, da brukes confstring eller standard for buildtype 
        GNU ('./configure \$confstring').
  maketargets
        Kan være blank.  Parameter til make.  Default er intet
        parameter.
  installtargets
        Kan være blank.  Parameter til make for a installere
        applikasjonen.  Default for X er 'install install.man', for
        alle andre 'install'
  linkdownfirst
  linkupafter
        Kan være blank.  Liste over applikasjoner som linkes henholdsvis
        ned og opp fra linktreet før og etter installasjon.
        Space-separert liste.
  postpostinstcmds
        Kan være blank.  Kommando som kjøres etter postinst på
        maskinen er installasjonen ble gjennomført.
  linkupthis
        Liste over applikasjoner som skal linkes opp før kompilering.
        Formatet er 'app versjon store', og flere applikasjoner skilles
        med skråstrek(/).  Eksempel:
                linkupthis='glib 1.2.2/gtk 1.2.2'
  rsh
        Kan være blank.  Hvilken kommando som brukes for å kjøre
        kommandoer på andre maskiner.  Default er 'ssh -x'.
  nice
        Kan være blank.  Nive-nivå for 'configure'- og
        'make'-kommendoene.  Default er 'nice -15'
  timeout
        Kan være blank.  Timeout-verdi for postinst.  Default er 25.

Tilgjengelige shell-variabler i confcmd og postpostinstcmds:

  SARCH Store-arkitektur
  PMA   Perl5 arkitekturnavn (for pm buildtype)

Buildall-systemet består av følgende filer:

  /store/bin/build-all
        Oppstart-scriptet som kjøres fra master-dir for applikasjonen
  /store/etc/internal/buildsubs
        Skriptet som gjør jobben
  /store/etc/internal/etc/pm-a-by-a
        Mapping mellom store-arkitektur og Perl5 arkitekturnavn
  \$HOME/etc/buildhosts
        Liste over hvilke maskiner de forskjellige arkitekturene
        kompileres på.
  \$HOME/etc/master.conf
        Informasjon om master-store.
  \$appdir/buildinfo
        Informasjon om applikasjonen som skal kompileres

\end{document}
