\documentclass{article}
\ExecuteOptions{dvips,color}
\usepackage{fullpage}
\usepackage{color, xspace}
\IfFileExists{hyperref.sty}{\usepackage{hyperref}}{}
%
\newcommand{\XXX}[1]{\textbf{XXX} #1}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\file}[1]{\texttt{#1}}
\newcommand{\eups}{\code{ExtUPS}\xspace}
\newcommand{\pacman}{\code{pacman}}
\newcommand{\rarrow}{$\Rightarrow$}
\newcommand{\darrow}{$\Downarrow$}
%
% Redefine verbatim to integrate better into running text
%
\usepackage{verbatim}
\let\overbatim=\verbatim
\let\oendverbatim=\endverbatim
\renewenvironment{verbatim}
{\center\minipage{16cm}\overbatim}
{\oendverbatim\endminipage\endcenter}

%=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

\begin{document}
\title{\eups --- a Tool to Manage Software Dependencies}
\author{Nikhil Padmanabhan, Robert Lupton, and Craig Loomis}

\maketitle

\tableofcontents
\newpage

%=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

\section{Introduction}

Complex software systems are generally built from a hierarchy of
components, and in general all of these systems are in a state of
flux.  In order to bring order out of chaos, we need to be able to:
\begin{itemize}
  \item Organize the set of components, allowing for their natural
    hierarchy.

  \item
    Select which versions of components should be used, ensuring
    that a consistent set are chosen

  \item
    Configure the environment (\code{PATH}; environment variables)
    for each component.

  \item
    Provide a way to identify a chosen set of components

  \item
    In addition, we would like to be able to install libraries that support
    these versions, and to do so on a number of different platforms.
\end{itemize}

We assume that the task of actually managing individual components
(e.g. tracking code versions) is being handled with some other system,
such as \code{svn} or \code{git}.

See Appendix \ref{AppInstalling} if you want to know how to install your own copy of \eups.

\section{The \code{setup} command}

\eups
\footnote{%
  The name comes from \code{UPS} (\code{Unix Product Support}), a
  tool written at Fermi National Accelerator Laboratory, FNAL. \eups (pronounced ``E-ups'',
  or just ``ups'', or sometimes even ``eeups'' as a single word)
  was basically a reimplementation first in perl and now python of those parts of \code{UPS}
  that we have found especially valuable;  we have now made extensive extensions.}
achieves all of these goals. A component (refered to as a `product')
may be used after it has been \code{setup}, and these products may
in turn setup other products. When setting up a product, a user
may specify a version, or accept the current default. These setup versions
may either be in a user's file space (probably a `live' version checked out from a source code manager),
or copies that have been \code{declare}d to the system; these declarations are
aware of the user's computer architecture (referred to as a `flavor').

The organisation is via `table' files
associated with each component, for example the table file
for a product named \code{photo} reads:
\begin{verbatim}
       setupRequired("astrotools")
       envSet(PHOTO_STARTUP, ${PRODUCT_DIR}/etc/photoStartup.tcl)
       envAppend(PATH, ${PRODUCT_DIR}/bin)
\end{verbatim}

When we attempt to \code{setup} the product \code{photo}, this
table file leads to the following actions:
\begin{description}
\item
  The environment variable \code{PHOTO\_DIR} is automatically set to
  the root of the directory tree for product \code{photo} (how this
  is determined is described in the next section)
\item
  \code{setupRequired} states that when you \code{setup} this product, you
  should also \code{setup} a product called \code{astrotools}.
  The table file for \code{astrotools} can
  (and in fact does) itself \code{setup} further products.  We say that
  \code{photo} \emph{depends} on \code{astrotools}.
\item
  \code{envSet} sets an extra environment variable; here \code{\$\{PRODUCT\_DIR\}}
  refers to the root of this product's tree (i.e. to \code{PHOTO\_DIR} as set above)
\item
  \code{envAppend} appends
  the directory \code{\$\{PRODUCT\_DIR\}/bin} to the current path (there
  is also a \code{envPrepend} directive).
\end{description}

So far we have achieved the first of the goals listed in the introduction,
describing a hierarchy.   The next section describes how to maintain
multiple versions of products.

\section{Declaring Products and Versions}

Whence came \code{PHOTO\_DIR} in the example? From a command of the form
\footnote{Actually, a simple \code{eups declare photo v5\_4\_25} would suffice}
\begin{verbatim}
eups declare photo v5_4_25 -f Darwin -r /u/products/Darwin/photo/v5_4_25
\end{verbatim}

This command updates the \eups `database' (in reality a set of files);
this `database' is then `queried' by the \code{setup} command. In
the \code{declare} command,
\begin{itemize}
  \item
    \code{photo} is the name of the product

  \item
    \code{v5\_4\_25} specifies the version number (by convention this
    is a tag provided by your source code manager (\textit{e.g.} \code{svn} or \code{git}))

  \item
    \code{-f Darwin} specifies the flavor (i.e. my computer's hardware and
    operating system).  You should almost always omit an explicit flavor declaration;
    it's not needed and you can get it wrong.

  \item
    \code{-r /u/products/Darwin/photo/v5\_4\_25} is the directory where
    the specified version can be found. The name is purely conventional,
    but the convention is pretty transparent.

    This directory is typically created by an \code{install} target
    in a Makefile, but it could simply be your current working
    copy: \footnote{It's probably better to use a tag (Sec. \ref{tags}) here: \code{eups declare -t rhl -r .}}
    \vspace{-7mm}
\begin{verbatim}
       eups declare photo cvs -r ~/photo
\end{verbatim}
\end{itemize}

If I now say \code{setup photo v5\_4\_25}, \eups will look for
a table file in the directory\hfil\break \code{/u/products/Darwin/photo/v5\_4\_25/ups},
and obey whatever instructions it finds there.  For example,
I will find that
\code{PHOTO\_DIR} is set to \code{/u/products/Darwin/photo/v5\_4\_25}. If,
in the \code{declare} command I'd also specified \code{-c} (for
`current'), then version \code{v5\_4\_25} of \code{photo} would
have become the default, and I could have simply said \code{setup photo}.

You will remember that \code{photo}'s table file simply requested
that \code{astrotools} be setup, but it could have specified a version:
\begin{verbatim}
setupRequired("astrotools v4_10_1")
\end{verbatim}
The table file being used is the one in the \emph{installed} directory,
and the \code{make install} command was free (and indeed encouraged) to
rewrite the table file to specify explicit version numbers using the \code{eups expandtable} command.

We have now achieved all of our five goals (although we have not
yet described how to make use of our success): I have defined
a version \code{v5\_4\_25} of a product \code{photo}, which is
to be found in a given directory for a given architecture,
and specified how its environment should be configured. Furthermore,
this version depends on a specific version (\code{v4\_10\_1}) of
\code{astrotools}, and so on. By convention, each of these version
numbers corresponds to a tag in some source code repository, so I am
able to recover the complete set of releases used to build and
run this version of \code{photo} by examining the \eups database.

\section{The \code{setup} command continued}

\subsection{How \eups decides which version of a package to setup}
\label{SetupVersionChoice}

We rather blithely described how \eups chooses a version with the phrase,
``When setting up a product, a user may specify a version, or accept the current default''.  Unfortunately,
it isn't always quite so simple.

Consider a simple ``dependency tree'' of products such as:
\setlength{\unitlength}{1mm}
\begin{center}
\begin{picture}(100,10)
\thinlines
\put(10,0){\framebox(20,10){A 1.2}}
\put(30,5){\vector(1,0){10}}
\put(40,0){\framebox(20,10){B 2.2}}
\put(60,5){\vector(1,0){10}}
\put(70,0){\framebox(20,10){C 1.3}}
\end{picture}
\end{center}
i.e. version 1.2 of product A sets up version 2.2 of B which sets up version 1.3 of C.  This chain is
defined by the product's table files; i.e.. A 1.2's table looks something like:
\begin{verbatim}
setupRequired(B 2.2)
\end{verbatim}
and B 2.2's table:
\begin{verbatim}
setupRequired(C 1.3)
\end{verbatim}

When we say \code{setup A 1.2} setup's task is simple;  it looks up A's table file and finds
\code{setupRequired(B 2.2)}; so it sets up B 2.2 finding \code{setupRequired(C 1.3)}, so it
  sets up C 1.3 and that's it (as C has no dependencies).

\eups can also handle \code{setup A} (i.e. no explicit version).  In this case it looks for the version of
A that has been tagged `current'; if A 1.2 is current, then \code{setup A} has the same result as
\code{setup A 1.2}.
\footnote{You can actually
  change this behaviour to make any tag the default by changing the VRO; see Sec. \ref{VRO}}

Unfortunately even specifying explicit versions of dependent products doesn't completely define which
products should be setup.

Consider
\begin{center}
\begin{picture}(100,25)
\thinlines
\put(10,0){\framebox(20,10){D 2.0}}
\put(30,5){\vector(1,0){10}}
\put(40,0){\framebox(20,10){C 2.0}}

\put(10,15){\framebox(20,10){A 1.2}}
\put(30,20){\vector(1,0){10}}
\put(40,15){\framebox(20,10){B 2.2}}
\put(60,20){\vector(1,0){10}}
\put(70,15){\framebox(20,10){C 1.3}}
\end{picture}
\end{center}

\newcommand{\DiamondDependencyFigure}{
\begin{center}
\begin{picture}(100,22.5)
\thinlines
\put(10,7.5){\framebox(20,10){A 1.2}}
\put(30,12.5){\vector(1,0){10}}
\put(40,7.5){\framebox(20,10){B 2.2}}
\put(60,12.5){\vector(3,2){10}}
\put(60,12.5){\vector(3,-2){10}}
\put(70,12.5){\framebox(20,10){\color{blue}C 1.3}}

\put(70,0){\framebox(20,10){D 2.0}}
\put(90,5){\vector(1,0){10}}
\put(100,0){\framebox(20,10){\color{blue}C 2.0}}
\end{picture}
\end{center}
}

If we change B 2.2's table file to read
\begin{verbatim}
setupRequired(C 1.3)
setupRequired(D 2.0)
\end{verbatim}
i.e. if we add a dependency on D version 2.0 to B version 2.2, we have:
\DiamondDependencyFigure
Note that there are two separate requests for C;
this is referred to as a ``diamond dependency'' by analogy to multiple inheritance in OO languages.
\eups is unable to handle this without help.  One solution is that \code{eups expandtable} writes the
complete set of setup products into the table file (see Sec. \ref{expandtable} for details) and when
you specify an exact version or use the \code{--exact} flag this set of
versions is used. For example, if C 1.3 was setup when you installed and declared A 1.2, then the command
\code{setup A 1.2} would result in A 1.2, B 2.2, D 2.0, and C 1.3 being setup.

Another possibility is to always accept the latest version of a product; this is
supported but has proved to be fragile as it turns out to be hard to define an absolute order for versions.

Another way to get exactly your desired mix-n-match of versions is to use tags; tagging your favourite
version of C preempts any other choice (see Sec. \ref{tags}).

There are a couple of other \code{setup} options that can be used to control dependencies.  One is
\code{--just} which is equivalent to \code{--max-depth 0}; that is, don't setup any dependencies (so
\code{setup --just A 1.2} wouldn't setup B, whereas
\code{setup --max-depth 1 A 1.2} would setup B but not C or D.

Another is \code{--keep} which means that any products that you've already setup are preserved; e.g.
after \code{setup C 1.0; setup --keep A 1.2} would
result in A 1.2, B 2.2, D 2.0, and C 1.0 being setup.

\subsection{The VRO}
\label{VRO}

When looking for a version of a product, \code{setup} searches a list known as the VRO (the \code{V}ersion
\code{R}esolution \code{O}rder) looking for a valid recipe to find a version; you can see the current vro with
\code{eups vro}.  Some entries on the VRO are directives (e.g.  \code{keep}), while others tell \eups how to
look for a product (e.g. \code{version}).

For example, a VRO of \code{version current} means that when looking for a product, \eups should
first try to an explicit version specification, and only then a version with tag \code{current} (it
is a VRO like this that makes \code{current} be the default version).  That is,
if foo 6.6.6 is current and we see a table file such as
\begin{verbatim}
setupRequired(foo 1.2.3)
\end{verbatim}
a VRO of \code{version current} would use  \code{version} to setup foo 1.2.3.
If the VRO had been \code{current version} then foo 6.6.6 would have been setup instead.

As the VRO is processed, entries are interpreted as follows:
\begin{description}
\item[current]
   Use a version tagged \code{current}
\item[commandLineVersion]
   Use the version explicitly specified on the command line
\item[keep]
   If a version of the product is already setup, accept it as the new version
\item[latest]
   Use the most recent version [not well tested; caveat usor]
\item[path]
   Use the version specified by an explicit path on the command line (i.e. \code{-r ...})
\item[\textit{tagname}]
   Use the version with a specific tag (see Sec. \ref{tags})
\item[type:\textit{typename}]
   Set the build type, exactly as if you'd said \code{--type \textit{typename}}.  This directive is seen
   when this element of the VRO is processed, so you probably want to put it first.  Its major use is to
   set \code{type:exact};  this is the the mechanism used to make commands like \code{setup foo 1.2}
   behave as if you'd typed \code{setup --exact foo 1.2}.
\item[version]
   Use a version of the product specified explicitly (e.g. \code{1.2.3})
\item[versionExpr]
   Use a version that satisfies an expression (e.g. \code{>= 1.2.3})
   (explicit versions are allowed too, and imply equality)
\item[warn]
   Print a warning message if the version resolution reaches this point in the VRO without finding a version.
   You can add a verbosity level (e.g. \code{warn:2}) to specify the minimum verbosity to print the message.
\end{description}

The VRO can be set by the \code{--vro} option, or (more commonly) by setting \code{hooks.config.Eups.VRO}
in a startup file (Sec. \ref{customization}).  \code{hooks.config.Eups.VRO} is a dictionary with
keys that specify the VRO to use with a commandLineVersion, with a tag (e.g. \code{rhl}) or a default value (key \code{"default"});
the default can itself be a dictionary with keys corresponding to elements of the \code{\$EUPS\_PATH} (cf. the
\code{-z} option).  The \code{eups vro} command can be used to show what VRO would be used (e.g. \code{eups vro -tag rhl afw 1.2})

\subsection{Tags}
\label{tags}

It's possible to associate a name with a set of versions; tags are specified as \code{-t XXX} or
\code{--tag XXX}.  After tagging a variety of products as \code{rhl}, I can say \code{setup -t rhl photo}
to get a version of the product \code{photo} setup
using dependencies that I've honoured with the tag \code{rhl}; other products are found on the VRO as usual.

Tags may be set with a command such as \code{eups declare -t rhl afw 1.2.3} or
\code{eups declare -t rhl -r .}\footnote{yes; no version name is required as the tagname suffices to
  identify the product's version.}
There are two sorts of tags; user tags are only available to
you, while global tags are visible to all users of your \eups database.\footnote{You are permitted to use
  other people's user tags if you can read their \file{\~{}/.eups} directory; e.g. to use my beta tag put
  \code{hooks.config.Eups.userTags += [("beta", "rhl")]} into \textit{your} \file{\~{}/.eups/startup.py} file}
Additionally, tags may be labelled as `reserved' which means that you're not supposed to meddle with them;
they are designed for centrally-assigned tags such as `pre-release' or `golden'.

Tags must be declared before use (to avoid
typos such as \code{-t rkl} when you obviously meant \code{-t rhl}).
This is done in one of the startup files (see Sec.
\ref{customization}), typically \code{\$HOME/.eups/startup.py} with code such as
\begin{verbatim}
hooks.config.Eups.globalTags += ["test"]
hooks.config.Eups.userTags += ["t1570"]
\end{verbatim}
This declares tags \code{test} and \code{t1570}.  In addition, your username (in my case \code{rhl}) is
automatically defined as a valid user tag.

You can list all known tags with \code{eups tags}; user tags are prefixed \code{user:}.  For example,
\begin{verbatim}
$ eups tags
current latest stable user:rhl
\end{verbatim}

When using a tag, the tag is automatically inserted near the front of the VRO;
\begin{verbatim}
$ eups vro
path versionExpr warn current
$ eups vro -t rhl
path rhl versionExpr warn current
\end{verbatim}
In other words, your tagged products take priority over any other version specification (except an explicit
path).  If you'd rather give priority to version expressions over your tags, specify them with \code{-T} or
\code{--postTag}:
\begin{verbatim}
$ eups vro -T rhl
path versionExpr rhl warn current
\end{verbatim}
If you need even more complete control, use the \code{--vro} command.

Post-tags are useful when you want exact products, but you don't want to have to search your email for
the name of currently-blessed version, e.g. \code{afw 6.1.3.1}.  You might think of tagging it with
\code{rhl}: \code{eups declare -t rhl afw 6.1.3.1; setup -t rhl afw} and that would work until you
tagged some dependent product \code{rhl} --- at that point you'd get both of your tagged products.  The
solution is to make the tag only apply if no version is known, in other words put the tag \textit{after}
\code{version} in the \code{vro}.  And this is exactly what \code{-T rhl} does.

As an alternative declaring a version with a known tagname, the `tagname' in \code{-t \textit{tagname}} may be a file
consisting of pairs \code{product version ...} such as that produced with the
\code{eups list --setup} command
\footnote{You may also say \code{file:XXX} to explicitly specify that \code{XXX} should
  be interpreted as a file, not a tagname}

For example, to share a setup with a colleague I could say:
\begin{verbatim}
$ eups list --setup > mysetups.txt
$ emacs mysetups.txt       # remove products I don't care about
$ setup -t mysetups.txt afw
\end{verbatim}
and then tell her to repeat that last line.  If she wants to use some of her bug-fixed versions in conjunction
with my versions, she'd say \code{setup -t lynda -t mysetups.txt afw} which is why this approach is often
better than just sourcing a set of \code{setup -j XXX} lines.

\subsubsection{Specifying default Tags}
\label{defaultTags}

If you don't specify any tags to the \code{setup} (or \code{eups vro}) command (with either \code{--tag} (\code{-t}) or \code{--postTag} (\code{-T})) then
\code{hooks.config.Eups.defaultTags} is consulted.  It's a dictionary with keys \code{pre} and \code{post};
e.g. if you have
\begin{verbatim}
hooks.config.Eups.defaultTags["pre"] += ["rhl", "HSC"]
hooks.config.Eups.defaultTags["post"] += ["v6_1"]
\end{verbatim}
in \file{startup.py}, then \code{setup foo} is exactly equivalent to \code{setup -t rhl,HSC -T v6\_1}.
You can disable this default tag processing with \code{--tag None} (or \code{--tag ""}).

\section{How do I Actually Use this System to Manage Code?}

All that the \code{setup} command did was to set or append to a number of environment variables,
such as \code{PHOTO\_DIR}, \code{ASTROTOOLS\_DIR}, and (often) \code{LD\_LIBRARY\_PATH}.
These can be used in Makefiles, e.g.
\begin{verbatim}
CFLAGS = -g $(INCS)
INCS = -I$(ASTROTOOLS_DIR)/include \
       -I$(PHOTO_DIR)/include \
       ...
LIBS =   -L$(ASTROTOOLS_DIR)/lib -lastrom \
         -L$(PHOTO_DIR)/lib -lphoto -lmeasureObj \
         ...
\end{verbatim}
				% $ for emacs

App. \ref{autoconf} discusses a strategy for managing include files
and libraries using configure and make; but the gnu build tools are
complicated and (some would say) confusing and clunky, so you may
not want to learn them.  One option is to add some more magic
to the Makefile (see the next section);  another is to give up
entirely on make and use some more sophisticated build tool.  The
one that we have experience with is \code{scons}, and a complete
integration of \eups with scons is described in section \code{scons}.

\subsection{\eups and make}

This is all very well, and perfectly practical, but it doesn't
integrate very closely with \eups; in particular it doesn't
help you much with installing in Proper Places. If you are
using GNU's version of make (and you probably are), you can handle
this by a set of rules looking something like:
\begin{verbatim}
PRODUCT = test
EUPS_ROOT = $(shell eups path -1)
VERSION = $(shell ./eups_product_version)
FLAVOR = $(shell eups flavor)

ifeq (, $(prefix))
   prefix = $(EUPS_ROOT)/$(FLAVOR)/$(PRODUCT)/$(VERSION)
endif

install :
        install -m 775 bin/foo $(prefix)/bin
        eups expandtable ups/$(PRODUCT).table $(prefix)/ups

declare :
        eups declare -r $(prefix) $(PRODUCT) $(VERSION)

current : declare
        eups declare $(PRODUCT) $(VERSION) --current --force
\end{verbatim}
				% $ for emacs

\code{EUPS\_ROOT} is taken to be the last element in \code{EUPS\_PATH} (that's
the \code{-1} in \code{eups path -1}),
and the \code{ifeq} bit allows me to say \code{make install declare version=/usr/local}.

The script \code{eups\_product\_version} (and this Makefile) are to be found
in the \eups \code{etc} directory, although they are not installed along
with \eups.

The script \code{eups\_product\_version} is rather like:
\begin{verbatim}
#!/usr/bin/env python
import eups

print eups.version('$Name: $')
\end{verbatim}
where the \code{\$Name:  \$} is a magic cvs keyword that expands to your
current tagname, so you need to put a copy of the script in your own
package, so as to get \emph{your} tagname.

If you use svn, things are a bit harder as svn provides no real
equivalent to a tagname. Simpilar functionality can be achieved using \code{\$HeadURL\$}
and requiring that all tags be in a directory \code{tags}
or \code{TAGS} within the svn repository.\footnote{
  and saying \code{svn propset svn:keywords HeadURL}}
The real \code{eups\_product\_version} attempts to correctly handle \code{cvs}, \code{svn},
\code{hg} and \code{git} users.

\subsection{\eups and scons}
\label{scons}

Write me.

\appendix

\section{Using \eups with python}

\eups is written in python, so you can use it in scripts by simply importing it.

To use \eups from python, you need to \code{import eups};
The functions in \code{eups.app} define the supported API:
\begin{description}
  \item[clearCache]
        remove the product cache for given stacks/databases and flavors

  \item[declare]
        Declare a product.  That is, make this product known to EUPS.

  \item[expandBuildFile]
        expand the template variables in a .build script to produce an
        explicitly executable shell scripts.

  \item[expandTableFile]
        expand the version specifications in a table file.  When a version in
        the original table file is expressed as an expression, the expression is
        enclosed in brackets and the actual product version used to build the
        table file's product is added.

  \item[getDependencies]
        Return a list of productName's dependent products

  \item[getDependentProducts]
        Return a list of Product topProduct's dependent products

  \item[getSetupVersion]
        return the version name for the currently setup version of a given product.

  \item[listCache]
        List the contents of the cache

  \item[printProducts]
        print out a listing of products.  Returned is the number of products listed.

  \item[printUses]
        print a listing of products that make use of a given product.

  \item[productDir]
        return the installation directory (PRODUCT\_DIR) for the specified product

  \item[setup]
        Return a set of shell commands which, when sourced, will setup a product.

  \item[undeclare]
        Undeclare a product.  That is, remove knowledge of this
        product from EUPS.  This method can also be used to just
        remove a tag from a product without fully undeclaring it.

  \item[unsetup]
        Return a set of shell commands which, when sourced, will unsetup a product.
\end{description}

\section{\eups Reference Manual}

\subsection{\eups concepts and jargon}

\begin{description}
\item[current]
  The special \textit{tag} used to indicate the default version of a \textit{product}.
\item[dependency]
  A \textit{product} B is a dependency of A if B needs to be setup as part of setting up A.
\item[flavor]
  The computer architecture for which your \textit{product}s are valid.  This is often more-or-less
  a summary of your \code{uname}; examples are \code{DarwinX86}, \code{Linux}, \code{Linux64}.
\item[product]
  A logical unit that you would like to version using \eups
\item[root]
  The directory associated with a \textit{product} (if any).  For the common case of
  a \textit{product} containing source code the root would usually contain include and library subdirectories,
  although this is not required.
\item[tag]
  A name attached to a set of one or more \textit{products}, which can be used to override the version
  that would otherwise be selected.  Note that this use of the word \textit{tag} is unrelated to its use
  in source code managers such as \code{svn} or \code{hg}.
\item[table]
  A \textit{product}'s \textit{table file} lists the actions that \eups
  needs to carry out when setting up the \textit{product}.
\item[version]
  A string specifying which version of a \textit{product} is being used.  Conventionally these correspond to names
  generated from your source code manager (e.g. \code{svn}), but this is not required.
\item[VRO]
  The \code{V}ersion \code{R}esolution \code{O}rder;  the order in which possible versions of
  a \textit{product} are considered.
\end{description}

\subsection{How to customize \eups}
\label{customization}
You can customize \eups's behaviour in two ways:
\begin{itemize}
\item By setting an environment variable \code{\$EUPS\_STARTUP} which points to a python script
\item By putting a \file{startup.py} in the directory given by the  environment variable
  \code{\$EUPS\_USERDATA} (or \file{\$HOME/.eups} if \code{EUPS\_USERDATA} isn't set).
  In fact \eups searches a number of place in order (see below).
\end{itemize}

You can list your startup files with \code{eups startup}; with \code{-v} files that would be consulted if they
are existed are also listed.  \footnote{Once upon a time there were two sorts of startup file: \file{startup.py} and \file{config.properties}.  The latter are currently disabled in \file{hooks.py}}

For example if \code{\$EUPS\_STARTUP=\$HOME/Python/foo.py} and \code{\$EUPS\_PATH=/u/lsst/products:/u/lsst/coreProducts}, then \code{eups -v startup} reports
\begin{verbatim}
/u/lsst/products/eups/site/startup.py
/u/lsst/products/site/startup.py
[/u/lsst/coreProducts/site/startup.py]
/Users/rhl/.eups/startup.py
/Users/rhl/Python/foo.py
\end{verbatim}
These files are processed in the order listed (i.e. \code{\$EUPS\_STARTUP} last)

\subsubsection{Contents of startup files}
\label{secStartupFiles}

\begin{description}
  \item[Hook commands]
    There are a number of variables that can be set using syntax such as\hfil\break
    \code{hooks.config.Eups.reservedTags += ["stable"]}

    \item[userTags]
      Permitted user tags.  See Sec. \ref{tags}.
    \item[preferredTags]
      XXX
    \item[defaultTags]
      A dict indexed by \code{pre} and \code{post}.  See Sec. \ref{defaultTags}.
    \item[globalTags]
      Defined global tags.  See Sec. \ref{tags}.
    \item[reservedTags]
    \item[verbose]
    \item[asAdmin]
    \item[setupTypes]
      Permitted arguments to \code{setup --type=XXX}, \textit{e.g.}
      \code{hooks.config.Eups.setupTypes.append("sdss")}
    \item[setupCmdName]
    \item[VRO]
    \item[fallbackFlavors]
\end{description}

For example, I have
\begin{verbatim}

hooks.config.Eups.globalTags += ["test"]
hooks.config.Eups.userTags += ["t1570"]
hooks.config.Eups.reservedTags += ["stable"]
hooks.config.Eups.VRO["default"]["dss"] = "type:exact path version current"
\end{verbatim}

\subsubsection{Callback functions}
\label{commandCallbacks}

You can also register callback functions which are called twice; one just before the main initialisation (the
one that creates the \code{Eups} object) and once just before \eups settles down to work.

The arguments to the callbacks are:
\begin{description}
  \item \code{Eups}
    An instance of the class \code{Eups} (or \code{None} the first time the callback is called, before
    the \code{Eups} object has been created)

  \item \code{cmd}
    The command being executed (e.g. \code{setup} or \code{list})

  \item \code{opts}
    The options being passed to the command

  \item \code{args}
    The arguments being passed to the command
\end{description}

For example, you could put something like this in a \file{startup.py} file:
\begin{verbatim}
import eups

def cmdHook(Eups, cmd, opts, args):
    import eups

    if not Eups:
        if cmd in ("setup", "unsetup"):
            eups.enableLocking(False)
        return

    if Eups and cmd == "setup":
        if not opts.tag:              # see also config.Eups.defaultTags
            opts.tag = ["rhl", "Winter2012c", "beta"]

            if opts.verbose >= 0:
                import utils
                print >> utils.stdinfo, "Adding default tags: %s" % (", ".join(opts.tag))
eups.commandCallbacks.add(cmdHook)
\end{verbatim}

(Since this was written a configuration option, \code{hooks.config.Eups.defaultTags}, was added
to support default tags without writing a callback.)

\subsubsection{Colour}
\label{color}

It is possible to get \eups to colour its error, warning, and informational messages if your
terminal co-operates.  By default color is turned off; to enable it put a line
\begin{verbatim}
hooks.config.Eups.colorize = True
\end{verbatim}
in your startup file.  If you don't like our choice of colours, you can instead say \textit{e.g.}:
\begin{verbatim}
hooks.config.Eups.colorize = dict(ERROR = "red", WARN = "blue", INFO = "cyan")
\end{verbatim}
Available colours are \code{black}, \code{red}, \code{green}, \code{yellow}, \code{blue}, \code{magenta},
\code{cyan}, and \code{white}.  Additionally, you may add \code{;bold} (\textit{e.g.} \code{red;bold}).

Colour is only used if your \code{stderr} is going to a terminal.

%------------------------------------------------------------------------------

\subsection{\eups commands}

\subsubsection{\code{eups}}
\begin{verbatim}
Usage:
        eups [--help|--version] command [options]
Supported commands are:
        admin           Administer the eups system
        declare         Declare a product
        distrib         Install a product from a remote distribution,
                        or create such a distribution
        expandbuild     Expand variables in a build file
        expandtable     Insert explicit version tags into a table file
        flags           Show the value of \$EUPS_FLAGS
        flavor          Return the current flavor
        help            Provide help on eups commands
        list            List some or all products
        path [n]        Print the current eups path, or an element thereof
        pkgroot [n]     Print the current eups pkgroot, or an element thereof
        pkg-config      Return the options associated with product
        remove          Remove an eups product from the system
        tags            List information about supported and known tags
        undeclare       Undeclare a product
        uses            List everything which depends on the specified product
                        and version
        vro             Show the Version Resolution Order that would be used

Use
        eups --help cmd
for help with command "cmd"
\end{verbatim}
				% $ for emacs

A consistent front-end to all the other \eups commands.

There's no \code{eups setup} or \code{eups unsetup} as these actions
modify your environment and are in fact aliases for commands
that source files of \code{export ...} (or \code{setenv ...}) lines
into your current shell.

All \code{eups} commands support a common set of options:

\begin{verbatim}
       --debug      arg    Permitted Values: raise
   -f, --flavor     arg    Use this flavor. Default: $EUPS_FLAVOR or `eups flavor`
   -F, --force             Force requested behaviour
   -h, --help              Print this help message
   -n, --noaction          Don't actually do anything
   -z, --select-db  arg    Select the product paths which contain this directory.
                           Default: all
   -Z, --database   arg    Use this products path. Default: $EUPS_PATH
                           Alias: --with-eups
   -v, --verbose           Be chattier (repeat for even more chat)
   -V, --version           Print eups version number and exit
   --vro=LIST              Set the Version Resolution Order
\end{verbatim}

The flavor is usually determined by the command \code{\$EUPS\_DIR/bin/eups flavor}, but may be set using the
environment variable \code{\$EUPS\_FLAVOR}, or \code{--flavor} (in order from lowest to highest precedence).

The desired database can also be specified explicitly with the \code{-Z} option (which overrides
\code{EUPS\_PATH}), or by using \code{-z} to specify a path component; e.g.  \code{-Z
  /home/proj1/eups:/home/proj2/eups -z proj2} would select \code{/home/proj2/eups}.

\subsubsection{\code{eups admin}}
\begin{verbatim}
Usage:
    eups admin [options] [buildCache|clearCache|listCache|clearLocks|clearServerCache|info|show]

Options:
   -r, --root       arg    Location of manifests/buildfiles/tarballs (may be a URL or scp specification).
                           Default: $EUPS_PKGROOT
\end{verbatim}

There are a number of subcommands:
\begin{itemize}
  \item{\code{buildCache|clearCache|listCache}}
    Manipulate \eups's caches

  \item{\code{clearServerCache}}
    Clear the \code{eups distrib} cache

  \item{\code{clearLocks}}
    Clear \eups locks

  \item{\code{info product [--tag XXX] [version]}}
    Provide information about a product, specifically the location of the file that \eups (currently)
    uses to define a product/version/tag.

  \item{\code{show}}
    Show the value of something of interest to \eups.
\end{itemize}

\subsubsection{\code{eups declare}}
\label{eups declare}
\begin{verbatim}
Usage:
   eups [commonOptions] declare [options] [product [version]]
Options:
   -c, --current           Declare product current
   -L, --import-file arg   Import a file directly into the database
   -M               arg    Import the given table file directly into the database
                           (may be "-" for stdin)
   -m, --table      arg    Use table file (may be "none") Default: product.table
   -r, --root       arg    Location of product being declared
   -t, --tag        arg    Install versions with this tag (e.g. current or stable)
\end{verbatim}

Declares \code{version} of \code{product} to \eups.

The \code{eups declare} command has to decide which database in the environment
variable \code{EUPS\_PATH}
to use.  If the product's already declared, use the database it's in (this is usually
only relevant when you're declaring a product current).  Otherwise, if the specified root
lies within a database in \code{EUPS\_PATH}, use that database; as a last resort use
the database that's listed first in \code{EUPS\_PATH}.

You can use \code{-L fileName} to tell \eups to save you a copy of \code{fileName} in the
`extra product directory'
(usually because you are declaring a product that you don't have write permission for).
When you setup a product that was declared
this way, an extra environment variable \code{PRODUCT\_DIR\_EXTRA} is set to point to this directory;
it's also available as \code{\$\{PRODUCT\_DIR\_EXTRA\}} in table files.

The argument to \code{-L} is in fact a bit more flexible:\hfil\break
\hspace*{0.5cm}\hbox to 3.3cm{\code{fileName}\hfil}
Save \code{fileName} as \code{\$PRODUCT\_DIR\_EXTRA/fileName}\hfil\break
\hspace*{0.5cm}\hbox to 3.3cm{\code{fileName:outName}\hfil}
Save \code{fileName} as \code{\$PRODUCT\_DIR\_EXTRA/outName}\hfil\break
\hspace*{0.5cm}\hbox to 3.3cm{\code{fileName:dirName/}\hfil}
Save \code{fileName} as \code{\$PRODUCT\_DIR\_EXTRA/dirName/fileName} (note the trailing \code{/})

The \code{-m} option specifies the table
file to be used (either in the database, or in the ups directory of the product).
Your permitted options are actually only \code{product.table} or \code{none}; but see \code{-M}.

The \code{-M} option specifies a file which will be copied into the
database as a table file. This lets you avoid putting EUPS data
into products. You can pipe the table file to \code{eups declare} by
specifying \code{-} as the filename.  The option \code{-M bar} is equivalent to
\code{-L bar:ups/product.table}, \textit{i.e.} the table file may be found in \code{\$FOO\_DIR\_EXTRA/ups}
(you can also find it with \code{eups list -m foo}).

If you omit the \code{-r dir}, \eups will attempt to guess it for you based
on your \code{\$EUPS\_PATH}, flavor, product and version; alternatively,
if you omit both \code{product} and \code{version}, but provide \code{-r dir},
the product and version will be guessed from the last two parts of the directory
name (e.g. \code{-r /home/products/Linux/xpa/v2\_1} will be taken to be
declaring version \code{v2\_1} of product \code{xpa}).  If you only omit
the product, the product will be guessed from the name of the table file
present in the root directory. For example, the following are all equivalent:
\begin{verbatim}
  eups declare -r /u/lsst/products/DarwinX86/foo/1.2.3 foo 1.2.3
  eups declare -r /u/lsst/products/DarwinX86/foo/1.2.3 1.2.3
  eups declare -r /u/lsst/products/DarwinX86/foo/1.2.3
  eups declare foo 1.2.3
\end{verbatim}
(assuming that the file \code{/u/lsst/products/DarwinX86/foo/1.2.3/ups/foo.table}
exists). You may need to specify the version, e.g.
\begin{verbatim}
  eups declare -r /u/rhl/foo
\end{verbatim}
tries to declare version \code{foo} of product \code{rhl}; this will fail as
there is presumably no file \code{/u/rhl/foo/ups/rhl.table}.  You needed to say
\begin{verbatim}
  eups declare -r /u/rhl/foo myVersion
\end{verbatim}

You may specify \code{-r none}, in which case you don't have any files; this
is only permitted if you also specify \code{-M} to provide a table file (or \code{-m none}).
This can be handy if you want an alias; e.g.
\begin{verbatim}
echo "setupRequired(visionWorkbench)" | eups declare -r none -M - vw current
\end{verbatim}
makes \code{vw} an alias for product \code{visionWorkbench}. You can make
an alias for a specific version with e.g.
\begin{verbatim}
setup visionWorkbench 1.0.0
echo "setupRequired(visionWorkbench)" | eups expandtable | \
	eups declare -r none -M - vw 1.0.0
\end{verbatim}

If you want to
know what \code{vw} does, type e.g.
\begin{verbatim}
cat $(eups list vw -m)
\end{verbatim}
				% $ for emacs

If you specify \code{-c} then it leaves the currently declared version alone, and
only updates the current.chain.  If you are declaring the first version of a new
product it's automatically made current.

%------------------------------------------------------------------------------

\subsubsection{\code{eups distrib}}
\begin{verbatim}
Usage: eups distrib [clean|create|declare|install|list|path] [-h|--help] [options] ...

Interact with package distribution servers either as a user installing
packages or as a provider maintaining a server.

An end-user uses the following sub-commands to install packages:
   list      list the available packages from distribution servers
   path      list the distribution servers
   install   download and install a package
   clean     clean up any leftover build files from an install (that failed)
To use these, the user needs write-access to a product stack and database.

A server provider uses:
   create    create a distribution package from an installed product
   declare   declare global tags
To create packages, one must have a write permission to a local server.

Type "eups distrib [subcmd] -h" to get more info on a sub-command.

Common
Options:
  --debug=DEBUG         turn on specified debugging behaviors (allowed: debug,
                        profile, raise)
  -h, --help            show command-line help and exit
  --noCallbacks         Disable all user-defined callbacks
  -n, --noaction        Don't actually do anything (for debugging purposes)
  --nolocks             Disable locking of eups's internal files
  -q, --quiet           Suppress messages to user (overrides -v)
  -T SETUPTYPE, --type=SETUPTYPE
                        the setup type to use (e.g. exact)
  -v, --verbose         Print extra messages about progress (repeat for ever
                        more chat)
  -V, --version         Print eups version number
  --vro=LIST            Set the Version Resolution Order
  -Z PATH, --database=PATH
                        The colon-separated list of product stacks (databases)
                        to use. Default: $EUPS_PATH
  -z DIR, --select-db=DIR
                        Select the product paths which contain this directory.
                        Default: all in path
  --with-eups=PATH      synonym for -Z/--database
  -f FLAVOR, --flavor=FLAVOR
                        Assume this target platform flavor (e.g. 'Linux')
  -F, --force           Force requested behaviour
\end{verbatim}
				% $ for emacs

Handle the distribution of products and their dependencies as `packages'. A
package is a set of tarballs (i.e. gzipped tar archives), a set of build files\footnote{%
  see Appendix \ref{buildFiles}.
} or pacman\footnote{%
  See Appendix \ref{pacman}.
}
caches and
a file (ending in \code{.manifest})
listing a product's dependencies, including the names of the proper tarballs/caches.

Subcommand options are:
\begin{itemize}
\item\code{clean}
\begin{verbatim}
eups distrib clean options product version

Options:
   -n, --noaction          Don't actually do anything
   -R, --remove            Clean and Remove all remnants of a declared product
   -r, --root       arg    Location of manifests/buildfiles/tarballs (may be a URL or scp specification).
                           Default: $EUPS_PKGROOT
   -S, --server-class arg  register this DistribServer class (repeat as needed)
   -t, --tag        arg    Install versions with this tag (e.g. current or stable)
\end{verbatim}

\item\code{create}
\begin{verbatim}
eups distrib create options product [version]

Options:
  -a PACKAGEID, --as=PACKAGEID
                        Create a distribution with this name
  -d DISTRIBTYPENAME, --distribType=DISTRIBTYPENAME
                        Create a distribution with this type name (e.g.
                        'tarball', 'builder')
  -I, --incomplete      Allow a manifest including packages we don't know how
                        to install
  -m MANIFEST, --manifest=MANIFEST
                        Use this manifest file for the requested product
  -j, --nodepend        Just create package for named product, not its
                        dependencies
  -r BASEURL, --repository=BASEURL
                        the base URL for other repositories to consult (repeat
                        as needed).  Default: $EUPS_PKGROOT
  -s DIR, --server-dir=DIR
                        the directory tree to save created packages under
  --flavor=FLAVOR       Assume this target platform flavor (e.g. 'Linux')
  -F, --force           Force requested behaviour
  -D DISTRIBCLASSES, --distrib-class=DISTRIBCLASSES
                        register this Distrib class (repeat as needed)
  -R REBUILDPRODUCTVERSION, --rebuild=REBUILDPRODUCTVERSION
                        Create a new distribution given that product:version's
                        ABI has changed
  --rebuildSuffix=REBUILDSUFFIX
                        Specify suffix to apply to new versions generated by
                        --rebuild
  --server-class=SERVERCLASSES
                        register this DistribServer class (repeat as needed)
  -S SERVEROPTS, --server-option=SERVEROPTS
                        pass a customized option to all repositories (form
                        NAME=VALUE, repeat as needed)
  -e, --exact           Follow the as-installed versions, not the dependencies
                        in the table file
  -f USEFLAVOR, --use-flavor=USEFLAVOR
                        Create an installation specialised to the specified
                        flavor
  -T POSTTAG, --postTag=POSTTAG
                        Put TAG after version(Expr)? in VRO (may be repeated;
  -t TAG, --tag=TAG     Set the VRO based on this tag name
  --debug=DEBUG         turn on specified debugging behaviors (allowed: debug,
                        raise)
  -h, --help            show command-line help and exit
  -n, --noaction        Don't actually do anything (for debugging purposes)
  --nolocks             Disable locking of eups's internal files
  -q, --quiet           Suppress messages to user (overrides -v)
  --type=SETUPTYPE      The setup type to use (e.g. exact)
  -v, --verbose         Print extra messages about progress (repeat for ever
                        more chat)
  -V, --version         Print eups version number
  --vro=LIST            Set the Version Resolution Order
  -Z PATH, --database=PATH
                        The colon-separated list of product stacks (databases)
                        to use. Default: $EUPS_PATH
  -z DIR, --select-db=DIR
                        Select the product paths which contain this directory.
                        Default: all in path
  --with-eups=PATH      synonym for -Z/--database
\end{verbatim}

\item\code{declare}
\begin{verbatim}
Usage: eups distrib declare [-h|--help] [options] [product [version]]

Declare a tag for an available package from the package distribution
repositories.  If no product or version is provided, all defined tags are
defined.

  ...
\end{verbatim}

Declare a tag which \code{eups distrib install} will make use of, e.g.
\begin{verbatim}
eups distrib declare --server-dir=$HOME/packages -t current afw
\end{verbatim}
You can disable the installation of the tag with \code{eups distrib install --no-server-tags ...}.

\item\code{install}
\begin{verbatim}
usage: eups distrib install [-h|--help] [options] product [version]

Install a product from a distribution package retrieved from a repository. If
a version is not specified, the most version with the most preferred  tag will
be installed.

options:
  -d TAG, --declareAs=TAG
                        tag all newly installed products with this user TAG
                        (repeat as needed)
  -g GROUP, --groupAccess=GROUP
                        Give specified group r/w access to all newly installed
                        packages
  -I DIR, --install-into=DIR
                        install into this product stack (Default: the first
                        writable stack in $EUPS_PATH)
  -m MANIFEST, --manifest=MANIFEST
                        Use this manifest file for the requested product
  -U, --no-server-tags  Prevent automatic assignment of server/global tags
  --noclean             Don't clean up after successfully building the product
  -j, --nodepend        Just install product, but not its dependencies
  -N, --noeups          Don't attempt to lookup product in eups (always
                        install)
  -r BASEURL, --repository=BASEURL
                        the base URL for a repository to access (repeat as
                        needed).  Default: $EUPS_PKGROOT
  -t TAG, --tag=TAG     preferentially install products with this TAG
  --tmp-dir=DIR         Build products in this directory
  --nobuild             Don't attempt to build the product; just declare it
  -f FLAVOR, --flavor=FLAVOR
                        Assume this target platform flavor (e.g. 'Linux')
  -F, --force           Force requested behaviour
  -D DISTRIBCLASSES, --distrib-class=DISTRIBCLASSES
                        register this Distrib class (repeat as needed)
  --server-option=SERVEROPTS
                        pass a customized option to all repositories (form
                        NAME=VALUE, repeat as needed)
  -S SERVERCLASSES, --server-class=SERVERCLASSES
                        register this DistribServer class (repeat as needed)
  --debug=DEBUG         turn on specified debugging behaviors (allowed: raise)
  -h, --help            show command-line help and exit
  -n, --noaction        Don't actually do anything (for debugging purposes)
  -q, --quiet           Suppress messages to user (overrides -v)
  --type=SETUPTYPE      The setup type to use (e.g. exact)
  -v, --verbose         Print extra messages about progress (repeat for ever
                        more chat)
  -V, --version         Print eups version number
  --vro=LIST            Set the Version Resolution Order
  -Z PATH, --database=PATH
                        The colon-separated list of product stacks (databases)
                        to use. Default: $EUPS_PATH
  -z DIR, --select-db=DIR
                        Select the product paths which contain this directory.
                        Default: all in path
  --with-eups=PATH      synonym for -Z/--database
  --recurse             don't assume manifests completely specify dependencies
  --root=ROOT           equivalent to --repository (deprecated)
  -C, --current-all     Disabled; make all products we install current
  -c, --current         Make top level product current (equivalent to --tag
                        current)
\end{verbatim}

Usually \code{--force} will reinstall all products, but you can override this with an entry in
\file{manifest.remap}:
\begin{verbatim}
product[:version]  noReinstall
\end{verbatim}
and is useful if you have local declarations of e.g. python.

Due to restrictions on the server side (e.g. \textbf{robots.txt} files) checking all the possible tags
can be annoyingly slow, and it's especially annoying if you have specified an explicit tag.  You might
want to consider using \code{--no-server-tags} (equivalent to \code{-U}) to avoid this; the specified
tag will still be installed.

You sometimes want to run some code after products have been installed.  For example, due to restrictions
imposed by os/x (``The SIP'') you may need to fix up the \texttt{\#!} (``shebang'') lines, or to patch symbolic links for
shared object files that point outside the installed tree.  The mechanism is that if a file
\file{distribInstallPostHook.py} is found in one of the standard places to find customisation files (as shown
by \code{eups startup -v}). There is an example file in the \eups source directory, \file{callback/distribInstallPostHook.py} which patches both shebangs and shared object file paths.

This file needs to be on the \textit{installer}'s machine, of course,
e.g. \file{/u/products/site/distribInstallPostHook.py}.

\item\code{path}
\begin{verbatim}
Usage: eups distrib path [-h|--help] [n]

Print the base URLs for the repositories given via EUPS_PKGROOT.  An
optional integer argument, n, will cause just the n-th URL to be listed
(where 0 is the first element).

Options:

  ...
\end{verbatim}


\end{itemize}

You may use \code{eups distrib list} to list available products; with \code{--tag current}
only current products are listed.  E.g.
\begin{verbatim}
eups distrib list --root http://www.astro/~rhl/LSST/packages --tag current mwi 2.4
\end{verbatim}
(or you could use any other tag of your choice).
You can list tags with e.g. \code{eups distrib tags w\_2017*} (note the glob; csh users in particular
will probably need to protect it from the shell).

Note that there isn't enough information in any single file on the 
server to tell us which products are available for which flavor, so
to get accurate listings we have to do another round-trip query for
each product/version/flavor.  This is slow, so is only implemented
if you specify \code{eups distrib list --precise} (or \code{--verbose} --- but that'll also
list the dependencies).

Once you've created a package with \code{eups distrib create} you can log on to
another machine and use \code{eups distrib install} to
recreate a working \eups installation.  For example:
\begin{verbatim}
eups distrib --verbose --select-db act create moby v1_2
eups distrib --database /u/rhl/ppp --verbose install \
             --root http://www.astro.princeton.edu/~act/packages moby v1_2
\end{verbatim}
to install \code{moby} into a \file{/u/rhl/ppp} \eups database. If you omit
\code{--root} it'll be taken from the environment variable \code{EUPS\_PKGROOT},
if set.  As an alternative to an http URL, you may specify a directory as
if you were using \code{scp}, prefixed by \code{scp:}; e.g.
\begin{verbatim}
    --root=scp:rhl@apache2.astro.princeton.edu:WWW/public/distrib
\end{verbatim}

When creating an distribution, tarballs that already present are not recreated
(unless you specify \code{--force}),
so repeating a \code{eups distrib create} command to create a manifest for another
product won't lead to duplication of tarballs.  If you want to use buildfiles
see App. \ref{buildFiles}; if you'd like to try \pacman{}, see App. \ref{pacman}.

When unpacking a distribution with \code{eups distrib install}, products that are
already declared to \eups won't be unpacked and re-declared (unless you specify \code{--force}).

If you don't specify a version when installing a distribution with
\code{--install} the current version will be used.  This isn't quite the same
as the version declared current on some machine where the distribution
originated, as a bleeding-edge version acceptable in Princeton may not
be ready for deployment on a mountain top in e.g. Chile. In
consequence, the list of `current' versions is \textit{not}
automatically created or updated by \code{eups distrib create}, but is
only set when you later say \code{eups distrib create --current}.  If you don't specify
a product, the list will in fact be identical to your local preferences.
Alternatively, you can update a single product's version number (e.g.
\code{eups distrib create --current moby}) or specify a version (\code{eups distrib create --current moby v1\_2}).

\textit{N.b.} As presently written, \code{eups distrib} assumes that (unless you're
using \code{--noeups}) you've
installed all the products into \eups, as opposed to simple declaring them, but
relying on files installed in e.g. \code{/usr/local}; more precisely, it assumes
that all product directories start with a directory listed in \code{EUPS\_PATH}.
This is probably a good idea, as otherwise \code{eups distrib} would tar up
all of /usr/local for you.

\textit{N.b.} A decent description of the \code{-d builder -S buildFilePath=D:D:} version of this command
needs to be written!  This would include the \code{-S noeups=True} option, and its use
of product.table files in the BuildFilePath

For example, to create a distribution of product \code{moby} (already declared
to \eups on my machine), install it in a central place (on \code{apache2})),
and then install in on some other machine I first created a build file
\code{moby.build} in \code{moby}'s ups directory:
\begin{verbatim}
export CVSROOT="@CVSROOT@"

cvs co -P -d @PRODUCT@-@VERSION@ -r @VERSION@ @PRODUCT@ &&
cd @PRODUCT@-@VERSION@ &&
setup -r . &&
./configure &&
make &&
make install
\end{verbatim}
and then typed:
\begin{verbatim}
eups distrib create -v -s /u/act/products/packages -d builder -S buildFilePath=~/ACT//BuildFiles:$EUPS_PATH: --current moby &&
rsync -rv /u/act/products/packages apache2:/u/act/WWW/public

eups distrib -v install --current moby --root http://www.astro.princeton.edu/~act/packages
\end{verbatim}
The \code{~/ACT/BuildFiles:} tells \eups to first look for build files
in \code{~/ACT/BuildFiles} and then the product's \code{ups} directory (that's what
the trailing \code{:} means); that's why \code{--build :} means to only search \code{ups}
directories\footnote{
  You can use an empty string instead, but don't forget to quote it so that it isn't
  stripped by your shell, e.g. \code{--build "''"} --- \code{--build :} is easier.
  }. The \code{rsync} should be clear, and the second
\code{eups distrib} does the install.

What if your product isn't (yet) declared to \eups?  Write a build file \code{scipy.build} and
maybe table file \code{scipy.table} in \code{\~/ACT/BuildFiles}, and incant:
\begin{verbatim}
eups distrib -z act create -s /u/act/products/packages --build ~/ACT/BuildFiles: -S noeups=True scipy 0.6.0

eups distrib -z act install scipy 0.6.0 --root http://www.astro.princeton.edu/~act/packages scipy 0.6.0
\end{verbatim}
N.b. this uses \code{scipy.table} from the build file directory, \code{\~/ACT/BuildFiles}. The
\code{noeups} only applies at the top level;  if your table file specifies dependencies
they'll be honoured (the current versions will be used if you don't specify desired versions). A
simplified version (in this case installing the just-released \code{swig 1.3.35} on my laptop) is:
\begin{verbatim}
eups distrib create -s /u/act/products/packages --build \~/ACT/BuildFiles swig 1.3.35 -S noeups=True
eups distrib install swig 1.3.35
\end{verbatim}

