You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+51-30Lines changed: 51 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,6 +20,7 @@ Implementing Java's SelectableChannel API is not possible with EPoll and SocketC
20
20
* Support for other CAN protocols (e.g. CAN_MCNET)
21
21
* A [netty](https://netty.io) integration (see #20)
22
22
* BSD Support
23
+
* io_uring Support
23
24
24
25
Pull requests are welcome!
25
26
@@ -54,30 +55,41 @@ down below.
54
55
### CAN_RAW, CAN_BCM and CAN_ISOTP channels
55
56
56
57
1. Compile yourself or get a compiled release from [Maven Central](https://search.maven.org/search?q=a:javacan)
57
-
2. Create a channel by calling one of the `CanChannels.new...Channel()` methods
58
-
3. Create a `NetworkDevice` using its static `lookup(String)` method
59
-
4. Bind the channel to an interface using the `bind(CanDevice)` method
58
+
2. Install the native components into your `LD_LIBRARY_PATH` or configure the appropriate Java properties (See next section)
59
+
3. Create a channel by calling one of the `CanChannels.new...Channel()` methods
60
+
4. Create a `NetworkDevice` using its static `lookup(String)` method
61
+
5. Bind the channel to an interface using the `bind(CanDevice)` method
60
62
61
-
Usage example can be found in the unit tests.
63
+
Usage example can be found in the unit tests or in the related projects mentioned above.
62
64
63
-
**Remember**: JavaCAN is a fairly thin wrapper around Linux syscalls. Even though some aspects of the low-level C API are hidden, most JAVA API in this library will at one point call into a
65
+
**Remember**: JavaCAN is a fairly thin wrapper around Linux syscalls. Even though some aspects of the low-level C API are hidden, most Java APIs in this library will at some point call into a
64
66
(usually similarly named) C API and as such inherits all of its properties. For example `RawCanChannel.close()` translates to a call to `close()` on the underlying file descriptor, so their behaviour
65
67
should be identical. So if the behaviour of a certain API is unclear, a look into the man pages of related Linux syscalls might help. Feel free to still request additional documentation in the issues
66
-
on [Github](https://github.com/pschichtel/JavaCAN)!
68
+
on [GitHub](https://github.com/pschichtel/JavaCAN)!
67
69
68
70
#### Native components
69
71
70
-
The library relies on several native (JNI) components. By default, these components are either loaded from the standard library path (`java.library.path`) or are extracted from the classpath into a
71
-
temporary folder.
72
+
The library relies on several native (JNI) components. By default, these components are either loaded from the standard library path (`LD_LIBRARY_PATH` / `java.library.path`) or are extracted from
73
+
the classpath into a temporary folder.
72
74
73
-
Only one of the architecture can be bundled directly with JavaCAN, it is recommended to build variants of your program for each target platform.
74
-
If that is not possible, there are a few alternative approaches:
75
+
While JavaCAN 2.x bundled the native components, starting with the 3.x release series no native components are bundles with the core libraries. Dedicated jar files are generated for each native
76
+
component (classified by their architecture). JavaCAN will **not** attempt to discover the location of a library version appropriate for the correct architecture. This is instead left to
77
+
the downstream application developer.
75
78
76
-
1. Filesystem path: By setting the property `javacan.native.javacan-<module>.path` to a path in the filesystem before initializing the library, the native library will be loaded from that location.
77
-
2. Path on classpath: You can bundle libraries into different locations in your classpath. By setting the property `javacan.native.javacan-<module>.classpath` (`classpath` instead of `path`) to a path
78
-
in your classpath, the native library will be loaded from there.
79
-
80
-
The value for `<module>` is `core` and if the EPoll support is used, an additional option with `epoll` for `<module>` is necessary.
79
+
There are a few approaches to get the correct native libraries loaded:
80
+
81
+
1. Installing the libraries into the library path (the `LD_LIBRARY_PATH` environment variable or the `java.library.path` property)
82
+
2. Configuring the `javacan.native.javacan-<module>.path` property to tell JavaCAN the exact file system path where the native component is located
83
+
3. Configuring the `javacan.native.javacan-<module>.classpath` property to tell JavaCAN the exact location on the classpath where the native component is located
84
+
4. Adding **one** of the architecture-specific jar files into the classpath (either add compile time or runtime)
85
+
86
+
Application that are intended to run on a single architecture or that build architecture-specific version already, the simplest solution is to bundle the provided architecture-specific jar files
87
+
matching the build architecture.
88
+
89
+
For applications supporting multiple architectures at once I'd recommend dynamically adding the architecture-specific jar file at runtime or to repackage the available native libraries and
90
+
dynamically configuring the `javacan.native.javacan-<module>.path` properties in the CLI or before any JavaCAN classes are loaded.
91
+
92
+
The value for the `<module>` placeholder used throughout this section is `core` and if the EPoll support is used, an additional option with `epoll` for `<module>` is necessary.
81
93
82
94
## How to build
83
95
@@ -92,34 +104,43 @@ For compilation:
92
104
93
105
For tests:
94
106
95
-
* The [can-isotp](https://github.com/hartkopp/can-isotp) kernel module loaded
107
+
* A fairly recent Linux kernel with CAN support
108
+
* The can-isotp kernel module loaded (Kernel 5.10 with `CONFIG_CAN_ISOTP` enabled or the [out-of-tree module](https://github.com/hartkopp/can-isotp))
96
109
*[can-utils](https://github.com/linux-can/can-utils) installed in the `PATH`
97
110
* A CAN interface named "vcan0"
98
111
* Java 8 or newer installed
99
112
100
113
For usage:
101
114
102
-
* A recent Linux kernel with CAN support
103
-
* For ISOTP channels, the [can-isotp](https://github.com/hartkopp/can-isotp) out-of-tree kernel module or a kernel 5.10 or newer with `CONFIG_CAN_ISOTP` enabled
115
+
* A fairly recent Linux kernel with CAN support
116
+
* For ISOTP channels, the can-isotpkernel module loaded (Kernel 5.10 with `CONFIG_CAN_ISOTP` enabled or the [out-of-tree module](https://github.com/hartkopp/can-isotp))
104
117
* Java 8 or newer installed
105
-
* A few kilobytes of disk space to extract the native library
118
+
* A few kilobytes of disk space to extract the native components
106
119
107
120
108
121
### Building
109
122
110
-
#### Default Architectures
123
+
By default, the project only builds the x86_64 native components (`single-architecture` maven profile):
124
+
125
+
```bash
126
+
mvn clean package
127
+
```
128
+
129
+
The `single-architecture` profile can build different architectures by specifying the properties `javacan.architecture` and `dockcross.architecture`. This can be used to build architectures
130
+
that are not currently included in JavaCAN releases. Unit tests will be executed with the architecture being built. Overriding the test architecture is not possible, since other architectures are
131
+
not being built.
111
132
112
-
This will build a set of jars and native libraries capable of running on the supported architectures listed, without the need
113
-
for any further configuration.
133
+
In order to build all architectures that are currently part of releases, the `all-architectures` maven profile must be activated:
114
134
115
-
1.`mvn clean package`
116
-
2. profit
135
+
```bash
136
+
mvn clean package -Pall-architectures
137
+
```
117
138
118
-
#### Build other Architectures
139
+
The `all-architectures` profile will execute the tests using the `x86_64` libraries by default. To override this the property `javacan.test.architecture` can be set to any other architecture that
140
+
is part of the build.
119
141
120
-
The build can be configured for any single architecture that is supported by dockcross:
142
+
If the architecture you are building *on* is not part of the build, then tests will always fail. To prevent this you have to disable the `test` maven profile:
`<classifier>` will be the maven classifier used for the architecture, `<architecture>` must be a Linux based architecture supported by the [dockcross project](https://github.com/dockcross/dockcross).
125
-
If you compile this on a system with a different architecture, then you will have to skip the unit tests by additionally passing `-DskipTests` to maven.
0 commit comments