Oracle sqlplus and instant client on Mac OS/X without DYLD_LIBRARY_PATH

I recently needed to get sqlplus (11.2) running on a mac (10.8.2). Oracle supports this via their instant client. For basic sqlpus, you need the lite oracle instant client and oracle sqlplus instant client packages. If you try to run sqlplus after unzipping the files, you probably will see an error message similar to:

$ ./sqlplus
dyld: Library not loaded: /ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib
Referenced from: /Users/clucas/apps/instantclient_11_2/./sqlplus
Reason: image not found
Trace/BPT trap: 5

This error can be fixed using one of the following methods:

  1. Move all the executables and supporting library files to locations which are searched by default (/usr/lib and /usr/bin.)  See this stackoverflow answer.
  2. Set your DYLD_LIBRARY_PATH environment variable so that the sqlplus executable can find required oracle libraries and so that those libraries can also find their dependencies.

Both of these will work, but I didn’t really like them because (1) I’m not a fan of installing (and having to remember how to clean up) various files into /usr/* and (2) DYLD_LIBRARY_PATH can affect everything else you run.

You can use otool to see the library locations embedded in the executables and libraries. Ex:

$ otool -L sqlplus
sqlplus:
/ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib (compatibility version 0.0.0, current version 0.0.0)
/ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 (compatibility version 0.0.0, current version 0.0.0)
/ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib (compatibility version 0.0.0, current version 0.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 159.1.0)

I assume those /ade/… paths are from the machine oracle used for building the instant client software.  We can replace these with @executable_path in order to have the dynamic loader find the libraries in the same directory where the executable is found. We want to end up with something like:

$ otool -L sqlplus
sqlplus:
@executable_path/libsqlplus.dylib (compatibility version 0.0.0, current version 0.0.0)
@executable_path/libclntsh.dylib.11.1 (compatibility version 0.0.0, current version 0.0.0)
@executable_path/libnnz11.dylib (compatibility version 0.0.0, current version 0.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 159.1.0)

Assuming you also adjust the libraries in the same directory, you’ll be able to run sqlplus just by having it in your PATH.  You can run the following script in the directory where sqlplus is located.  It will change all of the oracle dynamic library references to use @executable_path instead of the /ade/… full path:

#!/bin/sh
# script to change the dynamic lib paths and ids for oracle instant client
# exes and libs

# proces all the executable files in this directory
find . -maxdepth 1 -type f \( -perm -1 -o \( -perm -10 -o -perm -100 \) \) -print | while read exe
do
    echo adjusting executable $exe
    baseexe=`basename $exe`
    otool -L $exe | awk '/oracle/ {print $1}' | while read lib
    do
        echo adjusting lib $lib
        baselib=`basename $lib`
        if [ "$baseexe" = "$baselib" ]
        then
            echo changing id to $baselib for $exe
            install_name_tool -id $baselib $exe
        else
            echo changing path id for $lib in $exe
            install_name_tool -change $lib @executable_path/$baselib $exe
        fi
    done
done

Once the script is run and it changes the libs and executables, you can just add the directory holding sqlplus to your path and run sqlplus. No need to set any other oracle environment variables like ORACLE_HOME. Here’s the whole thing:

$ mkdir example
$ cd example
/Users/clucas/apps/example
$ unzip ~/dl/instantclient-basiclite-macos.x64-11.2.0.3.0.zip 
Archive:  /Users/clucas/dl/instantclient-basiclite-macos.x64-11.2.0.3.0.zip
  inflating: instantclient_11_2/BASIC_LITE_README  
  inflating: instantclient_11_2/adrci  
  inflating: instantclient_11_2/genezi  
  inflating: instantclient_11_2/libclntsh.dylib.11.1  
  inflating: instantclient_11_2/libnnz11.dylib  
  inflating: instantclient_11_2/libocci.dylib.11.1  
  inflating: instantclient_11_2/libociicus.dylib  
  inflating: instantclient_11_2/libocijdbc11.dylib  
  inflating: instantclient_11_2/ojdbc5.jar  
  inflating: instantclient_11_2/ojdbc6.jar  
  inflating: instantclient_11_2/uidrvci  
  inflating: instantclient_11_2/xstreams.jar  
$ unzip ~/dl/instantclient-sqlplus-macos.x64-11.2.0.3.0.zip 
Archive:  /Users/clucas/dl/instantclient-sqlplus-macos.x64-11.2.0.3.0.zip
  inflating: instantclient_11_2/SQLPLUS_README  
  inflating: instantclient_11_2/glogin.sql  
  inflating: instantclient_11_2/libsqlplus.dylib  
  inflating: instantclient_11_2/libsqlplusic.dylib  
  inflating: instantclient_11_2/sqlplus  
$ export PATH=$PATH:~/apps/example/instantclient_11_2
$ sqlplus 
dyld: Library not loaded: /ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib
  Referenced from: /Users/clucas/apps/example/instantclient_11_2/sqlplus
  Reason: image not found
Trace/BPT trap: 5
$ cd instantclient_11_2/
/Users/clucas/apps/example/instantclient_11_2
$ changeOracleLibs.sh 
adjusting executable ./adrci
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./adrci
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./adrci
adjusting executable ./genezi
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./genezi
adjusting executable ./libclntsh.dylib.11.1
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing id to libclntsh.dylib.11.1 for ./libclntsh.dylib.11.1
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./libclntsh.dylib.11.1
adjusting executable ./libnnz11.dylib
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing id to libnnz11.dylib for ./libnnz11.dylib
adjusting executable ./libocci.dylib.11.1
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libocci.dylib.11.1
changing id to libocci.dylib.11.1 for ./libocci.dylib.11.1
adjusting executable ./libociicus.dylib
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./libociicus.dylib
adjusting executable ./libocijdbc11.dylib
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./libocijdbc11.dylib
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./libocijdbc11.dylib
adjusting executable ./libsqlplus.dylib
adjusting lib /ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib
changing id to libsqlplus.dylib for ./libsqlplus.dylib
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./libsqlplus.dylib
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./libsqlplus.dylib
adjusting executable ./libsqlplusic.dylib
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./libsqlplusic.dylib
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./libsqlplusic.dylib
adjusting executable ./sqlplus
adjusting lib /ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib
changing path id for /ade/b/2649109290/oracle/sqlplus/lib/libsqlplus.dylib in ./sqlplus
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./sqlplus
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./sqlplus
adjusting executable ./uidrvci
adjusting lib /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1
changing path id for /ade/b/2649109290/oracle/rdbms/lib/libclntsh.dylib.11.1 in ./uidrvci
adjusting lib /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib
changing path id for /ade/b/2649109290/oracle/ldap/lib/libnnz11.dylib in ./uidrvci
$ sqlplus

SQL*Plus: Release 11.2.0.3.0 Production on Sun Mar 3 22:38:28 2013

Copyright (c) 1982, 2012, Oracle.  All rights reserved.

Enter user-name: ^C
$ cd ..
$ sqlplus

SQL*Plus: Release 11.2.0.3.0 Production on Sun Mar 3 22:38:40 2013

Copyright (c) 1982, 2012, Oracle.  All rights reserved.

Enter user-name: ^C