MacPorts Package Installation

Quick Start

The following provides a minimal set of installation instructions to get started. For more information or if you encounter problems, please refer to the detailed sections that follow.

Currently this procedure is supported for macOS 12 to 14. Note however that binary packages are currently supported only for macOS 12 x86_64 systems. For other systems the procedure is still valid but macports will fall back to source installation. You must have sudo/root access to install the packages through macports. Contact your system administrator for that. Here we assume that sudo access has been properly configured for you in the system. Note that you might be prompted with your password.

Prerequisites that must already be installed:

Run the commands from the following steps in a terminal window:

  1. Configure the ESO repository (This step is only necessary if the ESO repository has not already been previously configured.)

    Run:

    cd /tmp
    curl https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/setup/Portfile -o Portfile
    sudo port install
    sudo port sync

  2. Install the pipelines

    The list of available top level packages for different instruments is given by:

    port list 'esopipe-*-all'

    To install all pipelines use:

    sudo port install 'esopipe-*-all'

    To install an individual pipeline use the following (This example is for X-Shooter. Adjust the port name to the instrument you require.):

    sudo port install esopipe-xshoo-all

  3. Launch pipeline front-ends: EsoReflex and EsoRex

    esoreflex
    esorex recipe data.sof

    Note that EsoReflex is automatically installed only if the requested installed pipelines have a EsoReflex workflow. See below if you want to install it explicitly.

Using the MacPorts Pipeline Repository

Users that are having problems with the above Quick Start instructions or advanced users should read the following sections. Users of laptops and workstations provided by ESO should have the repository already configured if you have a recent installation of OS X from helpdesk. Thus, you can immediately install the pipelines using the port command. If this is not the case, continue to follow these instructions to setup the repository.

The following sections indicate in more detail how you can setup MacPorts to use the repository of pipeline software provided by ESO. This installation procedure is currently only officially supported for Apple OS X 10.15 or newer.

These instructions assume that MacPorts and XCode command line tools have already been installed on your system. MacPorts should be installed into the default location /opt/local. If your installed location is different from the default one, then you must adjust the path in the instructions below to use the location of your MacPorts installation. If MacPorts is not yet installed on your system, then please first follow the instructions on the MacPorts web site (https://www.macports.org/install.php) before continuing. For XCode installation, which is itself a prerequisite for MacPorts, please refer to the Apple site (https://developer.apple.com/xcode/downloads/).

1) Configure the repository

To use ESO's MacPorts repository you must first configure it in MacPorts. The repository only needs to be configured once. Thus, you can immediately skip to the pipeline installation section if the repository configuration has already been done. Otherwise continue with the following steps.

The following sections indicate how to manually configure the repository. This should only be necessary for experienced users or for special circumstances. In most cases, you can automatically configure the repository by following the instructions in the Quick Start section.

Add the source ports

The first step is to add the URL https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/ports.tar to the file /opt/local/etc/macports/sources.conf on your host machine. One will normally need administrative rights to modify the sources.conf file.

Add the package archive

Although not strictly necessary, it is possible to significantly speed up the installation procedure by using the archived binary packages that have been prebuilt for the Apple Mac platform. To use these binary packages you should follow the instructions in this section 2 and also section 3. Alternatively if you want MacPorts to compile all pipelines from scratch, then just skip to section 4 after completing section 1. Note that MacPorts might require to compile and install the packages from source anyway, if no compatible binary packages are found in the archive. However, this process is fully transparent. You will only notice a longer installation time.

To setup the binary archive you must add the following lines to the file /opt/local/etc/macports/archive_sites.conf:

name             ESO repository
type             tbz2
prefix           /opt/local
applications_dir /Applications/MacPorts
frameworks_dir   /opt/local/Library/Frameworks
urls             https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/packages

Setup the RSA public key

One additional step is required to use the binary packages. Each package is signed with ESO's private RSA key. MacPorts will check the signature of every binary package before it tries to install it with a public key. However, MacPorts must first know about ESO's public RSA key for the check to succeed.

