From 4e0ace32eeefdd89f1f79ee5425496c278908d18 Mon Sep 17 00:00:00 2001
From: Ross Beyer <rbeyer@rossbeyer.net>
Date: Mon, 13 Apr 2020 13:03:38 -0700
Subject: [PATCH] Instructions for using conda packages in different
environments (#3835)
* Added instructions for using conda packages in different environment
than ISIS.
* Fixed typos.
* Changes from PR discussion with Jay.
* Typo fixes (why can't I ever just do one commit?) and ISIS3 cleanup.
* More typos ... grr.
* Spelling fix.
* Changes suggested by Jesse.
---
README.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 158 insertions(+), 25 deletions(-)
diff --git a/README.md b/README.md
index 83f988045f..c51c3eb33f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# ISIS3
+# ISIS
[](https://gitter.im/USGS-Astrogeology/isis3_cmake?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://astrodiscuss.usgs.gov/)
@@ -29,9 +29,9 @@ We maintain a list of frequently encountered questions and issues. Before openin
## Installation
-This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0)+ through conda.
+This installation guide is for ISIS users interested in installing ISIS (3.6.0)+ through conda.
-### ISIS3 Installation With Conda
+### ISIS Installation With Conda
1. Download either the Anaconda or Miniconda installation script for your OS platform. Anaconda is a much larger distribtion of packages supporting scientific python, while Miniconda is a minimal installation and not as large: [Anaconda installer](https://www.anaconda.com/download), [Miniconda installer](https://conda.io/miniconda.html)
2. If you are running on some variant of Linux, open a terminal window in the directory where you downloaded the script, and run the following commands. In this example, we chose to do a full install of Anaconda, and our OS is Linux-based. Your file name may be different depending on your environment.
@@ -44,19 +44,19 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0
3. If you are running Mac OS X, a pkg file (which looks similar to Anaconda3-5.3.0-MacOSX-x86\_64.pkg) will be downloaded. Double-click on the file to start the installation process.
4. After the installation has finished, open up a bash prompt in your terminal window.
-5. Next setup your Anaconda environment for ISIS3. In the bash prompt, run the following commands:
+5. Next setup your Anaconda environment for ISIS. In the bash prompt, run the following commands:
- #Create a new conda environment to install ISIS3 in
- conda create -n isis3 python=3.6
+ #Create a new conda environment to install ISIS in
+ conda create -n isis python=3.6
#Activate the environment
#Depending on your version of Anaconda use one of the following:
#Anaconda 3.4 and up:
- conda activate isis3
+ conda activate isis
#Prior to Anaconda 3.4:
- source activate isis3
+ source activate isis
#Add the following channels to the environment
conda config --env --add channels conda-forge
@@ -77,7 +77,7 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0
conda config --env --add channels usgs-astrogeology
-6. The environment is now ready to download ISIS3 and its dependencies:
+6. The environment is now ready to download ISIS and its dependencies:
conda install -c usgs-astrogeology isis
@@ -89,7 +89,7 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0
7. Finally, setup the environment variables:
- #Execute the ISIS3 variable initialization script with default arguments.
+ #Execute the ISIS variable initialization script with default arguments.
#This script prepares default values for: $ISISROOT, $ISIS3DATA, $ISIS3TESTDATA
python $CONDA_PREFIX/scripts/isis3VarInit.py
@@ -100,10 +100,143 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0
python $CONDA_PREFIX/scripts/isis3VarInit.py --data-dir=[path to data directory] --test-dir=[path to test data directory]
- More information about the ISIS3DATA environment variable and the ISIS3 Data Area can be found [here]("#The-ISIS3-Data-Area"). Now everytime the isis3 environment is activated, $ISISROOT, $ISIS3DATA, and $ISIS3TESTDATA will be set to the values passed to isis3VarInit.py. This does not happen retroactively, re-activate the isis3 envionment with one of the following commands:
+ More information about the ISIS3DATA environment variable and the ISIS Data Area can be found [here]("#The-ISIS-Data-Area"). Now everytime the isis environment is activated, $ISISROOT, $ISIS3DATA, and $ISIS3TESTDATA will be set to the values passed to isis3VarInit.py. This does not happen retroactively, re-activate the isis envionment with one of the following commands:
+
+ for Anaconda 3.4 and up - conda activate isis
+ prior to Anaconda 3.4 - source activate isis
+
+
+### Practical Usage with other conda packages
+
+If you don't use conda for anything else on your computer, you can
+skip this section.
+
+If you use conda to install other packages, you may run into
+difficulties with adding the isis conda package to those environments
+or adding other conda packages to the isis environment you just
+created above. This is because the isis conda package pins a number
+of requirements that may clash with other packages.
+
+At this time, we recommend creating the isis environment as detailed
+above, and then not adding any other conda packages to it. This
+is similar to the best practice usage of not adding any conda
+packages to your 'base' conda environment.
+
+Instead, when you need to have a conda environment with other
+packages that also needs to be able to run ISIS programs, we have
+two different options. In both cases, we'll assume that you create
+a new environment called 'working' (but it could be named anything)
+that you want to add some conda packages to, but from which you
+also want ISIS access.
+
+The first step is to create 'working' and add whatever conda packages you want.
+
+#### Easy mode, with stacking
+
+1. `conda activate isis`
+
+2. `conda activate --stack working`
+
+That's it. Told you it was easy.
+
+This activates the isis environment, gets it all set up, and
+then it 'stacks' the new working environment on top of it. To get
+out, you'll have to `conda deactivate` two times to get out of
+`working` and then out of `isis`.
+
+
+#### Harder mode, with activation script hacking
+
+The above stacking situation may have issues if you have a particularly
+complicated set of packages or other dependencies. The idea here is that
+the only thing you *really* need in your 'working' environment are
+the ISIS environment variables and the path to the ISIS executables.
+
+If the above paragraph sounded like gibberish, please seek help
+from your system administrator or local computer guru.
+
+And we can do this via customizations in the conda environment's
+activate.d/ and deactivate.d/ directories. Adding these things can
+also be done manually from the command line, but encoding them in
+the activate.d/ and deactivate.d/ scripts is handy.
+
+1. Create your conda environment however you like, adding whatever
+packages you need. If you were reading the directions above, you've
+already done this.
+
+2. Locate the path to your conda environments:
+
+ conda activate
+ echo $CONDA_PREFIX
+ conda deactivate
+
+ You'll probably get a directory that is in your home directory and
+ is named `anaconda3` or `miniconda3` or something similar. For the
+ rest of this set of instructions, we'll refer to it as `$HOME/anaconda3`
+ to represent a directory named `anaconda3` in your home directory, but
+ this should be whatever you get from the above echo command.
+
+3. Locate the path to your ISIS conda environment:
+
+ conda activate isis
+ echo $CONDA_PREFIX
+ conda deactivate
+
+ This should probably be `$HOME/anaconda3/envs/isis`. You can see
+ that it starts with whatever you got from step 1, and ends in the
+ name of your isis environment, if you followed the installation
+ instructions above, you called that environment 'isis'.
+
+ You can do the same thing to find the path to your new 'working'
+ environment, but in this example, it will be at
+ `$HOME/anaconda3/envs/working`.
+
+4. Copy the ISIS activation and deactivation scripts to your new
+environment. Please note that the directory names in the instructions
+below are based on how you installed conda and what you named the
+'isis' environment and the 'working' environment. You may *not* be
+able to just copy and paste these instructions directly, they are
+an example. Likewise, if your shell doesn't take the bash syntax
+in the .sh files, then you may need to select one of the other
+`env_vars.*` files in the isis directories.
+
+ cd $HOME/anaconda3/envs/
+ mkdir -p working/etc/conda/activate.d/
+ mkdir -p working/etc/conda/deactivate.d/
+ cp isis/etc/conda/activate.d/env_vars.sh working/etc/conda/activate.d/env_vars.sh
+ cp isis/etc/conda/deactivate.d/env_vars.sh working/etc/conda/deactivate.d/env_vars.sh
+
+5. Edit the copied activation file in
+`$HOME/anaconda3/envs/working/etc/conda/activate.d/` to add the
+ISIS executable directory to the path, by adding this line at the
+end:
+
+ export PATH=$PATH:$ISISROOT/bin
+
+ Or whatever is appropriate for your shell if you aren't using
+ the .sh file. No matter how you do it, it is important that
+ you add `$ISISROOT/bin` to the end of the current path in your
+ working environment, and not at the beginning.
+
+
+6. Edit the copied deactivation file in
+`$HOME/anaconda3/envs/working/etc/conda/deactivate.d/` to remove
+the path, by adding this line at the end:
+
+ export PATH=`echo -n $PATH | awk -v RS=: -v ORS=: '/isis/ {next} {print}' | sed 's/:$//'`;`
+
+ Or whatever is appropriate for your shell if you aren't using the
+ .sh file. If your ISIS environment is not called `isis`, then you
+ need to replace that part in the awk line above. You can look in
+ the `activate.d/env_vars.sh` file to see what it should be.
+
+Adding the lines in steps 5 and 6 manually adds the 'bin/'
+directory of the ISIS environment to your path (step 5), and then
+manually removes it (step 6) on deactivation. If you are using
+some other shell, you may need to use a different syntax to add and
+remove these elements to and from your path.
+
- for Anaconda 3.4 and up - conda activate isis3
- prior to Anaconda 3.4 - source activate isis3
### Updating
@@ -120,14 +253,14 @@ This installation guide is for ISIS3 users interested in installing ISIS3 (3.6.0
### Operating System Requirements
-ISIS3 runs on many UNIX variants. ISIS does not run natively on MS Windows, although it has been successfully run on Windows 10 using the Windows Subsystem for Linux (WSL). Instructions for doing this can be found [here](http://planetarygis.blogspot.com/2017/07/isis3-on-windows-10-bash.html). The UNIX variants ISIS3 has been successfully built on are:
+ISIS runs on many UNIX variants. ISIS does not run natively on MS Windows, although it has been successfully run on Windows 10 using the Windows Subsystem for Linux (WSL). Instructions for doing this can be found [here](http://planetarygis.blogspot.com/2017/07/isis3-on-windows-10-bash.html). The UNIX variants ISIS has been successfully built on are:
- Ubuntu 18.04 LTS
- Mac OS X 10.13.6 High Sierra
- Fedora 28
- CentOS 7.2
-ISIS3 may be run on other Linux or macOS operating systems then those listed above, but it has not been tested and is not supported.
+ISIS may be run on other Linux or macOS operating systems then those listed above, but it has not been tested and is not supported.
### Hardware Requirements
@@ -135,12 +268,12 @@ Here are the minimum hardware requirements
- 64-bit (x86) processors
- 2 GB RAM
-- 2.5 GB of disk space for ISIS3 binaries
-- 10 GB to 510 GB disk space for ISIS3 data
+- 2.5 GB of disk space for ISIS binaries
+- 10 GB to 510 GB disk space for ISIS data
- 10 GB to many TB disk space for processing images
- A quality graphics card
-To build and compile ISIS3 requires following the instructions listed below, which are given on the GitHub wiki page for the ISIS3 project:
+To build and compile ISIS requires following the instructions listed below, which are given on the GitHub wiki page for the ISIS project:
- [Getting Started With GitHub](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#getting-started-with-github)
- [Building ISIS3 With cmake](https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3)
@@ -155,11 +288,11 @@ To build and compile ISIS3 requires following the instructions listed below, whi
### Ancillary Data
-Many ISIS3 applications require ancillary data. For example, ingestion applications require translation tables to convert labels, calibration applications require flat files to do flat field correct, and map projection applications require DTMs to accurately compute intersections. Due to its size, this data is stored in a separate directory called the ISIS3 Data Area. Any location can be used for the ISIS3 Data Area, the software simply requires that the ISIS3DATA environment variable is set to its location.
+Many ISIS applications require ancillary data. For example, ingestion applications require translation tables to convert labels, calibration applications require flat files to do flat field correct, and map projection applications require DTMs to accurately compute intersections. Due to its size, this data is stored in a separate directory called the ISIS Data Area. Any location can be used for the ISIS Data Area, the software simply requires that the ISIS3DATA environment variable is set to its location.
### Structure of the ISIS3 Data Area
-Under the root directory of the ISIS3 Data Area pointed to by the ISIS3DATA environment variable are a variety of sub-directories. Each mission supported by ISIS3 has a sub-directory that contains mission specific processing data such as flat files and mission specific SPICE. There are also data areas used by more generic applications. These sub-directories contain everything from templates to test data.
+Under the root directory of the ISIS Data Area pointed to by the ISIS3DATA environment variable are a variety of sub-directories. Each mission supported by ISIS has a sub-directory that contains mission specific processing data such as flat files and mission specific SPICE. There are also data areas used by more generic applications. These sub-directories contain everything from templates to test data.
### Size of the ISIS3 Data Area
@@ -167,9 +300,9 @@ If you plan to work with data from all missions, then the download will require
### Full ISIS3 Data Download
-The ISIS3 Data Area is hosted on rsync servers and not through conda channels like the ISIS3 binaries. This requires using the rsync command from within a terminal window within your Unix distribution, or from within WSL if running Windows 10. Downloading all mission data requires over 520 GB of disk space. If you want to acquire only certain mission data [click here](#Mission-Specific-Data-Downloads). To download all ISIS3 data files, continue reading.
+The ISIS Data Area is hosted on rsync servers and not through conda channels like the ISIS binaries. This requires using the rsync command from within a terminal window within your Unix distribution, or from within WSL if running Windows 10. Downloading all mission data requires over 520 GB of disk space. If you want to acquire only certain mission data [click here](#Mission-Specific-Data-Downloads). To download all ISIS data files, continue reading.
-To download all ISIS3 data, enter the following commands in the location where you want to install the ISIS3 Data Area:
+To download all ISIS data, enter the following commands in the location where you want to install the ISIS Data Area:
cd $ISIS3DATA
rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data .
@@ -178,9 +311,9 @@ To download all ISIS3 data, enter the following commands in the location where y
> Note: The above command downloads all ISIS data including the required base data area and all of the optional mission data areas.
-### Partial Download of ISIS3 Base Data (Required)
+### Partial Download of ISIS Base Data (Required)
-The base data area is separate from the source code. This data area is crucial to ISIS3 and must be downloaded. To do that run the following commands:
+The base data area is separate from the source code. This data area is crucial to ISIS and must be downloaded. To do that run the following commands:
cd $ISIS3DATA
rsync -azv --delete --partial isisdist.astrogeology.usgs.gov::isis3data/data/base .
@@ -376,4 +509,4 @@ If you are looking for ISIS2, please [refer to the ISIS 2 Installation Guide](ht
### How do I install ISIS3.5.2 or earlier?
-If you are looking for a version of ISIS3 prior to 3.6.0, please [refer to the Legacy ISIS3 Installation Guide](https://isis.astrogeology.usgs.gov/documents/LegacyInstallGuide/index.html) for instructions on downloading and installing ISIS3, versions prior to 3.6.0.
+If you are looking for a version of ISIS prior to 3.6.0, please [refer to the Legacy ISIS3 Installation Guide](https://isis.astrogeology.usgs.gov/documents/LegacyInstallGuide/index.html) for instructions on downloading and installing ISIS, versions prior to 3.6.0.
--
GitLab