Dylibs fix.m

An m-file function used in support of creating a MacOS X App bundle.

## Copyright (C) 2012 Ben Abbott
## 
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 3 of the License, or
## (at your option) any later version.
## 
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
## 
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn {Function File} fix_dylibs (@var{exebin}, @var{libdir}, @var{dryrun})
## Make the executable and dynamic libraries relocatable. The inputs are;
##
## @table
## @item @var{exebin}
## The full file name of the executable binary for the App bundle.
## The default is @code{bin/Octave-3.7.0+};
## @item @var{libdir}
## The full path to the directory containing the App bundle's dynamic
## libraries.  The default is @code{lib}.
## @item @var{dryrun}
## If @var{true}, the @code{install_name_tool} commands are printed to
## the command line and are not executed (i.e. the install names and paths
## to the dependent libraries are not changed).  The default is @var{true}.
## @end table
##
## Using @code{install_name_tool} the portion of the built in
## dynamic library paths external to the App bundles are replaced with
## the token @code{@@executable_path}.
## Ths will modify the paths in both the @var{exebin} and the the dynamic
## libraries and allow the application to be relocated with no risk
## that the binary executable and libraries are unable to locate the
## dynamic libraries they depend upon.
##
## In addition to correcting the location information for the dependent's
## of @var{exebin}, the @var{libdir} is searched recursively to locate all
## dynamic libraries present in the App bundle.  Both their install names
## and the locations of their dependents will also be fixed.
##
## Using the default, this script expects to find a @code{bin} and
## @code{lib} directory in the current working directory.  
##
## @center BACKGROUND INFORMATION BELOW @end center
##
## MacOS X supports the use of tokens to permit executable files and dynamic
## libraries to be relocated to a different path.  This is an essential
## feature for MacOS X's App bundles.  The three tokens supporte are below;
##
## @table @code
## @item @@executable_path
##   This token expands to the path of the executable application that is
##   loading the dynamic library.  Using this toek requires the location of
##   the library remains fixed relative to the binary executable.
## @item @@loader_path
##   This token expands to the path of binary loading the dynamic library.
##   The loader may be the binary application, a library, or a framework.
##   Using this token requires the location of the library remains fixed
##   relative to the loader.
## @item @@rpath
##   Searches a list of locations for the dynamic library.  @rpath is the
##   most flexible of these tokens.  When set in the install name of a
##   dynamic library, that library can be used in any applications,
##   frameworks or any other type of project without needing further
##   modification.  The @var{rpath} may be modified for a binary by using
##   the @code{otool} utility.
##
##   @example
##   otool -add_rpath @var{path_to_binary} @var{name_of_binary}
##   @end example
##
##   The @var{path_to_binary} may use either the @code{@@executable_path}
##   or @code{@@loader_path} tokens.
##
##   As it isn't clear how to check the entires of the @code{@@rpath} token.
##   Is it possible that dynamic libraries built by package managers
##   such as MacPorts or Fink have @code{@@rpath} entries to 
##   @code{/opt/loca/lib/..} or @code{/sw/lib/...}?  As a precaution, this
##   token can be avoided.
## @end table
##
## A hypothetical bundle, @var{my_exe.app}, will be used for demonstration.
## In this example, @var{my_exe} depends upon @var{libfoo.dyld} and
## @var{libbar.dyld}, and @var{libfoo.dyld} also depends upon @var{libbar.dyld}.
##
## @example
## ex.app/Contents/Resources/bin/@var{my_exe}
## ex.app/Contents/Resources/lib/@var{libfoo.dyld}
## ex.app/Contents/Resources/lib/@var{libbar.dyld}
## @end example
##
## The @code{@@executable_path} token represents the path to the executable, @var{my_exe}.
##
## @example
## @@executable_path = @code{/Applications/ex.app/Contents/Resources/bin}
## @end example
##
## To properly relocate the dynamic libraries the install name ID for each
## dynamic library must be set correctly, and the binary files which depend
## upon dynamic libraries need to be told where to find them.
##
## For this hypothetical example, and using the @code{@@executable_path} token,
## the commands below will properly relocate the dynamic libraries and fix their
## install name IDs.
##
## @example
## install_name_tool -change /Applications/ex.app/Contents/Resources/lib/@var{libfoo.dyld} \
##                           @@executable_path/../lib/@var{libfoo.dyld} \
##                           bin/@var{my_exe}
## install_name_tool -change /Applications/ex.app/Contents/Resources/lib/@var{libbar.dyld} \
##                           @@executable_path/../lib/@var{libbar.dyld} \
##                           bin/@var{my_exe}
## install_name_tool -change /Applications/ex.app/Contents/Resources/lib/@var{libbar.dyld} \
##                           @@executable_path/../lib/@var{libbar.dyld} \
##                           ../lib/@var{libfoo.dyld}
## install_name_tool -id @@executable_path/../lib/@var{libfoo.dyld} lib/@var{libfoo.dyld}
## install_name_tool -id @@executable_path/../lib/@var{libbar.dyld} lib/@var{libbar.dyld}
## @end example
##
## The @code{otool} utility may be used check the install name of a binary
## application. Replace @var{binary_name} with the actual path and name of
## the binary.
##
## @example
## otool -D @var{binary_name}
## @end example
##
## The @code{otool} utility may be also be used check the locations of its
## dependent libraries.  Again, replace @var{binary_name} with the actual path
## and name of the binary.  The first entry is the binary's install name.
##
## @example
## otool -L @var{binary_name}
## @end example
##
## @end deftypefn