The public key is available from the following URL https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/eso-pubkey.pem. One should download it to your local machine. The default location to store the key file is under /opt/local/share/macports/.

Once the key file has been downloaded it must be registered with MacPorts by adding the key's path to the /opt/local/etc/macports/pubkeys.conf file.

Synchronise the repository

Once the configuration modifications mentioned in steps 1 to 3 above have been completed, you must synchronise the Portfiles. This is accomplished by running the following command in a terminal window:

sudo port sync

Note that the synchronisation may take some time. Once it is complete, you are ready to install the pipeline packages.

The sudo commands will likely prompt for a password. If that is the case, you should type in your own account's password. If the sudo command fails with a permission denied message, then you likely do not have administrative privileges on the system. Please consult your system's administrator in such a case.

2) Installing the pipelines

To check which pipeline packages are available for installation, you should run the following command:

port list esopipe*

This will bring up a full list of packages available and their most recent version numbers that would be installed.

When you have selected a package, you use the "port install" command to install it. For example, if you want to install all pipeline packages related to X-Shooter, you simply execute the following command:

sudo port install esopipe-xshoo-all

esopipe-xshoo-all is a meta package that will pull in all child packages that contain the recipe plugins, workflows and supporting tools. It is possible to pull in a more restricted subset of packages, if you know before hand exactly what you need and do not need. Consult the descriptions of the packages with the "port info" command for details about what each package contains/provides.

Note:

  • If this is the first time a EsoReflex workflow has been installed on your machine and the X11 server was not installed before, it may be necessary to logout and log back into the computer to allow X11 to initialise. You may also have to create the path ~/Library/Logs/X11 if X11 fails to start and complains about not being able to create files under that directory.
  • If the Kepler home directory ~/.kepler exists from a previous installation of EsoReflex, the cached files under there may not be compatible with the newly installed EsoReflex version. Thus, before launching the new EsoReflex for the first time, you should backup the current Kepler directory and then remove it. This is only necessary once, the first time after installation.

3) Installing EsoReflex explicitly

EsoReflex will be installed automatically if a pipeline with a workflow is requested to be installed. However it is also possible to install it explicitly with the following command:

sudo port install esoreflex

4) Running EsoReflex/EsoRex

Once installation of a pipeline is complete, you can run EsoReflex of EsoRex tools to execute the pipeline.

you can start EsoReflex with following command from a terminal window:

esoreflex

Remember: the appropriate wkf and esoreflex packages must be installed. The easiest is to simply install the gui or all packages. For example, for X-Shooter it would be esopipe-xshoo-gui or esopipe-xshoo-all.

A number of useful command line options are available for the esoreflex command. Such as the -n | -non-interactive option to run a workflow in batch mode. For more information, please see the help message by running the following:

esoreflex -help

To run EsoRex, simply call the esorex command with the name of recipe you want to execute and the set of frames:

esorex recipe data.sof

When installing the macports packages the default path to the recipe plugins works out of the box and EsoRex doesn't have to be configured in any special way. However if you have a customized $HOME/.esorex/esorex.rc configuration file, the option esorex.caller.recipe-dir might be pointing to the wrong place. In this case, set the esorex.caller.recipe-dir option to /usr/lib/esopipes-plugins or /usr/lib64/esopipes-plugins depending on whether you are in a 32 or 64 architecture. Other option is to remove $HOME/.esorex/esorex.rc if it is not neede anymore.

5) Upgrading Pipelines

Before upgrading it is recommended to get a full listing of the MacPorts packages that are currently installed on your system, especially their version numbers. This may become useful when trying to rollback an upgrade, since MacPorts is not always capable of automatically downgrading all the package dependencies to the correct previous version. Such a list can be produced with the following command (one should save the output, by piping it to a file for example):

port installed

If you have previously installed a given pipeline with these instructions and a new version has been made available by ESO, you can upgrade it using the following commands:

