EUPS for PFS¶

Overview¶

PFS software products are all stored as git repositories under https://github.com/Subaru-PFS. They are installed and run as EUPS products on a local machine.

The purpose of EUPS is to maintain multiple versions of products. If a given product depends on others, the version numbers of all are saved together.

The tool to install PFS git products into an EUPS tree is pfsinstall. Give it a list of products and git tags, and it will install them in order, using the git tag as the EUPS tag:

pfsinstall ics_config:1.4.0

After which you arrange for version 1.40 of ics_config to be used with EUPS’s setup command:

setup -v ics_config 1.4.0

Note that you had to specify the version. EUPS also maintains a “current” version, which is the one which is used if no version is specified. ``pfs_install -c `` sets the current version if you want:

pfsinstall -c ics_config:1.4.0

after which setup -v ics_config will give you version 1.40.

Since it sets up basic rules, ics_config is a bit special. Among other things it does not depend on any other products. But most PFS products do. The actor library is in the tron_actorcore product, for instance. You can chose which tron_actorcore library you build and run against. pfsinstall installs each of the product:version on its command line in order, and uses the following rules to select the other products:

if a product depends on one earlier on the command line, it will depend on the command line version:
```
pfsinstall tron_actorcore:1.7.0 ics_mcsActor:1.4.0
```
if a product depends on one which was set up before pfsinstall was invoked, it will depend on the setup version:
```
setup tron_actorcore 1.6.4
pfsinstall ics_mcsActor:1.4.0
```
if a product depends on one which has a current version, it will depend on the current version:
```
pfsinstall ics_config:1.4.0
```

Common development practice¶

A common development pattern is for a programmer to be actively working on live git versions of one or a few products, but to also use installed versions of other products. Actor programmers probably want to use the latest installed version of tron_actorcore, for instance.

One mechanism to get the right environment is to run setup -v -r . in the top-level of the git directory for your working product. This configures the git version for your product and the current versions of any dependencies. This is usually sufficient for programming on actors.

If you need to override the version of a lower-level product you can specify it and leave the others alone, with setup -j $PRODUCT $VERSION.

A couple of products are almost always left as live git versions, and should not (yet) be frozen with pfsinstall. The ics_actorkeys product is the obvious one. For that, git clone ics_actorkeys in a development directory and declare that current to EUPS (cd into the git directory, then eups declare -v -c -r . ics_actorkeys live. You can then git fetch; git rebase, etc. to get new versions.

ics_config can also be such a product. Obviously all products get tagged for production.

Common development standards¶

Please use MAJOR.MINOR.REVISION git and EUPS tags. 2.3.0, for instance. Always having all three parts is good. Change MAJOR when the external API changes in an incompatible way, or you want to highlight a large architectural change. Change REVISION for bug fixes. Make a git tag with git tag -a 1.2.3 then push it with git push -t

Git branches should be handled roughly as in the LSST branching model though we are much less formal about reviews and CI. The branch naming and merging, and the commit best-practices sections are useful.

Basic EUPS commands¶

eups list

List all eups products and versions.

eups list tron_actorcore

List all versions of a single product.

eups list -s

List the currently set up versions.

eups list -c

List the “current” versions

setup -v $PRODUCT

Sets up the “current” version of a product.

setup -v -r .

Setup the product whose top-level directory you are in.

unsetup $PRODUCT

Remove whatever changes setting up $PRODUCT made to the environment.

eups declare -c $PRODUCT $VERSION

Declare that a given version of a product is the “current” version.

eups declare [-c] -r $DIR $PRODUCT $VERSION

Declare that the given directory contains the given version of the given product. Note several things:

-r . is a common idiom.

The $DIR must contain a ups directory and a ups/$PRODUCT.table table file.

In this case, version dependencies on other products are not frozen.

Basic EUPS internals¶

For a product named $PRODUCT to be an EUPS product, the top level directory must contain a ups directory, and that must contain a $PRODUCT.table “table” file.

The table file contains instructions for modifying the process environment and for specifying dependencies on other products. The most common are:

# Prepend our bin/ directory to the PATH environment variable
pathPrepend(PATH, ${PRODUCT_DIR}/bin)

# Prepend our python/ directory to the python search path
pathPrepend(PYTHONPATH, ${PRODUCT_DIR}/python)

# Set an environment variable
envSet(MYENVVAR, 'some value')

and for dependencies:

setupRequired(tron_actorcore)
setupOptional(some_product_name)

When pfsinstall runs, it installs the product into a directory inside the $EUPS_PATH directory tree. For example,``ics_xcuActor 1.7.2`` would be put into $EUPS_PATH/Linux64/ics_xcuActor/1.7.2/. It also adds the versions of the dependencies to the table file; the installed version from the last example would be written as:

setupRequired(tron_actorcore 1.7.0)

This is how versions are permanently frozen: the executables are copied into an internal tree and the version numbers are explicitly written.

Installation from scratch¶

Prerequisites¶

Some packages are required before starting the installation. Under Debian/Ubuntu system:

apt-get install git cmake

Python 3 is also required, miniconda can be installed from <https://conda.io/miniconda.html>

EUPS installation¶

This installation is done using the bootstrap_mhs script that you can get via

wget https://github.com/Subaru-PFS/ics_config/raw/master/bin/bootstrap_mhs
bash bootstrap_mhs

Then you are invited by the bootstrap_mhs script to add the setup line in your .bashrc or execute the command line.

the bootstrap_mhs installed also the ics_config PFS package, setting up ics_config you allow you to use pfsinstall:

setup -v ics_config