## Author: Ben Abbott <bpabbott@mac.com>
## Created: 2012-06-26

## NOTE - It is possible to avoid a recursive search down the directory tree, but this would
##        require that the bundle's directory tree accurately represent the part above the
##        @executable_path.  With the approach used, the stored dylib locations are not
##        relevant.  Thus, their paths can be mangled in any way and this script will fix it.

function dylibs_fix (BINARY = "bin/octave-3.7.0+", LIBDIR = "lib", dryrun = true)
  if (ischar (BINARY))
    BINARY = {BINARY};
  endif
  only_binary = false;
  pager_state(1) = page_output_immediately (true);
  pager_state(2) = page_screen_output (false);
  unwind_protect
    dylibs = dylibs_find (LIBDIR);
    [~, n] = sort ({dylibs.name});
    dylibs = dylibs (n);
    printf ("%d dynamic libraries found.\n", numel (dylibs));
    executable_path = file_location (BINARY{1});
    for b = 1:numel(BINARY)
      cmds = fix_deps (executable_path, BINARY{b}, dylibs);
      for c = 1:numel(cmds)
        printf ("%s", cmds{c})
        [status, output] = system (cmds{c});
        if (! status == 0)
          error (output);
        endif
      endfor
    endfor
    if (! only_binary)
      for d = 1:numel(dylibs)
        full_name = strcat (dylibs(d).location, filesep (), dylibs(d).name);
        if (! dylibs(d).islink)
          ## Don't fix symbolic links
          cmd = fix_id (executable_path, full_name);
          cmds = fix_deps (executable_path, dylibs(d).name, dylibs);
          cmds = [cmd;cmds];
          if (dryrun)
            printf ("%s", cmds{:})
          else
            for c = 1:numel(cmds)
              printf ("%s", cmds{c})
              [status, output] = system (cmds{c});
              if (! status == 0)
                error (output);
              endif
            endfor
          endif
        endif
      endfor
    endif
  unwind_protect_cleanup
    page_output_immediately (pager_state(1));
    page_screen_output (pager_state(2));
  end_unwind_protect
endfunction

function cmds = fix_deps (executable_path, binary, dylibs)
  [~, name, ext] = fileparts (binary);
  binary = strcat (name, ext);
  m = find (strcmp ({dylibs.name}, binary));
  if (isempty (m))
    ## If not in dylib list, it must be an executable
    full_binary = strcat (executable_path, filesep (), binary);
    is_link = false;
  else
    full_binary = strcat (dylibs(m).location, filesep (), binary);
    is_link = dylibs(m).islink;
  endif
  if (! is_link)
    [deps, full_deps] = dylibs_get_deps (full_binary);
    cmds = cell (numel (deps), 1);
    for n = 1:numel(deps)
      m = find (strcmp ({dylibs.name}, deps{n}), 1);
      if (! isempty (m))
        ## Don't run install_tool_name on symbolic links
        full_name = strcat (dylibs(m).location, filesep (), dylibs(m).name);
        tokenized_dep = tokenized_path (executable_path, full_name);
        cmds{n} = sprintf ("install_name_tool -change '%s' '%s' '%s'\n\n",
                           full_deps{n},
                           tokenized_dep,
                           full_binary);
      else
        warning ('dylibs_fix: Missing dynamic library "%s" needed by "%s"',
                 deps{n}, binary)
      endif
    endfor
    ## Missing dynamic libraries result in empty cmds
    cmds(cellfun(@isempty,cmds,"UniforOutput",true)) = [];
  else
    cmds = {};
  endif
endfunction

function cmd = fix_id (executable_path, full_binary)
  try
    if (dylibs_isdylib (full_binary))
      tokenized_binary = tokenized_path (executable_path, full_binary);
      cmd = sprintf ("install_name_tool -id '%s' '%s'\n",
                     tokenized_binary,
                     full_binary);
    endif
  catch
    save fix_id.mat
    rethrow (lasterror ())
  end_try_catch
endfunction

function tpath = tokenized_path (executable_path, binary)
  binary_path = file_location (binary);
  [~, name, ext] = fileparts (binary);
  name = strcat (name, ext);
  binary = strcat (binary_path, filesep (), name);
  n = min (numel (binary_path), numel (executable_path));
  n = binary_path(1:n) == executable_path(1:n);
  n = find (n == 0, 1, "first") - 1;
  shared_path = binary_path(1:n);
  extra_dirs = numel (findstr (executable_path(n+1:end), filesep ()));
  exe2bin = repmat (strcat ("..", filesep ()), [1, extra_dirs+1]);
  tpath = strcat ("@executable_path", filesep (), exe2bin, binary_path(n+1:end),
                  filesep (), name);
endfunction

function loc = file_location (file)
  path2file = fileparts (file);
  cwd = pwd ();
  unwind_protect
    if (! isempty (path2file))
      cd (path2file)
    endif
    loc = pwd ();
  unwind_protect_cleanup
    cd (cwd);
  end_unwind_protect
endfunction