sudo port sync
sudo port upgrade outdated

That is the standard and safe way to upgrade the MacPorts pipeline packages. However, this will update all packages installed.

In some special cases your may want to upgrade just an individual pipeline. This is done by replacing the special outdated tag with the names of the individual packages. Note: this is not recommended for MacPorts packages unless you know what you are doing, since there is a good chance that the other pipeline packages will get broken. If you are not sure, then always upgrade all packages with the previous set of commands shown. However, for those who nevertheless need to restrict the parts of the software that is updated, the following command examples may come in handy.

To update just the X-Shooter pipeline:

sudo port upgrade esopipe-xshoo-all rdepof:esopipe-xshoo-all and outdated

To exclude upgrading 3rd party dependencies:

sudo port upgrade esopipe-xshoo-all rdepof:esopipe-xshoo-all and maintainer:'eso\.org' and outdated

If you want to upgrade all pipelines, but restrict the upgrade only to ESO supplied software:

sudo port upgrade maintainer:'eso\.org' and installed

6) Downgrading Pipelines

In some cases, it may be desirable to downgrade to a previous version of a pipeline. We assume that the ESO MacPorts repository has been setup as indicated in the previous sections. Unfortunately, because of how MacPorts works, the downgrade procedure is a bit more tricky than other package management systems, such as RPM. As a concrete example, we will show how to downgrade the X-Shooter pipeline. In all subsequent instructions, simply substitute the pipeline name or ID for the one that you are actually interested in if needed.

The first step requires deactivating the currently installed pipeline and all of its dependencies. If done manually, this has to be done in the correct order for all pipeline packages. If you do get the order wrong, do not worry, this should not break your system (unless using the force flag). You will simply get an error message and have to repeatedly try deactivate the remaining packages, as their dependent packages get deactivated.

Assuming all packages were installed for just one pipeline, the simplest way to deactivate it is with the following command:

sudo port deactivate esopipe-xshoo-all rdepof:esopipe-xshoo-all and active

This will only work if you do not have any other MacPorts packages installed that have common dependencies with esopipe-xshoo-all. If this is not the case, you will see error messages saying that MacPorts will not deactivate a package, because another one still depends on it. You will need to also deactivate all those packages that have common dependencies. This can be done in a generic manner with the more complex command indicated below. The disadvantage is that this may deactivate other pipelines or other software unrelated to ESO pipelines, which will have to be reactivated/reinstalled afterwards.

port echo esopipe-xshoo-all rdepof:esopipe-xshoo-all and active \
    | awk '{print $1}' \
    | while read N ; do \
        port echo "$N" rdependentof:"$N" and active ; \
      done \
    | awk '{print $1}' \
    | sort -u \
    | xargs sudo port deactivate

If you know that certain common dependencies do not need to be downgraded, then you will have to manually deactivate only those packages you actually want to downgrade, with multiple invocations of the port deactivate command. You may want to also refer to the port command's manpage for details about package selection patterns that can help you with this. In addition, it will be useful to see the list of pipeline dependencies when making your decisions about what packages to deactivate. This is done by run the following command:

port rdeps esopipe-xshoo-all

Alternatively you may just want a list of active dependencies:

port echo rdepof:esopipe-xshoo-all and active

Or you may only want the list of active dependencies provided ESO:

port echo rdepof:esopipe-xshoo-all and active and maintainer:'eso\.org'

Once all packages that should be downgraded are deactivated, the next step is to downgrade the 3rd party dependencies provided my MacPorts itself. If there is not need to downgrade the non-ESO packages, you can skip ahead to the section dealing with the ESO supplied dependencies. 3rd party dependencies are handled differently to those supplied by ESO. More detailed instructions are provided in the MacPorts online documentation. But in summary, one first needs to get a list of all dependencies not maintained by ESO:

port echo rdepof:esopipe-xshoo-all and not maintainer:'eso\.org'

