usb4java.github.io/nativelibs.html at master · usb4java/usb4java.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
<!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
-->
<htmlxmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<metacharset="UTF-8" />
<metaname="viewport" content="width=device-width, initial-scale=1.0" />
<metaname="Date-Revision-yyyymmdd" content="20181021" />
<metahttp-equiv="Content-Language" content="en" />
<title>usb4java &#x2013; Native libraries</title>
<linkrel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
<linkrel="stylesheet" href="./css/site.css" />
<linkrel="stylesheet" href="./css/print.css" media="print" />
<scripttype="text/javascript" src="./js/apache-maven-fluido-1.7.min.js"></script>
<linkhref="favicon.ico" rel="SHORTCUT ICON" />
</head>
<bodyclass="topBarDisabled">
<ahref="https://github.com/usb4java">
<imgstyle="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>
<divclass="container-fluid">
<divid="banner">
<divclass="pull-left"><ahref="./" id="bannerLeft"><imgsrc="images/logo.png" alt="usb4java"/></a></div>
<divclass="pull-right"></div>
<divclass="clear"><hr/></div>
</div>

<divid="breadcrumbs">
<ulclass="breadcrumb">
<liid="publishDate">Last Published: 2018-10-21<spanclass="divider">|</span>
</li>
<liid="projectVersion">Version: 1.3.0<spanclass="divider">|</span></li>
<liclass=""><ahref="./" title="usb4java">usb4java</a><spanclass="divider">/</span></li>
<liclass="active ">Native libraries</li>
<liclass="pull-right"><spanclass="divider">|</span>
<ahref="http://libusb.info/" class="externalLink" title="libusb">libusb</a></li>
<liclass="pull-right"><ahref="http://javax-usb.sourceforge.net/" class="externalLink" title="javax-usb">javax-usb</a></li>
</ul>
</div>
<divclass="row-fluid">
<divid="leftColumn" class="span2">
<divclass="well sidebar-nav">
<ulclass="nav nav-list">
<liclass="nav-header">usb4java</li>
<li><ahref="index.html" title="About"><spanclass="none"></span>About</a></li>
<li><ahref="quickstart/index.html" title="Quick start"><spanclass="icon-chevron-right"></span>Quick start</a></li>
<li><ahref="faq.html" title="FAQ"><spanclass="none"></span>FAQ</a></li>
<li><ahref="configuration.html" title="Configuration"><spanclass="none"></span>Configuration</a></li>
<liclass="active"><ahref="#"><spanclass="none"></span>Native libs</a></li>
<liclass="nav-header">Project Documentation</li>
<li><ahref="project-info.html" title="Project Information"><spanclass="icon-chevron-right"></span>Project Information</a></li>
<li><ahref="project-reports.html" title="Project Reports"><spanclass="icon-chevron-right"></span>Project Reports</a></li>
</ul>
<hr/>
<divid="poweredBy">
<divclass="clear"></div>
<divclass="clear"></div>
<divclass="clear"></div>
<divclass="clear"></div>
<ahref="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><imgclass="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<divid="bodyColumn" class="span10" >
<divclass="section">
<h2><aname="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>
<divclass="source"><preclass="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>
<divclass="section">
<h2><aname="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>
<divclass="source"><preclass="prettyprint">Native library not found in classpath: /org/usb4java/freebsd-x86/libusb4java.so</pre></div>
<divclass="source"><preclass="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>
<divclass="source"><preclass="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 (<aclass="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 <aclass="externalLink" href="http://libusb.info/">libusb</a> development files.</p>
<p>3. Install <aclass="externalLink" href="http://git-scm.com/">Git</a>.</p>
<p>4. Clone the <aclass="externalLink" href="https://github.com/usb4java/libusb4java/">libusb4java source code repository</a> with Git:</p>
<divclass="source"><preclass="prettyprint">$ git clone git://github.com/usb4java/libusb4java.git</pre></div>
<p>5. Enter the cloned libusb4java directory:</p>
<divclass="source"><preclass="prettyprint">$ cd libusb4java</pre></div>
<p>6. Create a build output directory and enter it:</p>
<divclass="source"><preclass="prettyprint">$ mkdir build
$ cd build</pre></div>
<p>7. Compile the native library:</p>
<divclass="source"><preclass="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 <aclass="externalLink" href="mailto:usb4java@googlegroups.com">usb4java mailing list</a> (<aclass="externalLink" href="http://groups.google.com/group/usb4java">Google group</a>). You can subscribe to it via email by sending a mail to <aclass="externalLink" href="mailto:usb4java+subscribe@googlegroups.com">usb4java+subscribe@googlegroups.com</a>.</p></div>
</div>
</div>
</div>
<hr/>
<footer>
<divclass="container-fluid">
<divclass="row-fluid">
<p>Copyright &copy;2011&#x2013;2018
<ahref="http://usb4java.org/">usb4java Team</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>