This page guides you through installing the LSST Science Pipelines from source with lsstsw and lsst-build. These are the same tools LSST Data Management uses to build and test the Science Pipelines.
Since lsstsw presents the Science Pipelines as a directory of Git repositories cloned from github.com/lsst, this installation method can be very convenient for developing Science Pipelines code. Other methods of installing LSST Science Pipelines software are newinstall.sh <newinstall>
and Docker <docker>
.
If you have issues using lsstsw, here are two ways to get help:
- Review the
known installation issues <installation-issues>
. - Ask a question on the LSST Community support forum.
The LSST Science Pipelines can generally be compiled on CentOS, Debian, and macOS platforms. See prereq-platforms
for information about LSST's official reference platform and build reports with other platforms.
Before you begin:
- Install prerequisites for your platform:
CentOS / RedHat <prereqs/centos>
,Debian / Ubuntu <prereqs/debian>
, ormacOS <prereqs/macos>
. - If you intend to use a Git LFS repository, like ci_hsc or afwdata,
install and configure Git LFS <git-lfs>
. - If you opt not to use the default Python environment provided by
lsstsw
you will need toinstall these Python dependencies <python-deps>
.
Begin by choosing a working directory, then deploy lsstsw
into it:
git clone https://github.com/lsst/lsstsw.git
cd lsstsw
./bin/deploy
source bin/setup.sh
For more information about the deploy
command, such as using Python 2.7 instead of Python 3, see lsstsw-about-deploy
.
From the lsstsw
directory, run:
rebuild lsst_distrib
Once the rebuild
step finishes, note the build number printed on screen. It is formatted as "bNNNN
." Tag this build as current
so that EUPS can set it up by default:
eups tags --clone bNNNN current
Finally, set up the packages with EUPS:
setup lsst_distrib
See setup
for more information.
Note
You can do more with the build
command, including building from branches of GitHub repositories. For more information:
lsstsw-about-rebuild
.lsstsw-branches
.lsstsw-rebuild-ref
.
Once the LSST Science Pipelines are installed, you can verify that it works by running a demo project <demo>
. This demo processes a small amount of SDSS data.
In every new shell session you will need to set up the Science Pipelines environment and EUPS package stack.
Run these two steps:
Activate the lsstsw software environment by sourcing the
setup.sh
script in lsstsw'sbin
directory:source bin/setup.sh
If you are running in a
csh
ortcsh
, run this set up script instead:source bin/setup.csh
Set up a
top-level package <top-level-packages>
:setup lsst_distrib
Instead of
lsst_distrib
, you can set up a different top-level package likelsst_apps
or any individual EUPS package you previously installed. Seetop-level-packages
.
lsstsw-about-deploy
.lsstsw-py2
.lsstsw-about-rebuild
.lsstsw-branches
.lsstsw-deploy-ref
.lsstsw-rebuild-ref
.
The deploy
script automates several things to prepare an LSST development environment:
- Installs Git.
- Installs Git LFS (you are still responsible for configuring it).
- Installs a Miniconda Python environment specific to this lsstsw workspace. The default Python is Python 3, but you can switch to Python 2.7 if necessary. See
lsstsw-py2
. - Installs EUPS into
eups/current/
. - Clones lsst-build, which runs the build process.
- Clones versiondb, a robot-managed Git repository of package dependency information.
- Creates an empty stack installation directory,
stack/
.
This environment, including the EUPS, Miniconda, Git, and Git LFS software, is only activated when you source the bin/setup.sh
or bin/setup.csh
scripts in a shell. Otherwise, lsstsw does not affect the software installed on your computer.
See also: lsstsw-deploy-ref
.
The lsstsw deploy
script installs Miniconda as self-contained Python environment. By default, deploy
installs a Python 3 version of Miniconda. For testing Python 2.7 compatibility, you can create an lsstsw deployment with a Python 2.7 version of Miniconda using the deploy -2
argument:
./bin/deploy -2
The rebuild
command accomplishes the following:
- Clones all Science Pipelines packages from github.com/lsst. The repos.yaml file in the https://github.com/lsst/repos repository maps package names to GitHub repositories.
- Runs the Scons-based build process to compile C++, make Pybind11 bindings, and ultimately create the
lsst
Python package. The stack is built and installed into thestack/
directory inside yourlsstsw/
work directory.
lsstsw clones repositories using HTTPS (see repos.yaml). Our guide to Setting up a Git credential helper will allow you to push new commits up to GitHub without repeatedly entering your GitHub credentials.
See also: lsstsw-rebuild-ref
.
lsstsw's rebuild
command enables you to clone and build development branches.
To build lsst_distrb
, but use the Git branch my-feature
when it's available in a package's repository:
rebuild -r my-feature lsst_distrib
Multiple ticket branches across multiple products can be built in order of priority:
rebuild -r feature-1 -r feature-2 lsst_distrib
In this example, a feature-1
branch will be used in any package's Git repository. A feature-2
branch will be used secondarily in repositories where feature-1
doesn't exist. Finally, lsstsw
falls back to using the master
branch for repositories that lack both feature-1
and feature-2
.
deploy
usage: deploy.sh [-2|-3] [-b] [-h]
-2
Install a Python 2-based Miniconda.
-3
Use a Python 3-based Miniconda (default).
-b
Use bleeding-edge conda packages.
-h
Print the help message.
rebuild
rebuild [-p] [-n] [-u] [-r <ref> [-r <ref2> [...]]] [-t <eupstag>] [product1 [product2 [...]]]
-p
Prep only.
-n
Do not run git fetch
in already-downloaded repositories.
-u
Update the repos.yaml
package index to the master
branch on GitHub of https://github.com/lsst/repos.
-r <git ref>
Rebuild using the Git ref. A Git ref can be a branch name, tag, or commit SHA. Multiple -r
arguments can be given, in order or priority.
-t
EUPS tag.