Non-standard librnd installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Standard librnd installation

  As per FHS, librnd should be installed to prefix /usr/local (when installed
  from source) or /usr (when installed from package). If no prefix is specified
  when configuring librnd, it will default to /usr/local.

  Another standard prefix is /opt/librnd, in case a per-package root is
  preferred.

  When standard librnd installation is chosen, no librnd-specific arguments
  need to be passed to pcb-rnd ./configure, it will automatically find
  librnd (with a preference for source install).

  On some systems ldconfig needs to be ran after the installation so that
  the dynamic linker leanrs about the new .so files available.

2. Installing librnd in a non-standard prefix

  If --prefix was specified at configure time pointing to a non-standard
  path, pcb-rnd configuration, compilation and execution need extra
  preparation.

  Examples in this document assume librnd was configured with
  --prefix=/foo/librnd

2.1. Before pcb-rnd ./configure

  Set librnd prefix so ./configure can find it:

  export LIBRND_PREFIX=/foo/librnd

  After that, from the same shell, run ./configure with the usual arguments.

2.2. Before compiling pcb-rnd

  Nothing special, make should work as usual. 

  (LIBRND_PREFIX doesn't need to be set, ./configure ironed that in to
  compile time config files.)

2.3. Executing pcb-rnd

  This includes:
    - executing pcb-rnd from source (must happen from within src/)
    - executing pcb-rnd after installation
    - executing any utility, from source or installed
    - running make test
    - manually executing any test program 

  Failing this step will lead to an error message generated by the dynamic
  linker of the operating system, and will look similar to:

  error while loading shared libraries: librnd-hid.so.3: cannot open shared object file: No such file or directory

  Before execution, the operating system's dynamic linker needs to be
  configured to look for dynamic libs (.so files) in the non-standard place
  librnd is installed in. How this needs to be done may differ from system
  to system.

  Please note: this is not specific to librnd or pcb-rnd, this happens
  with any dynamic linked lib that gets installed to a non-standard place.
  If you already have a trick for those, that trick will work with librnd too.

  Here are some examples:

  - GNU/Linux; temporary solution (for a single execution)

     LD_LIBRARY_PATH=/foo/librnd/lib pcb-rnd <usual_arguments>

  - GNU/Linux; temporary solution (for a given shell session)

     export LD_LIBRARY_PATH=/foo/librnd/lib
     pcb-rnd <usual_arguments>

  - old OSX: same options as above, but use DYLD_LIBRARY_PATH instead of
    LD_LIBRARY_PATH

  - recent OSX: they have ruined DYLD_LIBRARY_PATH; for interactice usage 
    simple exporting DYLD_LIBRARY_PATH as above will work. For make test to
    pass, you'll need to:
    + create a file in your home directory called .zshenv
    + add in ~/zshenv: export DYLD_LIBRARY_PATH=/foo/librnd/lib
    + after ./configure in pcb-rnd, add this line at the end of Makefile.conf:
      SHELL=zsh
    + create a file src/pcb-rnd.wrap, enter:
      #!/bin/zsh
      exec ./pcb-rnd "$@"

  - GNU/Linux; permanent solution:

    Add /foo/librnd/lib to /etc/ld.so.conf or in a new file under
    /etc/ld.so.conf.d/ if that directory exists. Run ldconfig as root to
    get ld read your changes.


3. Other configure options that may matter

3.1. ./configure --libarchdir

  The default value of librachdir is "lib", which means the lib dir is
  $(PREFIX)/lib. On some systems, e.g. x86_64, it may need to be changed
  to "lib64".

  The --libarchdir setting between librnd and pcb-rnd must match: 
    - either not set
    - or if set, it must be set explicitly to the same string in both librnd
      and pcb-rnd ./configure.