From all of these you must select the ones that you have to downgrade. At this point, the full listing of installed MacPorts packages that you made before the upgrade you are trying to roll back will come in handy (see the upgrading pipelines section). This package subset will effectively be those that have more than one version already installed or that have the wrong version installed compared to your old package listing.

Then for every package name that should be downgraded, one needs to activate the old version if still installed. Using cfitsio as an example:

sudo port activate cfitsio @3.340

Otherwise, if the older version was not installed, one needs to execute commands similar to the following:

svn export -r {revision} https://svn.macports.org/repository/macports/trunk/dports/{category}/{portname}
cd {portname}
sudo port install

Where {revision} should be replaced by the appropriate historical Subversion revision number, found by querying the Subversion repository and commit logs. {category} must be the package's category and {portname} the package's name.

Next the ESO packages can be handled. This requires updating the MacPorts configuration file /opt/local/etc/macports/sources.conf. Open the file for editing and comment out the following URL by prepending the # character to the line:

https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/ports.tar

Also append the following URL to /opt/local/etc/macports/sources.conf (where {date} must be replaced with a directory name with the format YYYY-MM-DD):

https://ftp.eso.org/pub/dfs/pipelines/repositories/stable/macports/archive/{date}/ports.tar

You will have to manually navigate to the archive path on the FTP site to see the valid directories for {date}, and select the appropriate one.

Once the MacPorts configuration file is updated, you need to synchronise the repositories and install the earlier pipeline version using the following commands:

sudo port sync
sudo port install esopipe-xshoo-all

Later, when you want to upgrade to the latest packages again, you will have to revert the changes made to the /opt/local/etc/macports/sources.conf file and resynchronise the repositories.

Reminder: you may also have to reactivate/reinstall other pipelines or 3rd party MacPorts packages that were deactivated during this downgrade procedure.

7) Removing Pipelines

When you no longer need a pipeline you can remove it with the following command:

sudo port uninstall --follow-dependencies esopipe-xshoo-all

You may also find the --follow-dependents option useful in some circumstances, where you want to remove only certain packages and those that depend on it. See the port manpages for more details.

8) Installing Individual Components

Installing pipelines with the top level meta packages, for example esopipe-xshoo-all for X-Shooter, will typically consume a large amount of disk space because it installs all standard components of the pipeline. In some cases you may only be interested in a subset of the pipeline's components. Taking X-Shooter as an example again, to install just the recipe plugins you can run the following command:

sudo port install esopipe-xshoo-recipes

It is possible to get a listing of all available packages for a specific pipeline. For example by using the following command:

port list esopipe-xshoo*

To help decide which packages are most relevant, some information about each individual package is available with the following command:

port list esopipe-xshoo-recipes

9) Removing Individual Components

In some cases it is interesting to remove individual components of the pipeline. For instance, after installing the esopipe-xshoo-all package it has been decided that the demo data is no longer needed and can be removed. The following command would do the job:

sudo port uninstall esopipe-xshoo-datademo

Take into account that some components depend on others, and is therefore not possible to remove individually some components. For instance, the esopipe-xshoo-recipes depend on the cpl component.

Trouble-shooting

This section contains some solutions and workarounds for known problems that you may face when using the repository.

Fits viewer missing when running EsoReflex

When running EsoReflex and attempting to inspect a FITS file you might see the following error message:

Cannot run program "fv": error=2, No such file or directory

This happens because the fv program is either not installed on your system or not visible. If fv is not installed then download it from the HEASARC webpage and follow the installation instructions for MacOS/OSX provided there. The following paragraphs will assume that you have installed fv as recommended into the Applications folder and the fv binary can be found under /Applications/fv.app/Contents/MacOS/.

Once fv is correctly installed the esoreflex program needs to be made aware of where to find it. In essence this means that the binary should exist under one of the locations in the system PATH. However, the most straight forward solution is to use a customised configuration file for esoreflex. If you do not already have a file called ~/.esoreflex/esoreflex.rc then create one with the following command:

esoreflex -create-config