You can also use \code{-S noeups=True} to create a distribution from a checked out version without
first installing it.  You'll need to tell \eups where to look for the table/build files
in \code{./ups}:
\begin{verbatim}
eups distrib create -s /u/act/products/packages --build ups -S noeups=True mwi 2.4
\end{verbatim}

%------------------------------------------------------------------------------

\subsubsection{\code{eups expandbuild}}
\begin{verbatim}
eups expandbuild -h
Usage:
    eups [commonOptions] expandbuild [options] buildFile [outDir]

    Expand a .build file as part of installing it.

    If outDir is provided, the expanded file will be written there;
    otherwise it'll be written to stdout unless you specify --inplace.

Options:
   -c, --cvs        arg    Use this CVSROOT
                           Alias: --cvsroot
   -i, --inplace           Modify file in situ
   -p, --product    arg    The name of the product
   -s, --svn        arg    Use this SVNROOT
                           Alias: --svnroot

Expand a .build file as part of installing it.

If outDir is provided, the expanded file will be written there;
otherwise it'll be written to stdout unless you specify --inplace.
\end{verbatim}

Modify a ups build file (see section \ref{buildFiles}) expanding certain variables:
\begin{description}
  \item[\small @CVSROOT@] The value of \code{\$CVSROOT} used to check out this product.
    This is guessed from \code{./CVS} if not specified with \code{--cvs} (or \code{-c})
    or \code{\$CVSROOT}.
  \item[\small @PRODUCT@] The name of the product. This is guessed from \code{buildFile}
    (by dropping the suffix \code{.build}) if not provided with \code{--product} (or \code{-p}).
  \item[\small @SVNROOT@] The \code{svn} locator (e.g. \code{svn+ssh://svn.lsstcorp.org/DC2/fw/trunk})
    used to check out this product.
    This is guessed from \code{./.svn} if not specified with \code{--svn} (or \code{-s})
    or \code{\$SVNROOT}.
  \item[\small @VERSION@] The version of the product.  This is taken from the \code{--version} (or
    \code{-V}) option.
\end{description}

E.g. the file \code{prod1.build}
\begin{verbatim}
export CVSROOT="@CVSROOT@"
cvs co -d @PRODUCT@-@VERSION@ -r @VERSION@ @PRODUCT@
\end{verbatim}
becomes (with the \code{-V v1\_0\_1} option):
\begin{verbatim}
export CVSROOT="jeeves.astro.princeton.edu:/usr/local/cvsroot"
cvs co -d prod1-v1_0_1 -r v1_0_1 prod1
\end{verbatim}

Because this list of pre-defined variables is so inflexible, you can define a dictionary
of your own values in a startup file (\textit{e.g.} \code{\$HOME/.eups/startup.py}). For
example, after
\begin{verbatim}
hooks.config.distrib["builder"]["variables"]["WHO"] = "RHL"
\end{verbatim}
I can refer to \code{@WHO@} in build files.

A little imagination soon comes up with definitions such as:
\begin{verbatim}
hooks.config.distrib["builder"]["variables"]["DEFINE GET-SRC"] = """
get_src () {
    svn co "$@"
}
"""
hooks.config.distrib["builder"]["variables"]["GET-SRC"] = "get_src"
\end{verbatim}
which allow the insertion of centrally controlled shell functions into all build files as they
are expanded.

If a directory is specified, the modified build file will be written
there, with the same name as the original; otherwise it's written to
standard out unless you specify \code{--inplace}.

For example, the make target in a ups directory might contain the line:
\begin{verbatim}
      eups expandbuild -V $(VERSION) ups/prod1.build $(prefix)/ups
\end{verbatim}
				% $ for emacs

There is one special case when rewriting build files:  If the version
is of the form \code{svn\#\#\#} (e.g. \code{svn666}), any occurrence of
\code{/tags/svn\#\#\#} is replaced by \code{/trunk -r \#\#\#}. This will usually
lead to \code{svn co svn+ssh://host.edu/product/tags/svn666}
being replaced by \code{svn co svn+ssh://host.edu/product/trunk -r 666}
which is probably what you want.

%------------------------------------------------------------------------------

\subsubsection{\code{eups expandtable}}
\label{expandtable}
\begin{verbatim}
Usage: eups expandtable [options] file.table [directory]
Options are
    -h, --help    Print this message
    -i, --inplace Modify file in situ
    -p, --product PRODUCT=VERSION   Expand PRODUCT to use VERSION
    -w, --warn    Warn about versions that don't start with v or V
\end{verbatim}

Modify a ups table file replacing setupRequired and setupOptional
lines which refer to the current version by the actual version number
of the currently setup product; e.g.
\begin{verbatim}
      setupRequired("-f ${EUPS_FLAVOR} astroda")
\end{verbatim}
becomes
\begin{verbatim}
      setupRequired("-f ${EUPS_FLAVOR} astroda v13_1")
\end{verbatim}
You can override the version with e.g. \code{-p astroda=rhl}; more
than one \code{-p} command is permitted.  If the table file contains
a constraint on the version (e.g. \code{setupRequired(daf\_base >= 3.2.6)})
it'll be preserved in the installed file (e.g. \code{setupRequired(daf\_base 3.2.9 [>= 3.2.6])}).
These options are used by the \code{VRO}'s \code{version} and \code{versionExpr} entries.

If a directory is specified, the modified table file will be written
there, with the same name as the original; otherwise it's written to
standard output unless you specify \code{--inplace}, in which case the
substitution will be done in situ.
You may omit file.table, or specify it as "-", to read standard input;
this implies \code{--inplace}.

For example, the make target in a ups directory might contain the line:
\begin{verbatim}
      eups expandtable -w iop.table $(IOP_DIR)/ups
\end{verbatim}
				% $ for emacs

In addition to adding explicit versions of all products listed in the table files, \code{expandtable} also
writes a logical block to the tablefile that gives the versions of every product that it setup.  Returning
to the diamond dependency example in Sec. \ref{SetupVersionChoice}:
\DiamondDependencyFigure
Let us assume that we chose to use C 2.0 (e.g. by explicitly setting up C 2.0 after setting up A).
Initially A's table file looked like
\begin{verbatim}
setupRequired(B)
\end{verbatim}
and \code{eups expandtable} rewrites it as
\begin{verbatim}
if (type == exact) {
   setupRequired(B   -j 2.2)
   setupRequired(C   -j 2.0)
   setupRequired(D   -j 2.2)
} else {
   setupRequired(B 2.2 [>= 2.2])
}
\end{verbatim}

%------------------------------------------------------------------------------

\subsubsection{\code{eups flags}}
\begin{verbatim}
Usage:
    eups [commonOptions] flags [options]

Print the value of EUPS_FLAGS
\end{verbatim}

Print the value of \code{EUPS\_FLAGS}

%------------------------------------------------------------------------------

\subsubsection{\code{eups flavor}}
\begin{verbatim}
Usage:
   eups flavor
\end{verbatim}

Print your machine/operating system's flavor.  In simple cases, this'll
be the same as \code{uname -m}, but in reality it has to worry about things
like 32/64 bit libraries and os/x running on both PPC and X86 architectures.

%------------------------------------------------------------------------------

\subsubsection{\code{eups list}}
\begin{verbatim}
Usage:
    eups [commonOptions] list [options] [product] [version]

Options:
   -c, --current           Only show current products
   -Z, --database   arg    Use this products path. Default: $EUPS_PATH
                           Alias: --with-eups
       --debug      arg    Permitted Values: raise
   -D, --dependencies      Print product's dependencies
       --depth      arg    Only list this many layers of dependency
   -d, --directory         Print product directory
   -e, --exact             Use the as-installed version, not the conditional in the table file
   -f, --flavor     arg    Use this flavor. Default: $EUPS_FLAVOR or `eups flavor`
   -F, --force             Force requested behaviour
   -h, --help              Print this help message
   -n, --noaction          Don't actually do anything
   -z, --select-db  arg    Select the product paths which contain this directory.
                           Default: all
   -s, --setup             Only show setup products
   -S glob, --showTags=glob Only show tags that match this glob
   -m, --table             Print name of table file
   -t, --tag        arg    List versions with this tag (e.g. current or stable)
   -T, --type       arg    Specify type of setup (permitted values: build)
   -v, --verbose           Be chattier (repeat for even more chat)
   -V, --version           Print the version
\end{verbatim}

Print information about products.

The \code{--depth} option only applies to \code{--dependencies}. In general it's
an expression; the useful ones are of the form \code{depth == 2} or \code{depth <= 2}.
You may omit the \code{depth}, and if you just say \code{2} it's taken to mean \code{<= 2}
and thus \code{depth <= 2}.  E.g. the first-level dependencies may be displayed as
\code{eups list --dependencies --depth ==1 product version}.  Indentation's used to
indicate the indirectness of the dependency unless you specify an exact depth (i.e. with \code{==}).

The command \code{setup list --current} will list all products that
are declared current, or \code{setup list --tag} will list any tag that you're interested in (\code{tag}
may be a glob, \textit{e.g.} \code{--tag w\_2017\_2?}. Adding the \code{--verbose} option will also
list the database root and product root paths.  If you only want the product's
directory, you can use \code{--directory}.
The product name may be a glob expression (i.e. \code{*}, \code{?},
and \code{[]} are special, just like the shell).  Note that you may
need to quote them to protect them from the shell; e.g. \code{eups list $\backslash$* svn$\backslash$*}

%------------------------------------------------------------------------------

\subsubsection{\code{eups path}}
\label{eups path}
\begin{verbatim}
Usage: eups path [-h|--help] [n]

Print the product stack directories given via EUPS_PATH.  An
optional integer argument, n, will cause just the n-th directory
to be listed (where 0 is the first element).

\end{verbatim}

Tell me the current \eups search path

%------------------------------------------------------------------------------

\subsubsection{\code{eups pkg-config}}
\begin{verbatim}
Usage:
    eups [commonOptions] pkg-config [options] product [version]

Print information about products

Options:
   -c, --cflags            Output all pre-processor and compiler flags
   -l, --libs              Output all linker flags
\end{verbatim}

The same as the standard \code{pkg-config} command, except that it
searches \code{\$PRODUCT\_DIR/etc} for the \code{.pc} file.  It also
works around the problem that quoted variables \code{\$\$\{...\}}
in \code{.pc} files appear as \code{\%\{...\}} in \code{pkg-config} output.\footnote{
  Yes; I filed a Debian bug report (378570) and it's fixed in the next release, 0.21-1}

%------------------------------------------------------------------------------

\subsubsection{\code{eups remove}}
\begin{verbatim}
Usage:
    eups [commonOptions] remove [options] [product] [version]

Remove a product

Options:
   -i, --interactive       Prompt user before actually removing products (default if -R)
   -N, --noCheck           Don't check whether recursively removed products are needed
       --noInteractive     Don't prompt user before actually removing products
   -R, --recursive         Recursively also remove everything that this product depends on
\end{verbatim}

Undeclare the specified product, and remove it from the system. If you specify
\code{--recursive} then all dependent products will also be removed; this is dangerous
as they may be needed by someone else. \eups accordingly checks for products
that are in use and refuses to remove them unless you specify \code{--force}.  As
an added safeguard, \code{eups remove --recursive} will prompt you before doing anything
(you can bypass this check with \code{--noInteractive}.

You can use \code{eups uses} to check whether a product's in use.

%------------------------------------------------------------------------------

\subsubsection{\code{eups startup}}
\begin{verbatim}
Usage: eups startup [-h|--help]

List the startup files that customize EUPS (including $EUPS_STARTUP).  With
-v, show non-existent files that would be loaded [in brackets].
\end{verbatim}

\eups can be customised using files in a surprisingly large number of places; \code{eups startup}
lists the startup files that are actually used (with \code{-v} non-existent files that would be
used are also listed, enclosed in square brackets).

%------------------------------------------------------------------------------

\subsubsection{\code{eups tags}}
\begin{verbatim}
Usage: eups tags [-h|--help] [options]

Print information about known tags, or clone or delete a tag

  --clone=CLONE         Specify a tag to clone (must also specify new tag)
  --delete=DELETE       Specify a tag to delete
\end{verbatim}

For example,
\begin{verbatim}
$ eups tags --clone rhl tmp
\end{verbatim}
assigns the tag \code{tmp} to all products tagged \code{rhl} (remember to declare \code{tmp}
in your \file{startup.py} file with \code{hooks.config.Eups.userTags.append("tmp")}
)
while
\begin{verbatim}
$ eups tags --delete tmp
\end{verbatim}
removes the tag \code{tmp} from all products (but doesn't undeclare it).

%------------------------------------------------------------------------------

\subsubsection{\code{eups undeclare}}
\begin{verbatim}
Usage:
    eups [commonOptions] undeclare [options] product [version]

Undeclare a product

Options:
   -c, --current           Stop version from being current
   -t, --tag        arg    Undeclare versions with this tag (e.g. current or stable)
\end{verbatim}

Undeclares \code{version} of \code{product} from the database. Also removes any tags attached to version; if
you just want to delete a tag, use \code{--tag XXX} (as a special case rooted in history, \code{--current} is
equivalent to \code{-t current}).

If you specify a tag but not a version then the version itself will \textit{not} be undeclared; the exception
is that it \textit{will} be undeclared if version is of the form \code{tag:XXX}\footnote{
  \textit{i.e.} the version name was automatically
generated by a command such as  \code{eups declare -t XXX -r .} or \code{eups declare -t XXX productName} where you didn't name a version}.  You can force the underlying version to be undeclared along with the tag by specifying \code{--undeclareVersion} (or equivalently \code{--U}), e.g. \code{eups undeclare scons -t w\_2017\_52 -U}.

%------------------------------------------------------------------------------

\subsubsection{\code{eups uses}}
\begin{verbatim}
Usage:
    eups [commonOptions] uses [options] product [version]

Show which products setup the specified product (and maybe version of that product)

Options:
   -c, --current           Look for products that setup product only because it's current
                           N.b. This isn't the same as specifying product's current version
   -d, --depth      arg    Only search down this many layers of dependency
   -e, --exact             Use the as-installed version, not the conditional in the table file
   -o, --optional          Show optional setups
\end{verbatim}

Go through the \eups databases and return every product that depends upon the specified product and version;
if the version's omitted then everything that depends on product is returned, along with the version
required. \textit{N.b.  this will be quite slow if you've disabled the cache --- it'll need to read every table
  file that \eups knows about.}

Unless you specify \code{--quiet} you'll be warned if a product depends on
more than one version;  this may sound unlikely but can happen if you setup
the something more than once when setting up a product.

%------------------------------------------------------------------------------

\subsubsection{\code{eups vro}}
\begin{verbatim}Usage: eups vro [-h|--help] [options] product [version]

Print information about the Version Resolution Order (VRO) to use if issuing
the setup command with the same arguments.

Options:
  --type=SETUPTYPE      the setup type to use (e.g. exact)
  -c, --current         same as --tag=current
  -e, --exact           Consider the as-installed versions, not the
                        dependencies in the table file
  -r PRODUCTDIR, --root=PRODUCTDIR
                        root directory where product is installed
  -t TAG, --tag=TAG     Set the VRO based on this tag name
\end{verbatim}

Sometimes you may want to know what VRO would be used by a particular \code{setup} command; here's how you can
find out.

%------------------------------------------------------------------------------

\subsubsection{\code{setup}}
\begin{verbatim}
Usage: setup [-h|--help|-V|--version] [options] [product [version]]

(Un)Setup an EUPS-managed product.  This will "load" (or "unload") the
product and all its dependencies into the environment so that it can be used.

Options:
  -C, --current         deprecated (use --tag=current)
  -Z PATH, --database=PATH
                        The colon-separated list of product stacks (databases)
                        to use. Default: $EUPS_PATH
  --debug=DEBUG         turn on specified debugging behaviors (allowed: raise)
  -e, --exact           Don't use exact matching even though an explicit
                        version is specified
  -f FLAVOR, --flavor=FLAVOR
                        Assume this target platform flavor (e.g. 'Linux')
  -E, --inexact         Don't use exact matching even though an explicit
                        version is specified
  -F, --force           Force requested behaviour
  -h, --help            show command-line help and exit
  -i, --ignore-versions
                        Ignore any explicit versions in table files
  -j, --just            Just setup product, no dependencies (equivalent to
                        --max-depth 0)
  -k, --keep            Keep any products already setup (regardless of their
                        versions)
  -l, --list            deprecated (use 'eups list')
  -m TABLEFILE, --table=TABLEFILE
                        Use this table file
  -S MAX_DEPTH, --max-depth=MAX_DEPTH
                        Only show this many levels of dependencies (use with
                        -v)
  -n, --noaction        Don't actually do anything (for debugging purposes)
  -N, --nolocks         Disable locking of eups's internal files
  -q, --quiet           Suppress messages to user (overrides -v)
  -r PRODUCTDIR, --root=PRODUCTDIR
                        root directory of requested product
  -z DIR, --select-db=DIR
                        Select the product paths which contain this directory.
                        Default: all in path
  -t TAG, --tag=TAG     Put TAG near the start of the VRO (may be repeated;
                        precedence is left-to-right)
  -T TAG, --postTag=TAG Put TAG after version(Expr)? in VRO
                        (may be repeated; precedence is left-to-right)
  --type=SETUPTYPE      The setup type to use (e.g. exact)
  -u, --unsetup         Unsetup the specifed product
  -v, --verbose         Print extra messages about progress (repeat for ever
                        more chat)
  -V, --version         Print eups version number
  --vro=LIST            Set the Version Resolution Order
\end{verbatim}
				% $ for emacs

This is the workhorse routine. It sets up \code{version} of \code{product}. You
may omit the \code{version} (in which case you'll get the \code{current} version),
specify an explicit version, or use a logical expression. E.g.
\begin{verbatim}
  setup ds9
  setup ds9 4.13
  setup ds9 '>= 5.0'
  setup ds9 '>= 5.0 || rhl'
\end{verbatim}
(don't forget to quote \code{<} and \code{>} as they're interpreted by the shell).

\textbf{Important}: Since the commands to set environment variables differ across shells,
it is essential that \code{\$SHELL} reflects the current shell.

Options \code{--current} and \code{--setup} are only relevant with \code{--directory}.

(N.b. setup is really an alias or shell function that runs the command\hfil\break
\code{source `eups\_setup [options] product [version]`}\hfil\break
\code{eups\_setup} writes a shell script that is then sourced into the
current shell.  This \code{eups\_} command alone is not deprecated.
)

If you specify \code{--root}, you may not need to give the
product's name if you're not giving a version number too.
If the ups directory contains only one
table file, it'll be taken to be the product that you
want to setup.  I.e. \code{setup -r .} will work.

If you set verbose to three or more, the file that \code{setup} writes (and
which is sourced to modify your current shell's variables) is not deleted
after use, allowing you to peruse it at your leisure.

The \code{-k} (`keep') makes \eups preserve your pre-existing setups.
You can achieve the same effect
by carefully chosing your setup order, but this is easier.

The \code{-D} option specifies that the product itself \textit{not} be
setup, but that it's dependencies should be processed as normal.

With \code{-M} you specify a table file for something that may not
even be declared to \eups; this is useful for setting up dependent
products during installation.  Implies \code{-D}, and you may not
specify a product name. \emph{N.b.} this is not the way to set up
a local product --- use \code{setup --root dir [product]} (e.g. setup -r .).

If \eups detects an error, the file-to-source will be empty (i.e.
the setup will be aborted) unless you specify \code{--force}.

Usually \eups will lock files before using them, but this may not be desireable or required when setting up
products on a quiescent system (i.e. one where no-one is actively declaring products).  You can turn locking
off with the \code{-N} option.  Another way to achieve this is to use the \code{commandCallbacks} mechanism;
there's an example in Sec. \ref{commandCallbacks}.

%------------------------------------------------------------------------------

\subsubsection{\code{unsetup}}
\begin{verbatim}
Usage:
   unsetup [options] product
Options:
(same as setup)
\end{verbatim}

All the notes under \code{setup} apply to
\code{unsetup}. Unsetting up a product relies on the environment
variable \code{\$SETUP\_<product>}, so it fails if the variable
isn't set (unless you use \code{-M}).

\subsection{Environment Variables}

Required variables -

\begin{itemize}
  \item \code{SHELL}
    This must be set to the shell that you're running. This is
    generally set correctly for you, unless you run a shell script, or
    change your shell.

  \item \code{EUPS\_DIR}
    Where \eups is installed.

  \item \code{EUPS\_PATH}
    The colon-separated path of root directories under which all products are installed.
    Each root directory has a UPS database in a top-level \code{ups\_db} directory.
    As of \code{v0\_7\_33}, when you source \code{setups.[c]sh}, any
    pre-existing value of \code{EUPS\_PATH} is preserved at the end of
    your new path.
\end{itemize}

Optional Variables -

\begin{itemize}
  \item \code{EUPS\_DEBUG}
    This sets the verbosity; equal to the difference between the number of \code{-v}s
    and \code{-q}s.

    If you are confused by some error, or simply nosy, try adding a \code{-v}.

  \item \code{EUPS\_FLAVOR}
    Set to the default flavor (if not set \eups will use the value returned
    by \code{eups flavor}).

  \item \code{EUPS\_FLAGS}
    A list of options prepended to all setup/unsetup/declare/undeclare commands. Options
    that are not permitted by a given command are silently ignored (e.g. \code{-k}
    with \code{eups declare}).
\end{itemize}

%------------------------------------------------------------------------------

\subsection{Locking}

There are currently has three types of locks, and each command chooses one of them.
\begin{itemize}
  \item no lock
  \item shared lock
  \item exclusive lock
\end{itemize}
and the entire \eups system is locked\footnote{This may be a problem...}
Locking is per-process, or more precisely per a process and its children.

The following commands take a shared lock:
\begin{itemize}
\item \code{eups admin info}
\item \code{eups admin listCache}
\item \code{eups distrib list}
\item \code{eups expandbuild}
\item \code{eups expandtable}
\item \code{eups list}
\item \code{eups pkg-config}
\item \code{eups tags}
\item \code{eups uses}
\end{itemize}
and these take an exclusive lock:
\begin{itemize}
\item \code{eups admin buildCache}
\item \code{eups admin clearCache}
\item \code{eups admin clearServerCache}
\item \code{eups declare}
\item \code{eups distrib clean}
\item \code{eups distrib create}
\item \code{eups distrib declare}
\item \code{eups distrib install}
\item \code{eups remove}
\item \code{eups undeclare}
\end{itemize}

%------------------------------------------------------------------------------


\subsection{The Database}

\subsubsection{\eups Files}

This section briefly describes the structure of the UPS database. Each
EUPS root directory in \code{EUPS\_PATH} contains a database directory
\code{ups\_db}, with a subdirectory for each declared product.  Each
of these product directories contain a series of product definitions,
specified by three types of files:

\begin{itemize}
  \item current.chain

    There is only one (if any) of these per directory.  The
    current.chain file specifies the current version for a given
    flavor, and is what is used as the default if the version is not
    specified.

  \item Version files

    There is one of these for every declared version of the product,
    named \file{<version>.version}. The file specifies basic information
    about the version of the product, including where it is installed.

  \item Table files

    These specify the dependencies of the product. The default name
    for these is \file{<version>.table} although a specific name can be specified in the
    version file.

    Table files use a series of commands to specify the dependencies. These are
    discussed in the next subsection.

    NOTE: See Section 5 for a note on the search algorithm that \eups uses for
    locating table files.

  \item Cache files

    \eups uses a set of cache files that record the contents of the declared
    table files.  This provides a \emph{very} significant speedup when using
    commands such as \code{eups remove} or \code{eups uses}, but the speedup
    is also significant with a lowly \code{eups list}.

    The cache can get confused; in this case you can use the \code{eups admin clearCache}
    command to clean up.  If you can figure out exactly what you did to confuse
    \eups please let us know so we can fix it!  There is also a problem where
    the cache grows large;  once more \code{eups admin clearCache} should
    solve (or rather, mask) the problem.

    We are thinking of providing an option to disable the cache, either because
    you don't have write permission, or because the risk of cache corruption is
    more important to you than speed considerations.
\end{itemize}

\subsubsection{\eups table format}

Table files consist of blocks of commands, possible subject to if-else if-else blocks, \textit{e.g.}
\begin{verbatim}
if (FLAVOR == DarwinX86) {
   print(stdinfo, os/x)
} else if(FLAVOR == Linux || FLAVOR == Linux64) {
   print(stdinfo, linux)
}
\end{verbatim}

By default the test may use \code{FLAVOR} or \code{TYPE} (\textit{e.g.} \code{setup --type build})
(you can add more by setting \code{config.Eups.setupTypes} in a \file{startup.py} file; see
\ref{secStartupFiles})

\paragraph{\eups table commands}

If a value looks like \code{\$?\{NAME\}}, and there is no such environment variable, the entire line is
ignored (As a special case, \code{PRODUCT\_DIR} is considered undefined if its value is \code{none}).
If you omit the \code{?} it's an error for \code{NAME} not to exist.
Additionally, \code{\$\{NAME:-XXX\}} expands to \code{\$NAME} if defined, and to \code{XXX} otherwise.

The following table commands are supported by \eups: (\code{<Name>} either specifies an
alias or an environment variable - clear from the context.)

\begin{itemize}
   \item \code{addAlias(<Name>,<Value>)}
     Defines a function or an alias.  Arguments should be written in
     sh format (i.e. \code{\textbackslash"\$@\textbackslash"} not \code{\textbackslash!*}); don't worry,
     the csh alias will be defined correctly.  E.g.
     \begin{verbatim}
     addAlias(foo, source `${PRODUCT_DIR}/bin/eups_setup setup \"$@\"`;);
     \end{verbatim}
     Don't forget to escape the quotes.

   \item \code{envAppend(<Name>, <Value> [,<delimiter>])}
     Appends \code{<Value>} to \code{<Name>}. The default delimiter is~`:'; the value may not contain an
     embedded delimiter (use two separate \code{envAppend} commands instead).
     If the value looks like \code{\$?\{name\}},
     and there is no such environment variable, the \code{envAppend} command is ignored.
     If \code{<Value>} starts or ends
     with \code{<Delimiter>}, the final value of \code{<Name>} will
     have a delimiter pre- or -appended;  this is useful
     for variables such as \code{\$MANPATH} which use such an empty
     element to mean, ``use the default path too''. E.g.
     \begin{verbatim}
     envAppend(MANPATH, :${PRODUCT_DIR}/man)
     \end{verbatim}		% $


   \item \code{envPrepend(<Name>,<Value> [,<delimiter>])}
     Similar to envAppend, but put the value at the beginning

   \item \code{envSet(<Name>, <Value>)}
     Set \code{<Name>} to \code{<Value>}.

   \item \code{envUnset(<Name>)}
     It might sound as if this directive unsets the environment variable \code{<Name>}, and it
     would be possible to implement this if you have a use for it.  However, at present the
     only supported \code{<envUnset>} command is
     \code{envUnset(PRODUCT\_DIR)} which may be used to prevent
     \eups from setting \code{\$PRODUCT\_DIR}.
     For example, \code{git} uses \code{GIT\_DIR} for its own purposes,
     but yet it's useful to use \eups to manage \code{git} versions.

   \item \code{print(<String>)}
   \item \code{print(<Dest>, <String>)}
     Print the string to stdout; if \code{<Dest>} is provided it must be one of
     \code{stdout}, \code{stderr}, \code{stdok}, \code{stdinfo}, and \code{stdwarn}.

   \item \code{setupRequired(<Name> [options] [<Version>])}
     Setup \code{<Name>}.  If no \code{<Version>} is specified, the current
     version is used. Fails if unable to setup.

     \code{Version} may in fact be a logical expression, specifying acceptable
     versions. Permitted relational expressions are \code{>}, \code{>=}, \code{==},
     \code{<}, and \code{<=}. More than one expression may be joined using \code{||}
     (\code{\&\&} is not supported due to laziness).  For example,
\begin{verbatim}
    setupRequired(foo 1.2)
    setupRequired(foo == 1.2)
    setupRequired(foo >= 1.2)
    setupRequired(foo < 1.3)
    setupRequired(foo >= 1.2 || == rhl)
    setupRequired(foo >= 1.2 || rhl || svn)
\end{verbatim}
    The \code{==} is optional.  See the Sec. \ref{versionOrdering} for the definition
    of the ordering applied to version names.

    If more than one version matches the specified condition, priority is
    given to the version declared current;  if there is no current
    version, or it doesn't satisfy the condition, the highest valid version number
    is used.

    You may sometimes want to ignore explicit versions (e.g. if you are testing
    a new version, installed and current as \code{rhl}, but the table file specifies a
    version \code{> 1.2}).  You can do this with \code{setup -i} or \code{--ignore-versions}.

   \item \code{setupOptional(<Name> [ <Version>]}
     Same as \code{setupRequired} except that it does not fail if unable to setup.

%------------------------------------------------------------------------------
   \item \code{setupRequired(<Name> [options])}
     Unsetup \code{<Name>}.  Fails if unable to unsetup.

     An example is the LSST processing stack, where setup algorithms are run and a top-level
     product sets up a default set.  If want to disable some it's convenient to unsetup them up
     in your own product:
\begin{verbatim}
setupRequired(pipe_tasks)
unsetupRequired(meas_extensions_multiShapelet -j)
print(stdinfo, Disabling model fitting)
\end{verbatim}

   \item \code{unsetupOptional(<Name> [options]}
     Same as \code{setupRequired} except that it does not fail if unable to unsetup.

%------------------------------------------------------------------------------

\end{itemize}

\subsubsection{Version ordering}
\label{versionOrdering}

Version names are taken to be of the form \code{PrefixAAA.BBB.CCC-LLL.MMM.NNN+XXX.YYY.ZZZ}
where \code{Prefix} is optional, as are \code{-LLL.MMM.NNN} and \code{+XXX.YYY.ZZZ}.  Let's call
\code{PrefixAAA.BBB.CCC} the `primary' part, \code{LLL.MMM.NNN} the `secondary' part, and \code{XXX.YYY.ZZZ}
the `tertiary' part.
Each of the `dotted' parts may have any number of components. If you wish, you may use \code{\_}
instead of \code{.} as separators (this makes cvs happier).  Examples of valid
versions are:
\begin{verbatim}
  1.2.3
  v1.2.3.4
  a.b.c
  1.2.3-a.b
  1.2.3+a.b
  1.2.3-rc2+a.b
\end{verbatim}

The sorting rules are:
\begin{enumerate}
  \item If the version starts with non-digits (i.e. \code{Prefix} is provided),
    the two versions must have identical prefixes, or the first will sort to the
    left of the second (i.e. it can never satisfy \code{<}, \code{<=}, or \code{==}).

    If \code{Prefix} matches, it's ignored for the rest of the comparison.

  \item The primary part is then split on \code{.} (or \code{\_}), and
    each pair of components in the two names is compared numerically (if they look like
    integers) or lexicographically (otherwise). If they differ, the version name
    with the ``smaller'' component is taken to sort to the left, and the comparison
    stops.

  \item If one of the two version names is a subset of the other
    the longer version sorts to the right.  This only applies to the
    primary part; any secondary part is ignored in this comparison.

  \item If the two primary parts are identical, then the secondary part is
    examined.  Apart from the fact that no \code{Prefix} is allowed, the same
    rules are applied.  If only one version has a secondary part, it sorts
    to the \emph{left} -- so \code{1.2-rc2} sorts to the left of \code{1.2}.

  \item If the primary and secondary parts are identical, then the tertiary part is
    examined, applying the same rules as the secondary, except that if only one
    version has a tertiary part it sorts to the \emph{right}, so \code{1.2+hack}
    sorts to the right of \code{1.2}.
\end{enumerate}

What's the point of these complicated rules?  The primary sort should be
intuitive.  People often name \emph{pre-}release candidates things like
\code{1.2-rc2}, hence the rule for \code{1.2} being later than \code{1.2-rc2}.
After a version is released, you sometimes need a fixed version, so its
name should sort later --- hence \code{1.2+bugfix}.

Here are some examples:

\begin{tabular}{l|l|r|l}%
V1 & V2 & compar & notes \\
\hline
aa & aa & 0 & \\
aa.2 & aa.1 & +1 & Sort components numerically \\
aa.2.1 & aa.2 & +1 & \\
aa.2.1 & aa.2.2 & -1 & \\
aa.2.1 & aa.3 & -1 & \\
aa.2.b & aa.2.a & +1 & Sort components lexicographically \\
aa.2.b & aa.2.c & -1 & \\
v1\_0\_3 & a1.0.2 & -1 & Mismatching prefixes always sort to the left \\
v1\_0\_0 & 1.0.2 & -1 & Only V1 has a prefix \\
1\_0\_0 & v1.0.2 & -1 & Only V2 has a prefix\\
v1\_0\_2 & v1.0.0 & +1 & You can mix \code{.} and \code{\_} \\
v1.2.3 & v1.2.3-a & +1 & primary parts are identical, so secondary is examined \\
v1.2-0 & v1.2.3 & -1 & primary parts differ, so secondary parts are ignored \\
v1.2-4 & v1.2.3 & -1 & primary parts differ, so secondary parts are ignored \\
1-rc2+a & 1-rc2 & +1 & primary and secondary match; tertiary sorts to right \\
1-rc2+a & 1-rc2+b & -1 & sort is on tertiary \\
\end{tabular}

(Here compar is the value that C's \code{qsort} would use;  -1 if V1 is less
than V2; 0 if they're equal; +1 if V1 \code{>} V2).

\subsubsection{Obsolete table commands}

\begin{itemize}
   \item \code{pathAppend}, \code{pathPrepend}, \code{pathRemove}, \code{pathSet}
     Aliases for the \code{env} commands.

   \item \code{prodDir()}
     Sets \code{<PRODUCT>\_DIR} to the directory where the product is installed;
     this directive is ignored as \code{<PRODUCT>\_DIR} is automatically set for you.

   \item \code{setupEnv()}
     Sets \code{SETUP\_<PRODUCT>} so that product can be unsetup.
     this directive is ignored as \code{<PRODUCT>\_DIR} is automatically set for you.
\end{itemize}

\subsubsection{Variables}

The arguments to these UPS commands can be variables. All environment
variables can be used as \code{\$\{<ENV\_VARIABLE>\}}; \textit{e.g.} \code{\$\{HOME\}}.
\code{\$HOME} will not be expanded, so \code{envSet(FOO, \$\{HOME\})}
set \code{FOO} to the \textit{value} of \code{\$HOME} (\textit{e.g.} \code{/u/rhl}), whereas
\code{envSet(FOO, \$HOME)} sets it to \code{\$HOME}.

In addition, the following special variables are defined;

\begin{itemize}
  \item \code{\$\{PRODUCTS\}}
    The database

  \item \code{\$\{PRODUCT\_DIR\}}
    Where the product is installed.

  \item \code{\$\{PRODUCT\_DIR\_EXTRA\}}
    Where the product's extra files are installed; only set if there actually are
    any extra files (as provided by \code{eups declare}'s \code{-L} and \code{-M} options;
    \ref{eups declare})

  \item \code{\$\{PRODUCT\_FLAVOR\}}
    The product flavor.

  \item \code{\$\{PRODUCT\_NAME\}}
    The product name

  \item \code{\$\{PRODUCT\_VERSION\}}
    The product version

  \item \code{\$\{UPS\_DIR\}}
    The ups directory of the product (distinct from the directory
    in \code{\$\{PRODUCTS\}} - this is often where the table file will be stored).
\end{itemize}

\subsection{\eups autoconf commands}
\label{autoconfReference}

\XXX{Finish me}

\begin{itemize}
  \item{\code{AC\_INIT(product, version, ...}}
    This is a standard autoconf line, but with an invalid version name (\code{X.Y}).

  \item{\code{AC\_DEFINE\_ROOT(version [, flavor])}}
    Define the \code{configure} options
    \begin{itemize}
      \item{\code{--with-eups=path}}
        Specify the value of \code{EUPS\_PATH} and the prefix
        (defaults: \code{\$EUPS\_PATH} if set, or \code{\$prefix/share}. The
	prefix is taken to be the first component of the prefix, unless
	\code{--with-eups-db} is specified.

	\item{\code{--with-eups-db=DB}}
	  Select which component of the path is the prefix (just like setup's \code{-z}).
	  For example, if \code{EUPS\_PATH} is
    \code{/u/dss/products:/u/act/products} then the default prefix is
    \code{/u/dss/products}, but with \code{\--with-eups-db=act} the
    prefix becomes \code{/u/act/products}.

	\item{\code{--with-flavor=XXX}}
        Set the value of \code{EUPS\_FLAVOR}
        (default: \code{\$EUPS\_FLAVOR}, or the value returned by \code{eups flavor}
	or, failing \textbf{that}, uname).
    \end{itemize}
\end{itemize}

The conventional files are:
\begin{itemize}
   \item{etc/builddefs}
     Supports building on this platform. E.g.
\begin{verbatim}
CC = cc -std=c99
CFLAGS = -g -Wall
RANLIB = ranlib
\end{verbatim}

   \item{etc/installdefs}
     Supports the \code{make install} and \code{make declare} targets.

   \item{etc/makedefs}
     Supports building and linking products (GSL in this case). After
     expansion, the file will look like:
\begin{verbatim}
GSL_CFLAGS = -I$(GSL_DIR)/include
GSL_LIBS = -L$(GSL_DIR)/lib -lgsl -lgslcblas -lm
\end{verbatim}
\end{itemize}

\section{Installing \eups}
\label{AppInstalling}

If you want to play with \eups you may want to install a copy.

You can check out a copy from \code{svn} from NCSA:
\begin{verbatim}
  svn co svn://svn.lsstcorp.org/eups/trunk eups
\end{verbatim}
or to get an released version e.g.
\begin{verbatim}
  svn co svn://svn.lsstcorp.org/eups/tags/1.2.6 eups
\end{verbatim}
You can of course list available versions with
\begin{verbatim}
  svn ls svn://svn.lsstcorp.org/eups/tags
\end{verbatim}

Alternatively, grab the tarball
\begin{verbatim}
http://www.astro.princeton.edu/~act/packages/eups.tar.gz
\end{verbatim}
which is probably out of date.

Then unpack it, configure, and install.  E.g.
\begin{verbatim}
zcat eups.tar.gz | tar -xf -
cd eups
./configure --with-eups=/u/act/products
make show
make install
\end{verbatim}

The \code{make install} command will tell you to source a file
with a name such as
\begin{verbatim}
/u/act/products/eups/bin/setups.sh
\end{verbatim}
which will make \eups commands available to you; csh users should
use \code{setups.csh}.  You'll probably want to add this line to your
shell startup file (.bashrc or .tcshrc).

\subsection{Details, details...}

You can use \code{make show} to show you where things are
going to be installed:
\begin{verbatim}
$ make show
You will be installing ups in $EUPS_DIR  =  /usr/local/products/eups
Eups will look for products in $EUPS_PATH = /usr/local/products
Your EUPS database[s] will be               /usr/local/products/ups_db
Your EUPS version is                        1.2.6
Your site configuration files will be in    /usr/local/products/site
\end{verbatim}
				% $ for emacs
If you already have the environment variable \code{\$EUPS\_PATH} set,
then \code{EUPS\_PATH} will default to the old value.

You can control where files are put with the following configure options:
\begin{verbatim}
--prefix=PREFIX         install architecture-independent files in PREFIX
                        [default: /usr/local]
--with-eups=PATH        Use PATH as root for installed products
--with-eups-db=DB       Select component of path to use for EUPS_DIR;
                        "/eups" will be appended [default: first]
--with-eups_dir=DIR     Install eups into DIR/{bin,doc}
--with-setup-aliases=name1:name2  Make name1 an alias for setup, and
                        name2 an alias for unsetup
\end{verbatim}
The difference between \code{--prefix} and \code{--with-eups}
is that the former appends \code{/share} to the specified directory, to
be consistent with the standard default value, \code{/usr/local}.

If you don't explicitly choose a \code{EUPS\_DIR} with
\code{--with-eups\_dir} or \code{--with-eups-db} the value from the
environment will be adopted. If you don't have \code{EUPS\_DIR} set,
the first component of the \code{PATH} will be used, with \code{/eups}
appended.

As an alternative to
\begin{verbatim}
./configure --with-eups=/foo/bar/share
...
make install
\end{verbatim}
you can say
\begin{verbatim}
make install EUPS_PATH=/foo/bar/share
\end{verbatim}
\code{make install prefix=...} also works as an alternative to \code{--prefix=...}.
Note that \code{prefix} is ignored if you've set \code{EUPS\_PATH} either explicitly
or implicitly via an environment variable; \code{make show} is your friend.

The \code{--with-setup-aliases} option is provided for those who find the commands
`setup' and `unsetup' inelegant, or are who are concerned about the conflict with the
command \code{/usr/bin/setup} on many Linux systems.  A typical usage would be
\begin{verbatim}
configure --with-setup-aliases=activate:deactivate
\end{verbatim}

\subsubsection{Working with multiple copies of \eups}

This may only be of interest to the authors.  You can declare \eups as a full-up
\eups product in its own right, and use \code{setup eups version} to switch
between them.  To make this easier, the main Makefile allows you to say,
\code{make declare} to declare your new version.

\section{Changes}
\subsection{New features}

\eups has undergone significant enhancements recently.  Some
highlights are:

\begin{itemize}
  \item
    The addition of \code{\$EUPS\_PATH}

  \item
    The ability to specify logical expressions instead
    of simple version numbers in requirements

  \item
    Support for adding an extra delimiter at the
    start/end of a path variable (e.g. MANPATH)

  \item
    The ability to use relative paths with \code{--root}

  \item
    The ability to omit the product name when you're
    setting up with \code{--root}; e.g. \code{setup -r .}

  \item
    \code{eups distrib} can now use ``build files'' to
    build products locally; \code{sh} scripts that
    play nicely with \eups.

  \item
    \code{eups distrib} can now use scp as well as http to
    retrieve files.

  \item
    support \code{\$?\{name\}} in table files

  \item
    Don't print setup/current with \code{eups list -d}


  \item
    Support \code{eups declare -r XXX version}

  \item
    Allow version expressions in \code{eups list}

  \item
    Support \code{eups path n} to print part of a \code{EUPS\_PATH}

  \item
    Added \code{setup -C} as an alias for \code{setup -c}, for consistency with \code{eups distrib}

  \item
    Added \code{eups distrib -S noeups=True} to generate build/manifests for non-eups or non-installed products

  \item
    Allow \code{eups declare} to guess the directory given the product and version,
    e.g. \code{eups declare moby 3.1.4}.

  \item
    Don't allow a user to undeclare a setup product (as it couldn't be unsetup later)

  \item
    Support \code{eups declare -n}

  \item
    Support \code{\~} (but not \code{\~{}user}) when using -r to specify product directories;
    this only matters in table files (where the shell didn't already expand
    the \~{} for you)

  \item
    Support \code{eups list prod LOCAL:/product/dir}

  \item
    Support \code{setup --max-depth}/\code{-S} for use with \code{setup -v}.

  \item
    Add \code{eups distrib list}

  \item
    Add \code{eups undeclare --force} to undeclare products that are currently
    setup

  \item
    Add \code{eups remove} to remove installed products

  \item \code{eups uses} to list everything that depends on a given product
    % Up to date as of 2008/04/11

\end{itemize}

\subsection{Obsolete features}

\begin{itemize}
  \item The environment variable \code{\$EUPS\_PATH} used to be known
  as \code{\$PROD\_DIR\_PREFIX}. This is no longer supported.

  \item The \eups database used to be given by the environment variable \code{\$PRODUCTS}
    with a default value of \code{\$PROD\_DIR\_PREFIX/ups\_db}. This is no longer supported.
\end{itemize}

\section{\eups and autoconf/configure}
\label{autoconf}

If you're a user, you don't need to understand this section. If
you're creating new products, you may need to.

The \eups distribution includes a set of autoconf macros
in the file \file{etc/ac\_eups.m4}. Once you've arranged for
autoconf to know about this file,\footnote{e.g. by copying the
  file into your top level directory} you can write a
\file{configure.ac} file that looks something like
\begin{quote}
\obeylines\tt\small\parskip=0pt
AC\_INIT([myProduct], [X.Y], [rhl@astro.princeton.edu])
EUPS\_DEFINE\_ROOT(\${Name}: v2\_4 \$)
AC\_PROG\_CC(cc)
EUPS\_WITH\_CONFIGURE([gsl])
EUPS\_WITHOUT\_CONFIGURE([fftw3], [fftw3.h], -lfftw3f, [fftw3f,fftwf\_plan\_dft\_2d])
AC\_CONFIG\_FILES([etc/Makefile.global])
AC\_OUTPUT
\end{quote}
\footnote{The old forms with \code{UPS\_} (e.g. \code{UPS\_DEFINE\_ROOT})
  are supported for backward compatibility.}

Once you've generated a configure file (i.e. typed \code{autoconf})%
\footnote{You'll check the resulting configure file in, so users won't
  need to have autoconf on their machines}
you can say\hfil\break
\code{cd \$HOME/myProduct}\hfil\break
\code{setup gsl; setup fftw3}\hfil\break
\code{./configure --with-eups=/u/act/products --with-flavor=Linux64}\hfil\break
\code{make}\hfil\break
\code{make install}\hfil\break
\code{make declare}\hfil\break
\code{setup myProduct v2\_4}\hfil\break

You might wonder how you were supposed to know that you had to type
\code{setup gsl} and \code{setup fftw3} in order to build
\code{myProduct}. The answer, is: ``It depends''.  If you're
\code{myProduct}'s loving author, you knew that you needed
\code{gsl} as you included e.g. \code{gsl/gsl\_rng.h} in your
source. If you're not the author, then \code{myProduct} presumably
includes a properly written table file (probably called
\code{myProduct/ups/myProduct.table}) which knows about
\code{gsl} and \code{fftw3}:
\begin{verbatim}
setupRequired("fftw3")
setupRequired("gsl")
\end{verbatim}
in this case what you \textit{really} typed was:\hfil\break
\code{setup --root \$HOME/myProduct myProduct}\hfil\break
which setup \code{gsl} and \code{fftw3} for you:
\begin{verbatim}
Setting up:      fftw3               Flavor: Linux      Version: v3_0_1
Setting up:      gsl                 Flavor: Linux      Version: v1_8
\end{verbatim}

The \code{make declare} command told \eups about your newly built
product; the \code{setup myProduct v2\_4} command told the system
that you wanted to use it.

How did your \file{configure.ac} file achieve this magic?

\begin{itemize}
  \item{\code{AC\_INIT}}

    This is a standard autoconf line, but with an invalid version name (\code{X.Y}).

  \item{\code{AC\_DEFINE\_ROOT}}

    Define the \code{configure} options \code{--with-eups=path},
    \code{--with-eups-db=DB}, and \code{--with-flavor=XXX}. The
    version comes from the \code{\${Name}: v2\_4 \$} --- if the
    \code{v2\_4} were absent the value \code{cvs} would have been used
    instead.

  \item\code{AC\_PROG\_CC(cc)}

    Find the C compiler

  \item\code{EUPS\_WITH\_CONFIGURE([gsl])}

    Tell configure that we need the product \code{gsl}, and that it
    comes with a pkg-config script.\footnote{%
      I.e. a script \code{gsl-config} which accepts arguments \code{--cflags}
      and \code{--libs} to print out the options that you should pass to the
      compiler and linker to use the \code{gsl} libraries. For example,
      \code{--libs} prints \code{-I/usr/local/include} and
      \code{--cflags} prints \code{-L/usr/local/lib -lgsl -lgslcblas -lm}
      }
    In this case, it came from ups,
    but the macro also supports \code{--with-gsl=DIR}; there are
    other possibilies (see the reference manual,
    Sec. \ref{autoconfReference}).  If all goes well the macro macro sets (in the
    case of \code{gsl}) the variables \code{GSL\_CFLAGS} and \code{GSL\_LIBS}.

  \item\code{EUPS\_WITHOUT\_CONFIGURE([fftw3], [fftw3.h], -lfftw3f, [fftw3f,fftwf\_plan\_dft\_2d])}

    This macro is similar to \code{EUPS\_WITH\_CONFIGURE}, and sets
    \code{FFTW\_CFLAGS} and \code{FFTW\_LIBS}, armed with knowledge of
    \eups and  \code{--with-fftw3=DIR}.

    The difference is that this time configure has to probe the system
    to find the include files and libraries.  More specifically, it
    checks that it can find \code{fftw3.h} and that \code{-lfftw3f} provides the symbol
    \code{fftwf\_plan\_dft\_2d}.

  \item\code{AC\_CONFIG\_FILES}
  \item\code{AC\_OUTPUT}

    The standard autoconf macro to interpolate derived values
    into \file{Makefile.global}.  What does this mean?
    \XXX{Describe Makefile.global.in}
\end{itemize}


\subsubsection{A Strategy for using autoconf and \eups to Manage Layered Products}


A more complete example is:

\begin{quote}
    \obeylines\tt\small\parskip=0pt
AC\_INIT([myProduct], [X.Y], [rhl@astro.princeton.edu])
\vspace{5pt}
dnl --------- UPS directories and how to install --------------------------
\vspace{5pt}
EUPS\_DEFINE\_ROOT(\${Name}:  \$)
EUPS\_INSTALL\_DIRS
\vspace{5pt}

dnl --------- Build environment -------------------------------------------

AC\_PROG\_CC(cc)
AC\_PROG\_RANLIB

dnl --------- Products from UPS -------------------------------------------
dnl (remember to update etc/Makefile.global if you add a new product)
\vspace{5pt}
EUPS\_WITH\_CONFIGURE([gsl])
EUPS\_WITH\_CONFIGURE([pslib])
\vspace{5pt}
EUPS\_WITHOUT\_CONFIGURE([cfitsio], [fitsio.h],
                        -lcfitsio, [cfitsio,ffopen])
EUPS\_WITHOUT\_CONFIGURE([fftw3],   [fftw3.h],
                        -lfftw3f,  [fftw3f,fftwf\_plan\_dft\_2d])
EUPS\_WITHOUT\_CONFIGURE([wcslib],  [wcslib/wcslib.h],
                        -lwcs,     [wcs,wcsini])
\vspace{5pt}
AC\_CONFIG\_FILES([etc/makedefs etc/builddefs etc/installdefs])
AC\_CONFIG\_FILES([bin/eups\_import], [chmod 755 bin/eups\_import])
\vspace{5pt}
AC\_OUTPUT
\end{quote}

\section{``Transport Layers'' for \code{eups distrib}}
\label{pacman}

\pacman{} is a package used by the HEP community (e.g. Atlas) to distribute
software.  It doesn't solve the same problem as \eups (supporting
multiple simultaneous versions of the same package), but it does nicely
support building packages from source.  The home page is \code{http://physics.bu.edu/pacman/}.

An example \pacman{} script is
\begin{verbatim}
#
# Sample product installation using pacman
#
# author: RHL
# data:   2006/12/04
#
packageName('hello')
url('Foo', 'file:///dev/null')
#
# N.b. version is also encoded in directory name below
#
version('v1_0_0')
#
# Package requirements
#
platformGE("unix")
which("gcc"); which("make")
#
# Prepare to install
#
downloadUntar('/Users/rhl/LSST/Pacman-test/packages/hello-v1_0_0.tar.gz', 'HELLO_DIR')
cd('$HELLO_DIR')
cd('v1_0_0')
shell("make")
shell("make install")
\end{verbatim}
				% $ for emacs

\subsection{Using \pacman{} with \eups}

To use \pacman{}, simply specify a \pacman{} cache when running \code{eups distrib create}:
\begin{verbatim}
eups distrib -z lsst --pacman http://lsst.org/cache create hello
\end{verbatim}

The \code{eups distrib install} command is unchanged:
\begin{verbatim}
eups distrib install -r /u/lsst/products/packages/Darwin -z act hello v1_0_0
\end{verbatim}

\subsection{Using `Build Files' with \eups}
\label{buildFiles}

This isn't an integral part of eups, but it can be very useful in conjunction with \code{eups distrib}.

The work of installing a package frequently reduces to a stereotyped set of operations;
for each dependency you type:
\begin{verbatim}
    cvs co -r XXX prod1
    cd prod1
    make install
    cd ..
\end{verbatim}
followed by \code{eups declare ...} and on to the next product.  It'd
be nice not to have to type this repeatedly, especially if you have to
install on a bunch of machines that don't share an
\code{\$EUPS\_PATH}.  Fortunately, you don't have to.

One approach would be to bite the bullet and learn \pacman{} (see Appendix \ref{pacman});
another is to write simple `build files'.  The former is far more sophisticated
and bullet-proof; the latter is simpler.
\textit{Note: we may remove \pacman{} support in a future \eups release}

If you put a file \code{prod.build} in \code{prod/ups} and install it along
with the table file, \code{eups distrib create --build :} will set things up
so that a subsequent \code{eups distrib install} will copy the build file
to the new machine and execute it;  if you have a set of dependent products
they will be executed in the proper order.  By default, the products will be downloaded
and built in \code{EupsBuildDir} in a flavor subdirectory of your \code{\$EUPS\_PATH};
e.g. \code{/u/act/products/DarwinX86/EupsBuildDir} (but you can change this with
the \code{-T} flag). The build files are put in the same place, in case you want
to look at them or fix buglets (simply say \code{sh prod-1.2.3.build}).  If your
verbosity is 3 or higher, the commands will be executed with \code{-v -x} set.

At their simplest, build files could simply
be the commands that you'd type (such as those listed above); \eups will take
care of the declarations.  This isn't very satisfactory, as it requires the
build file to include the version string, and that the correct value of \code{\$CVSROOT}
be already set\footnote{This is problematic if you're getting code from a number
  of different places.}
Because \code{eups distrib} chains commands together with \code{\&\&} (to check
that the previous command succeeded) comments in build files are slightly
problematic (in particular ones at the top of your file, as \code{eups distrib}
usually preceeds your commands with some of its own while preparing to do
the distribution).  Accordingly, lines starting with \code{\#} are rewritten
to use the shell's executable comment, \code{:} instead.

This is where the \code{eups expandbuild} command comes in;  it's used to install
build files expanding \code{CVSROOT} (or \code{SVNROOT}), \code{PRODUCT}, and
\code{VERSION}.  This allows you to write generic build files such as \code{prod1.build}
\begin{verbatim}
    export CVSROOT="@CVSROOT@"

    cvs co -d @PRODUCT@-@VERSION@ -r @VERSION@ @PRODUCT@
    cd @PRODUCT@-@VERSION@

    setup -r .
    make install
\end{verbatim}
If your \code{make install} target says something like
\begin{verbatim}
      eups expandbuild -V $(VERSION) ups/prod1.build $(prefix)/ups
\end{verbatim}
the installed version (assuming that \code{\$(VERSION)} is
\code{v1\_0\_1}) becomes
\begin{verbatim}
    export CVSROOT="jeeves.astro.princeton.edu:/usr/local/cvsroot"

    cvs co -d prod1-v1_0_1 -r v1_0_1 prod1
    cd prod1-v1_0_1

    setup -r .
    make install
\end{verbatim}
and everyone's happy.  \footnote{
There's a subtlety here.  Imagine that we had a product \code{prod2}
which depended on \code{prod1}.
As we source each build file separately,
the \code{setup -r .} in \code{prod1}'s build file isn't visible by
the time that \code{prod2}'s being built (as it's run in a different shell), so
\code{prod1} isn't setup.  Even if it were, \code{prod2}
tries to setup \code{prod1} itself (as it's a dependency), which requests the \emph{current} version
of \code{prod1}.  We don't want \code{eups distrib} to always declare
products current, so what should we do?  The answer is that \code{eups distrib}
inserts explicit setup statements into the the build script
and replaces the \code{setup} with \code{setup -j}; try
running with the \code{--verbose} flag if you want to see this in action,
or simply read the installed build file.
}

We do try to check that build files are sensible (although you can skip the
checks with \code{--force};  more specifically, we look for a \code{curl},
\code{cvs}, \code{svn}, or \code{wget} command.  If you want to bypass
this check, include a comment line containing the phrase \code{Build File}
somewhere in your file, e.g.
\begin{verbatim}
# Tell eups distrib that this is a valid Build File
\end{verbatim}

\end{document}

