<!DOCTYPE html>

<!--

| Generated by Apache Maven Doxia Site Renderer 1.8.1 from src/site/apt/nativelibs.apt.vm at 2018-10-21

| Rendered using Apache Maven Fluido Skin 1.7

-->

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>

<meta charset="UTF-8" />

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

<meta name="Date-Revision-yyyymmdd" content="20181021" />

<meta http-equiv="Content-Language" content="en" />

<title>usb4java &#x2013; Native libraries</title>

<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />

<link rel="stylesheet" href="./css/site.css" />

<link rel="stylesheet" href="./css/print.css" media="print" />

<script type="text/javascript" src="./js/apache-maven-fluido-1.7.min.js"></script>

<link href="favicon.ico" rel="SHORTCUT ICON" />

</head>

<body class="topBarDisabled">

<a href="https://github.com/usb4java">

<img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;"

src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"

alt="Fork me on GitHub">

</a>

<div class="container-fluid">

<div id="banner">

<div class="pull-left"><a href="./" id="bannerLeft"><img src="images/logo.png" alt="usb4java"/></a></div>

<div class="pull-right"></div>

<div class="clear"><hr/></div>

</div>

<div id="breadcrumbs">

<ul class="breadcrumb">

<li id="publishDate">Last Published: 2018-10-21<span class="divider">|</span>

</li>

<li id="projectVersion">Version: 1.3.0<span class="divider">|</span></li>

<li class=""><a href="./" title="usb4java">usb4java</a><span class="divider">/</span></li>

<li class="active ">Native libraries</li>

<li class="pull-right"><span class="divider">|</span>

<a href="http://libusb.info/" class="externalLink" title="libusb">libusb</a></li>

<li class="pull-right"><a href="http://javax-usb.sourceforge.net/" class="externalLink" title="javax-usb">javax-usb</a></li>

</ul>

</div>

<div class="row-fluid">

<div id="leftColumn" class="span2">

<div class="well sidebar-nav">

<ul class="nav nav-list">

<li class="nav-header">usb4java</li>

<li><a href="index.html" title="About"><span class="none"></span>About</a></li>

<li><a href="quickstart/index.html" title="Quick start"><span class="icon-chevron-right"></span>Quick start</a></li>

<li><a href="faq.html" title="FAQ"><span class="none"></span>FAQ</a></li>

<li><a href="configuration.html" title="Configuration"><span class="none"></span>Configuration</a></li>

<li class="active"><a href="#"><span class="none"></span>Native libs</a></li>

<li class="nav-header">Project Documentation</li>

<li><a href="project-info.html" title="Project Information"><span class="icon-chevron-right"></span>Project Information</a></li>

<li><a href="project-reports.html" title="Project Reports"><span class="icon-chevron-right"></span>Project Reports</a></li>

</ul>

<hr />

<div id="poweredBy">

<div class="clear"></div>

<div class="clear"></div>

<div class="clear"></div>

<div class="clear"></div>

<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>

</div>

</div>

</div>

<div id="bodyColumn" class="span10" >

<div class="section">

<h2><a name="Library_loading"></a>Library loading</h2>

<p>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 <i>java.library.path</i> or environment variables like <i>LD_LIBRARY_PATH</i> or <i>DYLD_LIBRARY_PATH</i>.</p>

<p>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:</p>

<div class="source"><pre class="prettyprint">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</pre></div>

<p>To make this work just make sure to put the <i>natives</i> folder into your classpath.</p></div>

<div class="section">

<h2><a name="Unsupported_platforms"></a>Unsupported platforms</h2>

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

<div class="source"><pre class="prettyprint">Native library not found in classpath: /org/usb4java/freebsd-x86/libusb4java.so</pre></div>

<div class="source"><pre class="prettyprint">Unable to determine the shared library file extension for operating system

'strangeos'. Please specify Java parameter -Dusb4java.libext.strangeos=&lt;FILE-EXTENSION&gt;</pre></div>

<p>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):</p>

<div class="source"><pre class="prettyprint">-Dusb4java.libext.strangeos=so</pre></div>

<p>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:</p>

<p>1. Install a Java JDK (<a class="externalLink" href="http://openjdk.java.net/">OpenJDK</a> for example). Make sure the environment variable <i>JAVA_HOME</i> is pointing to the directory where you have installed the JDK.</p>

<p>2. Install the <a class="externalLink" href="http://libusb.info/">libusb</a> development files.</p>

<p>3. Install <a class="externalLink" href="http://git-scm.com/">Git</a>.</p>

<p>4. Clone the <a class="externalLink" href="https://github.com/usb4java/libusb4java/">libusb4java source code repository</a> with Git:</p>

<div class="source"><pre class="prettyprint">$ git clone git://github.com/usb4java/libusb4java.git</pre></div>

<p>5. Enter the cloned libusb4java directory:</p>

<div class="source"><pre class="prettyprint">$ cd libusb4java</pre></div>

<p>6. Create a build output directory and enter it:</p>

<div class="source"><pre class="prettyprint">$ mkdir build

$ cd build</pre></div>

<p>7. Compile the native library:</p>

<div class="source"><pre class="prettyprint">$ cmake .. -DCMAKE_INSTALL_PREFIX=&quot;&quot;

$ make install/strip DESTDIR=/tmp</pre></div>

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

<p>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 <i>src</i> sub folder. You could write a new simple Makefile or whatever is needed on your platform.</p>

<p>If you have problems then please consult the <a class="externalLink" href="mailto:usb4java@googlegroups.com">usb4java mailing list</a> (<a class="externalLink" href="http://groups.google.com/group/usb4java">Google group</a>). You can subscribe to it via email by sending a mail to <a class="externalLink" href="mailto:usb4java+subscribe@googlegroups.com">usb4java+subscribe@googlegroups.com</a>.</p></div>

</div>

</div>

</div>

<hr/>

<footer>

<div class="container-fluid">

<div class="row-fluid">

<p>Copyright &copy;2011&#x2013;2018

<a href="http://usb4java.org/">usb4java Team</a>.

All rights reserved.</p>

</div>

</div>

</footer>

</body>

</html>