Next, edit ~/.esoreflex/esoreflex.rc and change the parameter esoreflex.path to contain the path where the fv binary can be found. In our example the modified line in the configuration should look as follows:

esoreflex.path=/opt/local/bin:/Applications/fv.app/Contents/MacOS

You must then restart all EsoReflex instances.

Esorex reports issue with recipe initialization

Due to a bug in the cfitsio package provided by macports, there might be issues installing a pipeline that was compiled with a previous version of cfitsio. The execution of esorex usually gives the following error:

[ERROR] esorex: Init of recipe failed . . .

Other typical message looks like this:

ERROR: Mismatch in the CFITSIO_SONAME value in the fitsio.h include file
that was used to build the CFITSIO library, and the value in the include file
that was used when compiling the application program:
Version used to build the CFITSIO library = 5
Version included by the application program = 1550439912

As a workaround, the pipeline can be installed from source. For that, uninstall first the installed pipeline (here Xshooter as an example):

# sudo port uninstall --follow-dependencies esopipe-xshoo-all

and install the pipeline again from source:

# sudo port -s install esopipe-xshoo-recipes
# sudo port install esopipe-xshoo-all

This cause of the problem is a wrong patch in the cfitsio Portfile in macports which has been reported upstream (https://trac.macports.org/ticket/51645).

3rd party library problems

The pipeline software relies on a number of 3rd party libraries, such as Cfitsio, FFTW, WCSLIB and GSL. These are provided directly by the MacPorts system and are maintained independently from the pipeline packages themselves. In some cases, the MacPorts maintainers of these libraries might inadvertently upgrade to an incompatible version, before ESO has a chance to fix and update the pipeline packages. This may result in a compilation failure during installation. In such cases, one should downgrade/reactivate the previous 3rd party library version, before the upgrade was made. Detailed instructions for such a downgrade are provided in the MacPorts online documentation.

Interactive windows fail with missing DISPLAY variable

The interactive windows for a number of pipelines rely on X11 support rather than the native Apple OS X window manager. X11 is installed automatically via MacPorts when installing a pipeline package that uses EsoReflex. However, the first time after a fresh installation, the X11 system needs to initialise properly. If you installed a pipeline, then tried to run its EsoReflex workflow with interactive windows enabled, and see an error message saying the DISPLAY environment variable is not set, it is likely that X11 has not been initialised for the session.

The solution is to simply log out completely from the system, specifically out of any GUI window sessions. Then just log back in as normal. You should now be able to see the interactive windows properly for every subsequent launch of the esoreflex command.

Setting esoreflex.library-path in esoreflex.rc is not working

From OS X 10.11 the System Integrity Protection (SIP) feature is enabled by default. This prevents the DYLD_LIBRARY_PATH environment variable from being inherited by child processed, as explained in the Apple documentation. Therefore setting the esoreflex.library-path variable in the esoreflex.rc configuration file to append variables to DYLD_LIBRARY_PATH will not work. The only workaround is to disable the SIP feature in the operating system. Refer to the Apple documentation for further details.

FTP problems

In some cases you may find that the installation procedure times out when transferring files form the FTP server. In particular for wcslib. If this is the case, it is possible there is an incorrectly configured or incompatible firewall/NAT between your host machine and the FTP server. In such a case, changing the default fetch.use_epsv flag in MacPorts from yes to no may help. This flag can be modified with the following command run in bash:

sudo sed -i -e 's|fetch\.use_epsv[[:space:]]*"yes"|fetch\.use_epsv "no"|' /opt/local/libexec/macports/lib/port1.0/portfetch.tcl

Only perform this modification if you actually experience this problem and it actually helps, otherwise you may end up with IPV6 problems instead.

To undo the modification you need to change the fetch.use_epsv flag from no to yes. This can be achieved with the following command run in bash:

sudo sed -i -e 's|fetch\.use_epsv[[:space:]]*"no"|fetch\.use_epsv "yes"|' /opt/local/libexec/macports/lib/port1.0/portfetch.tcl