Need a sw startup script and check/error messages when user forgets to run it (e.g., when they try to use RunPython.py)

[akenmorris]

Our users typically get something like this when they forget the "conda activate shapeworks" step:

ImportError: No module named termcolor

Can we add a check to our python scripts that can instead print an error message saying "please run 'conda activate shapeworks'"?

It may also be needed for running Studio.

[cchriste]

More generally, because there is more than just conda activate, so it makes more sense to provide a shapeworks_env script (or whatever we want to call it). This includes:

• adding path to the shapeworks executable(s) to PATH (important),
• adding path to lib/lib64 to LD_LIBRARY_PATH (please confirm if this is still necessary)
• starting a Jupyter server
• anything else?

This start_env script is important because people will increasingly utilize the interactive command line and/or Python API, and use batch processing scripts less.

For Studio I don’t know, but the creation of an API will be important for any future remote GUIs.

The framework API will serve as a very solid foundation for current users and for future API exposures such as MATLAB and Java (our users have expressed immediate interest in both Python and MATLAB), so we should ensure it’s accessible by providing a simple startup script.

[akenmorris]

The original part of this issue was addressed in PR #491. When the python tests run, they will give a more informative error message when conda isn't activated.

[cchriste]

We need a startsw.sh script.

1. it will...
   a) conda activate shapeworks
   b) add swbin to PATH
2. update README and other instructions to tell users to always run it first

As of today on OSX in executable branch, no LD_LIBRARY_PATH is needed for any standalone executable or Studio, so we can (with gratitude on a number of levels) avoid setting LD_LIBRARY_PATH.

Starting a potential Jupyter server and/or setting PYTHONPATH can be part of pybind work, so the script described above will be sufficient to resolve this issue.

[cchriste]

I committed a setupenv and setupenv.bat to upgrade_deps_work, but there's still a fair ways to go to get them working on their respective platforms. Issue #300 has more info about what they need to do. On OSX, there is some @rpath action interfering with being able to import the vtk module built with vtk (not installed by conda), but we're able to import it with both Windows and Linux.

[cchriste]

The setupenv script should probably be split out from the upgrade_deps branch.
As discussed in our group meeting today, please update build/install instructions on docs when this script is added.

[cchriste]

The challenge mentioned in the version of the setupenv script (and setupenv.bat for Windows) in that the directories of where the dependencies are installed as well as the build and/or install path need to be known at its time of execution. It occurs to me that this script can start as a template setupenv.in and be fleshed out by cmake as well as provided in the downloadable installation using default such as $HOME/ShapeWorks for Linux and Windows (only if using git bash?) and /Applications/ShapeWorks for OSX.

[sheryjoe]

How about those (us) building from source? aren't those paths already known when we build?

[cchriste]

Sorry, I think this issue was discussed elsewhere. We can probably create the setupenv script (and .bat) using CMake in the same way we create the TestConfiguration.h starting with TestConfiguration.h.in. Cmake fills in these macros because it knows the path to the dependencies' install and ShapeWorks build and install directories.

A downloadable user deployment is actually more difficult than a developer build because the path to their installation is less known. On OSX it will most likely be /Application/ShapeWorks/<paths to bin and studio/macos/bin>; on Windows I'm not sure; and on Linux it could be virtually anywhere. Maybe we need to provide an installer and/or setup script for users to enter these directories and create the setupenv script (we could call it startsw or something different, short and sweet and clear to the user).

[cchriste]

For Windows, a Start Menu item can be added to setup the SW environment and open a prompt.

[medakk]

Another option: for releases, conda_installs.sh(or some other install script) copies shapeworks binaries and libs to $CONDA_ENV. Then conda activate shapeworks will suffice to get shapeworks in the path

[cchriste]

Similar to Karthik's suggestion, a ShapeWorks conda package will do just that. #865

[sheryjoe]

@cchriste @akenmorris is this still an issue?

[cchriste]

Yes. I suggest we use Karthik's proposal.
One argument against this is to be able to support multiple builds on one system that share a conda environment. But I think for most users that won't be an issue.

[cchriste]

Good idea from Alan: add a shortcut to open Anaconda Prompt with location of shapeworks and ShapeWorksStudio added to the PATH, and PYTHONPATH updated to find the shapeworks library. We could also add a shortcut to just start jupyter-notebook with all these things setup.

For osx and linux, the startup script will activate conda, add necessary stuff to all the paths, and be good. No more need to have customized notebooks and use case scripts that work so hard to add things to paths. Putting things in CONDA_ENV/bin would be nice, but with potentially unknown consequences, and it wouldn't take care of everything such as ld_library_path on linux and maybe pythonpath.

[sheryjoe]

scripts to start notebook and start shell with conda activated and paths added @cchriste --- could be needed for the workshop users

[cchriste]

In summary... a handy startsw.[bat|sh] that can be a shell script for osx/linux and a shortcut on Windows that opens a shell with and runs these commands:

osx/linux:

conda activate shapeworks
export PATH=/path/to/installation\bin:$PATH

windows:
conda activate shapeworks
set PATH=x:\path\to\shapeworks\bin;%PATH%

...and create a shortcut on windows that opens a terminal (anaconda branch or git bash?) and runs this batch file.

[cchriste]

We're working towards having no need for startup scripts, but we currently don't handle non-standard installation paths (#1328), and it would still be worthwhile to provide Windows shortcuts in the ShapeWorks menu that start Jupyter notebooks and shapeworks-activated Anaconda shells.

[cchriste]

For Windows, this seems like an excellent option for installation: https://github.com/faph/NSIS-Conda-Macros
It means we need to create a conda package for ShapeWorks (including Studio).

For all platforms a conda package would be very worthwhile, including path safety, the ability to have multiple installs simultaneously (in different conda environments), and simplicity of user vs developer installation of dependencies. (we discussed this previously in other issues such as #865).

We may want to divide this into two issues: Windows installer and ShapeWorks conda package.

[cchriste]

Another option: for releases, conda_installs.sh(or some other install script) copies shapeworks binaries and libs to $CONDA_ENV. Then conda activate shapeworks will suffice to get shapeworks in the path

Exactly.

[cchriste]

As of pr #1338 RunUseCase now try/excepts to ensure that both the shapeworks executable and python module are successfully found/imported, reminding the user to conda activate and directing them to the appropriate link in the documentation for installation. No other path arguments are any longer necessary for this script or any other python import or executable access.