Installing on macOS

< Previous		Next >

Before You Install

Before you install Spotfire Streaming, use the following checklist to make sure each target machine matches the prerequisites.

	Read through the Release Notes for the current release to look for any late-breaking information about installing on macOS.
	If you have used StreamBase Studio on the target machine, back up your existing Studio workspace and configuration, as described below.
	Confirm that the target machine is running a supported version of macOS with the latest updates. See Supported Configurations.
	Confirm that the target machine's RAM and disk space requirements meet or exceed the minimums listed on Supported Configurations.
	Depending on where you decide to install Streaming, you may need administrator and/or sudo rights on the target machine.
	If you are running macOS 10.12 Sierra or later and you are having trouble getting StreamBase Studio to start from its application bundle, see Starting StreamBase Studio on macOS Sierra.
	The installation requirements of a JDK for command-line use are discussed in Installing a JDK.

Limitations and Differences

Spotfire StreamBase Studio is provided on macOS as a client application to allow users to develop, debug, and test StreamBase EventFlow and Spotfire LiveView applications. StreamBase installations on macOS include a local-only copy of the StreamBase Runtime for running and testing your applications locally, on the same Mac computer as Studio.

However, the Streaming Runtime is explicitly not supported for build or production deployment purposes on Apple Mac machines.

Expect the following important differences when working with StreamBase Studio on macOS compared to Studio on Windows:

It is the best practice to use a two- or three-button mouse with StreamBase Studio on macOS. macOS has strong support for two- and three-button mice based on its UNIX heritage.

In many places, StreamBase documentation directs you to right-click to open the context menu. If you are using a two-button or three-button mouse on macOS, a right-click is invoked with the right mouse button as on other platforms (or with the left mouse button if you have configured for left handed use). If you are using a trackpad, use a light two-finger tap to invoke the context menu (depending on Trackpad Preference settings), or use control+click.
StreamBase Studio supports macOS's full screen feature.
There is no Insert key on Mac keyboards, but StreamBase Studio on Windows and Linux uses Insert to add a new row in schema editor grids in Properties views and configuration editors. On macOS, use the backslash key ( \ ) for this purpose. The backslash key retains its standard meaning in other contexts, including when composing an expression in a field of the schema editor grid.
Add-on products such as the High-Performance FIX Engine install as overlays into the same location as the base Streaming kit. These packages are distributed as .archive-bin packages. On macOS, after downloading use chmod +x to be sure you can run the installer. See below for more.
StreamBase Studio keyboard shortcuts for Mac keyboards are not always explicitly called out in Streaming documentation. In general, commands documented as Ctrl+key for Windows are accomplished with command+key on macOS.
On macOS, commands on the main StreamBase Studio menu and on context menus throughout Studio show the keyboard equivalent of commands using Mac keyboard symbols and semantics.
In StreamBase Studio, command+shift+L shows a pop-up help window of all commands and their keyboard equivalents just as Ctrl+Shift+L does on Windows.
StreamBase-specific EventFlow Editor keyboard shortcuts for Insert menu commands (such as O M to place a Map operator on the canvas) all work the same on macOS as on Windows.
Some menu items are in different places in keeping with macOS standards. In particular, when Streaming documentation directs you to open Window>Preferences, on macOS open StreamBase Studio>Preferences, or use the macOS-specific keyboard equivalent command+comma.
StreamBase Studio Help opens in your system default web browser instead of opening in a separate application window as on Windows. The Help system in your browser is in Eclipse Help format with a left-side navigation panel and full search capabilities.
When you click a Show in Help link in the Properties view's Expression Quickref tab, a new browser tab opens for each click, instead of reusing an already-open Help tab as on Windows.

Back Up Existing StreamBase Workspace

If you used a previous release of StreamBase Studio on the target machine, create backup copies of your existing Studio workspace directories, before using StreamBase Studio in the current release. Save the backup copy with filenames that indicate the version number of the release you are archiving. For example, save SB-workspace-10-03-00.zip.

The default location of the StreamBase Studio workspace directory is described in Default Installation Directories. You may have specified a different directory the first time you ran StreamBase Studio.

Steps to Install Streaming on macOS

TIBCO provides a Streaming installer in standard Apple DMG (disk image) format. This installer includes a Java JDK for the exclusive use by Spotfire Streaming software.

As downloaded from the TIBCO distribution site, the Streaming DMG installer is delivered in a single file stored in zip format, with a zip file named:

SPOT_str_11.1.1_macosx_x86_64.zip

The macOS version is available for x86 64-bit only.

To install Spotfire Streaming, follow these steps:

The handling of downloaded .zip files depends on your default browser and its settings. With Safari and its default settings, the Streaming .zip file is automatically unzipped after download, leaving a DMG file with the same name pattern, but .dmg extension.

If your browser and its settings does not automatically unzip downloaded zip files, then manually extract the DMG file from its .zip container.
Double-click to open the unzipped DMG file.

Click Agree to accept the Streaming license. This opens the DMG folder on your desktop containing subfolders like the ones shown here.

Spotfire Streaming 11.1.1	The Spotfire Streaming installation folder. The inclusion of the full release number allows you to have more than one Spotfire Streaming release on your Mac at the same time (but using only one at a time). See Switching for details.
doc	Full documentation for this release in HTML format. This is a symbolic link to the `/doc` folder inside the Spotfire Streaming folder, which will be placed in your target installation folder. You can copy this folder to a public location to make Streaming documentation available to other licensed users.

