ljacklm (libljacklm) Library Installation Instructions
============================================================


Linux Requirements
------------------

1. GNU C compiler (gcc).

2. The Exodriver library from LabJack.  The Exodriver requirements and download
   can be found here:
   https://labjack.com/support/software/installers/exodriver

3. Linux kernel 2.6+.

4. Uninstall any old U12 kernel-module based drivers.  The old driver
and custom kernel modules conflict with the current libljacklm library.


Mac OS X Requirements
---------------------

1. XCode developer tools

2. The Exodriver library from LabJack.  The Exodriver requirements and download
   can be found here:
   https://labjack.com/support/software/installers/exodriver

3. Mac OS X 10.5 Leopard or newer.


libljacklm Library Installation
----------------------------------

After fulfilling the requirements, in a terminal go to the download's directory
ljacklm/, then go to the libljacklm/ directory and compile and install the
library with the following commands:

    $ cd libljacklm/
    $ make
    $ sudo make install


Compiling and Running the Example Programs
------------------------------------------

The examples use the ljacklm library and the ljacklm.h header file. The header
file is installed in the /usr/local/include/ directory and can also be found in
the libljacklm/ directory.

The examples are located in the examples/ directory.  To compile the programs,
in a terminal go to the directory and run:

    $ cd examples/
    $ make

Run one of example programs like this:

    $ ./analog


Optional: Build a combined 32-/64-bit ljacklm on Mac OS X
-----------------------------------------------------------

These steps are generally not needed, but there are circumstances that require
a combined 32-bit and 64-bit Exodriver. You need both architectures when you
get error messages like this one:

    dlopen(libljacklm.dylib, 6): no suitable image found.  Did find:
        /usr/local/lib/libljacklm.dylib: mach-o, but wrong architecture

In this case, a 32-bit process tried to load a 64-bit ljacklm. Here's how it
happened: When following the instructions in the Quickstart, the compiler built
a copy of the ljacklm for its native architecture. On modern Mac OS X
systems, that's x86_64 (64-bit). Verify this by running:

    $ file /usr/local/lib/libljacklm.dylib 
    /usr/local/lib/libljacklm.dylib: Mach-O 64-bit dynamically linked shared library x86_64

Normally, this is what you want. The programs you will use to call the
ljacklm will also be 64-bit. The built-in Python on Mac OS X, for example, is
compiled for three architectures, including x86_64:

    $ file /usr/bin/python
    /usr/bin/python: Mach-O universal binary with 3 architectures
    /usr/bin/python (for architecture x86_64):  Mach-O 64-bit executable x86_64
    /usr/bin/python (for architecture i386):    Mach-O executable i386
    /usr/bin/python (for architecture ppc7400): Mach-O executable ppc

There are some programs on Mac OS X, though, that are not 64-bit (they're i368
only), and they can't load a 64-bit ljacklm. The Python download from
python.org, for example, is 32-bit at the time of this writing. We recommend
using the built-in Python on Mac OS X.

When you must load the ljacklm from a 32-bit process, you must compile
libusb-1.0 and Exodriver to be 32-/64-bit libraries first.  Refer to the
Exodriver download's INSTALL.MacOSX installation instuctions on building
libusb-10 and Exodriver as 32-/64-bit libraries.


After libusb-1.0 and the Exodriver are installed correctly, move on to the
ljacklm. Find the ljacklm download directory

    $ cd path/to/ljacklm
    $ cd libljacklm/

Now edit the Makefile in a text editor to comment out (put a # sign in front
of) this ARCHFLAGS line:

    #ARCHFLAGS =

and uncomment (remove the # sign from) this ARCHFLAGSS line two lines above it:

    ARCHFLAGS = -arch i386 -arch x86_64

Now build and install the software

    $ make clean
    $ make
    $ sudo make install

Verify that it worked by running:

    $ file /usr/local/lib/libljacklm.dylib 
    /usr/local/lib/libljacklm.dylib: Mach-O universal binary with 2 architectures
    /usr/local/lib/libljacklm.dylib (for architecture i386): Mach-O dynamically linked shared library i386
    /usr/local/lib/libljacklm.dylib (for architecture x86_64):   Mach-O 64-bit dynamically linked shared library x86_64

Because libusb-1.0, the Exodriver and ljacklm are built for the i386
architecture, 32-bit applications can load them.
