Omnis Technical Note TNSQ0043August 2024

Loading External macOS Libraries

For Omnis Studio 11.2 (revision 38349) and later running on macOS (intel-x64 or arm64)
By Omnis Engineering.

Overview

This Technote applies to Omnis Studio 11.2 revision 38439 and later which contains changes to the way external components such as DAMs locate third-party frameworks and libraries.

Previously, components were not strictly adhering to the rules for laying out the nested app bundles used by our components. This can cause problems when signing and verifying. It is good practice to keep all shared libraries and frameworks which a bundle relies on only within that bundle's Frameworks folder. Note that we no longer use the legacy xcomp, (jscomp & logcomp) folders within the app bundle, and all external components are now loaded from Contents/Plugins.

Runtime Load Library Paths

A runtime load library path (or RPATH) is "burnt" into an external library when it is built, but can subsequently be modified using a command line tool such as install_name_tool.

General rules are that when a DAM is using an RPATH then the dependent library can be located in one of the 4 ways:

@loader_path/../Frameworks ( the DAM bundle's Frameworks folder )
@executable_path/../Frameworks ( the Omnis.app bundle's Frameworks folder )
A DAM-specific local lib folder ( this helps to keep libraries separate and can be symbolically linked to an installation location ), i.e.
  Oracle - /usr/local/oracle/lib
  Sybase - /usr/local/sybase/lib
  PostgreSQL - /usr/local/pgsql/lib
  MySQL - /usr/local/mysql/lib
The general system /usr/local/lib folder.

If bundling database clientware within Studio or the DAM, this may require the path to the dependency to be altered ( using install_name_tool ) so it can be located within the correct load library path. Bundling and deploying clientware within Studio is also subject to the vendors licensing requirements.

Using Unsigned Libraries

Where we previously advocated adding non code signed libraries into either the Omnis.app Frameworks folder, or the DAM Framework folder, and re-signing the Omnis executable, we now recommend that each library is itself ad-hoc code signed. Once signed, such libraries will load from locations on the standard library search path, (e.g. /usr/local/lib).

With these changes in mind, the following notes apply when using specific database clients.
Show discussion for:

Notes for Oracle

For a self-signed binary distribution of Instant Client, we recommend that client libraries are copied from the install location into the /usr/local/lib folder.

For unsigned binaries- extracted from a zip file for example, these should be placed either:

inside the Omnis.app/Contents/Frameworks folder, or the DAM's Contents/Frameworks folder.
These can then be signed as part of the Omnis executable.
inside the /usr/local/lib folder. This option requires that you apply an adhoc code signature to each client library dependency.

Note that the Omnis.app/Contents/MacOS folder should not be used for client libraries, since this folder is reserved for the main Omnis executable.

Notes for Sybase

When building the freetds client library for use with the Sybase DAM, this gets signed and installed into the /usr/local/lib folder by default, and should load correctly from this location.

It should be possible to bundle the client library inside Omnis.app/Contents/Frameworks or inside the DAM's Contents/Frameworks folder, provided that the client library's dependencies can be located. The RPATHs used by the client library can be modified using the install_nme_tool command if required.

Notes for PostgreSQL

On installing the PostgreSQL admin & command line tools- from https://www.postgresql.org/download/,
the following symlink can be used to point at the installed lib folder:

ln -s /Library/PostgreSQL/16/lib /usr/local/pgsql/lib

This will allow the DAM to load the SSL-enabled version of libpq.dylib.

Alternatively, it is possible to copy the dylibs from /Library/PostgreSQL/16/lib to /usr/local/lib.

The SSL client can also be bundled with the DAM if part of a custom deployment. However, this is subject to the license terms and will require dependency paths to be modified using the install_path_tool. No custom folders should be created in the Studio tree, (e.g. lib).

Notes for MySQL

Standard installation of the MySQL client places a symlink from /usr/local/mysql, for example:

/usr/local/mysql -> mysql-9.0.1-macos14-arm64

This means that the DAM can pick the client up along that path. If bundling the client with Studio, the dependencies will likely need changing to be load from Omnis.app/Frameworks or /PlugIns/dammysql.u_xcomp/Contents/Frameworks.

Developers