As with all macOS program files, you are free to install Streaming in any standard or personal location, as long as you have write access to the folder of choice. Decide on an installation location based on the following points:
- Recommended. It is recommended to drag the Spotfire Streaming 11.1.1 folder (or Spotfire Data Streams 11.1.1 folder) to a folder named Applications in your home directory. Create the $HOME/Applications folder if it does not exist. This location is shown in examples on this page and is presumed throughout Streaming documentation. The advantages of this location are:
  - The contents of home directory Applications folders are automatically included in macOS searches for application bundles, such as when using macOS Spotlight.
  - You automatically have write rights for any folder in your home directory, and can therefore install Streaming add-on products with ease.
- Also Possible. The standard location for macOS application files is /Applications at the root of the primary disk. This location has the advantage of being standard, but the disadvantage of requiring administrator access, both to install files initially, and to install other files to the same location later. These permissions issues can complicate the installation of Streaming add-ons.
- Linux-standard. TIBCO's standard installation location on Linux is /opt/tibco. The default installation location for the add-ons that use an installer in the .archive.bin format install by default into /opt/tibco/str/11.1. You can choose to drag the TIBCO Streaming folder to /opt/tibco to keep all your TIBCO products in the same location. However, the /opt folder does not exist by default on macOS machines, and rarely has write rights for all users by default.
Drag the entire Spotfire Streaming 11.1.1 folder from the open DMG to the location you elected in the previous step. You may be prompted to enter an administrative password.
To close the DMG folder, right-click or Control-click anywhere in its blank space to invoke the context menu, and select Eject.

Post-Installation Shell Configuration

For all users who will run or develop with Spotfire Streaming on this Mac, you must configure their shell initialization files such as .bash_profile. Follow the instructions in the macOS section of the Streaming-Configured Shells page.

Installing Additional Features

For macOS, all add-on products, like adapters and StreamBase Manager, install as overlays into the base Streaming folder. The installers for these add-ons are distributed as executable .archive-bin packages, which are standard .tar.xz files packaged in a shell wrapper.

These installers for macOS have file names that match the following pattern:

SPOT_str_name_11.1.1_macosx_x86_64.archive-bin

Note

The Safari browser on macOS automatically renames downloaded .archive-bin files as a safety precaution, because it detects that these files are unrecognized shell scripts. Safari adds the .txt extension so that these files are initially treated as text files.

When the download is complete, you must manually rename these files to remove the .txt extension.

After downloading one of these files, first make it executable with the chmod command. For example, for the Spotfire StreamBase High Performance Fix Pack:

chmod +x SPOT_sb-hp-fix_11.1.1_macosx_x86_64.archive-bin

For archive-bin packages, run the shell wrapper command. If you are installing into a Streaming folder for which you do not have write privileges, run the command as root or with sudo:

cd /path/to/SPOT_sb-hp-fix_11.1.1_macosx_x86_64.archive-bin
./SPOT_sb-hp-fix_11.1.1_macosx_x86_64.archive-bin

The wrapper script displays a license file for you to agree to, then prompts for the full path to your base Streaming installation. Provide the full absolute path; you do not need to escape the spaces in the folder name. For example, enter:

/Users/sbuser/Applications/Spotfire Streaming 11.1.1

or

/Users/sbuser/Applications/Spotfire Data Streams 11.1.1

The script then unarchives its files into the STREAMBASE_HOME location you identified.

How to Start Streaming Applications

On macOS, a Streaming installation provides two GUI applications plus the command-line utilities listed in the Command Reference. Man pages are provided at the shell prompt for the command-line utilities.

The two GUI applications are named as follows on the macOS file system:

StreamBase Studio 11.1.1.app
StreamBase Manager 11.1.1.app

Double-click to start either of these .app bundles like any other Mac app.

Note

If you are running macOS Sierra or later, and double-clicking does not start the application, see Starting StreamBase Studio on macOS Sierra for some workarounds.

Note

If the File>Import Samples and Community Content dialog is empty when you first run Studio, open Preferences from the TIBCO Streaming 11.0.0 top-level menu. In the StreamBase Studio panel, use the Browse button to set the correct file system location of your Streaming installation. For example, browse to and set:

/Users/sbuser/Applications/TIBCO Streaming 11.0.0

Starting StreamBase Studio on macOS Sierra

If you double-click the StreamBase Studio icon in a Mac Finder window, but nothing happens — you probably installed Streaming on macOS 10.12 Sierra or later.

This is a known issue described on the macOS Sierra workaround page, with several workarounds available.

Switching Between Streaming Releases

Because the name of the Spotfire Streaming installation folder in ~/Applications includes the release number, you can have more than one copy of Streaming on your disk at the same time, and can switch back and forth between them to use one at a time.

The easiest way to do this is to use a symbolic link pointing to the actual Streaming installation folder, and to place the path to the symbolic link's bin directory in the PATH, as recommended in Post-Installation Shell Configuration, above.

This way, when you have two or more Streaming installations, you can quickly switch between them by re-creating the symbolic link to point to the desired version.

Uninstalling Streaming on macOS

To uninstall Streaming on macOS, just move the ~/Applications/Spotfire Streaming 11.1.1 folder (or Spotfire Data Streams 11.1.1 folder) to the Trash, and remove any symbolic links you created. Your project files in your StreamBase Studio workspace are preserved when you remove the Streaming application files.

Downgrading Streaming Releases

When you upgrade from one Streaming release to a new major release, on first run, StreamBase Studio automatically and silently upgrades the XML representation of your application files.

If you need to downgrade back to a previously used Streaming release (such as to add a feature to an existing application), the older StreamBase Studio may not recognize some of the changes made to your applications by the newer Studio.

Thus, if you anticipate returning to an older Streaming release, specify a separate workspace, and either start over with new projects in your new StreamBase Studio release, or restore your matching version-specific backup copies to the separate workspace. See above for instructions for backing up workspaces.