Library loading

The native libraries for all supported platforms are provided as JAR files which you can simply reference in your classpath. usb4java automatically determines on startup which libraries are needed for the current platform and extracts them to a temporary directory and loads them from there. This makes it easy to use usb4java because you just need to put the JARs into your classpath. No need to fiddle around with java.library.path or environment variables like LD_LIBRARY_PATH or DYLD_LIBRARY_PATH.

usb4java only extracts the files into a temporary directory when they are inside a JAR file. So if you prefer direct loading without extracting to a temporary directory then you may want to distribute the files in extracted form. Just make sure your classpath includes the directory where you have extracted the JARs. Here is an example application layout for this scenario:

natives/
  org/usb4java/
    linux-x86-64/libusb4java.so
    win32-x86-64/libusb4java.dll
    darwin-x86-64/libusb4java.dylib
lib/
  usb4java.jar
  commons-lang3.jar
  myapp.jar
myapp.sh

To make this work just make sure to put the natives folder into your classpath.

Unsupported platforms

When you use usb4java on a platform which is not directly supported by usb4java then you might get one of the following two exceptions:

Native library not found in classpath: /org/usb4java/freebsd-x86/libusb4java.so

Unable to determine the shared library file extension for operating system
'strangeos'. Please specify Java parameter -Dusb4java.libext.strangeos=<FILE-EXTENSION>

If you get the second one then this simply means that your operating system is completely unknown to the usb4java authors and usb4java does not know the file extension of shared libraries on this platform. You can fix this by specifying a Java parameter like this (As explained in the exception):

-Dusb4java.libext.strangeos=so

After this you will most likely get the other exception, which means that there is no native JNI wrapper present for this platform. Your only chance here is to compile this wrapper yourself. I can't predict how this works on really strange platforms but chances are high that your platform is somewhat Unix-compatible. So try this:

1. Install a Java JDK (OpenJDK for example). Make sure the environment variable JAVA_HOME is pointing to the directory where you have installed the JDK.

2. Install the libusb development files.

3. Install Git.

4. Clone the libusb4java source code repository with Git:

$ git clone git://github.com/usb4java/libusb4java.git

5. Enter the cloned libusb4java directory:

$ cd libusb4java

6. Create a build output directory and enter it:

$ mkdir build
$ cd build

7. Compile the native library:

$ cmake .. -DCMAKE_INSTALL_PREFIX=""
$ make install/strip DESTDIR=/tmp

8. When compilation was successful then the native library can be found in the directory /tmp/lib. The file name depends on your operating system. Make sure you rename it to libusb4java.so (Or whatever file extension your platform uses) and copy this file into the directory /org/usb4java/OS-ARCH/ in your classpath where OS is the name of your operating system and ARCH is your CPU architecture (Both must match the names mentioned in the exception thrown by usb4java.)

If you can't use the GNU compiler or cmake then you are on your own. If you have some experience with compiling JNI libraries then I guess this won't be hard for you. There are only a couple of source files in the src sub folder. You could write a new simple Makefile or whatever is needed on your platform.

If you have problems then please consult the usb4java mailing list (Google group). You can subscribe to it via email by sending a mail to usb4java+subscribe@googlegroups.com.