Skip to content

Commit a8bc454

Browse files
JashanReelJashanReel
committed
fix: adapted the readme guide about generating JARs, integrating JMEOS in a project and running it correctly
1 parent a9a07b1 commit a8bc454

1 file changed

Lines changed: 98 additions & 24 deletions

File tree

‎src/readme_jar.md‎

Lines changed: 98 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,38 @@
11
# Readme to generate the jar file and integrate it in an other directory - IntelliJ IDE 2023.1
2-
## A. Generation (Already done for you)
3-
### 1. Libmeos.so
4-
Add libmeos.so file, containing the basic meos library, into the lib directory. For simplicity, it was already done in this project.
5-
### 2. Pom.xml
6-
Add manually the libmeos plugin into the Maven dependency through the pom.xml file **<build>**. Again for simplicity, it was already done for you.
7-
### 3. Installation
8-
To install it, open the terminal where the **pom.xml** is located and run the command:
9-
```console
2+
## A. Generation
3+
4+
### 1. JAR (already done for you)
5+
You can find it in the /jar directory, but you can run this command if you'd like to generate a new one:
6+
```console
107
example@john:~$ mvn install
118
```
12-
A jar file will be generated into the target folder of the project.
139

14-
### 4. Verification
15-
You can verify the installation of the plugin by running the following command:
16-
```console
17-
example@john:~$ mvn verify
10+
### 2. Uber JAR
11+
You'll sometimes need a Fat/Uber JAR bundling all the dependencies JMEOS needs internally (such as jnr.ffi) so
12+
you don't have to manage them yourself (e.g. when creating a Jupyter Notebook using JMEOS).
13+
This command will generate a Fat Jar in the /jar directory alongside the classic Jar
14+
```console
15+
example@john:~$ mvn package -DskipTests
1816
```
1917

18+
Here's an article explaining everything about Fat/Uber, Thin, Skinny and Hollow JARs: https://dzone.com/articles/the-skinny-on-fat-thin-hollow-and-uber
19+
20+
In the end, the structure of your personal project should look like this:
21+
my-project/
22+
├── Dockerfile
23+
├── pom.xml
24+
├── lib/
25+
│ └── JMEOS-fat.jar
26+
└── src/main/java/org/example/Main.java
27+
2028
## B. Integration
2129

2230
### 1. Copy of the Jar
23-
Copy the generated **src/jar/JMEOS.jar** file into the new project repository you desire. It is recommended to put it into a specific directory (ex: src/jar).
31+
Copy the generated **src/jar/JMEOS-fat.jar** file into the new project repository you desire. It is recommended to put it into a specific directory (ex: src/lib).
2432

2533
### 2. Add dependency
26-
Open the **pom.xml** file (if using Maven) or a the **build.gradle** (if using Gradle) and add the **jmeos** dependency. For Maven:
34+
Open the **pom.xml** file (if using Maven) or a the **build.gradle** (if using Gradle) and add the **jmeos** dependency.
35+
For Maven:
2736
```
2837
<dependency>
2938
<groupId>org.jmeos</groupId>
@@ -34,23 +43,88 @@
3443

3544
### 3. Install the dependency
3645

37-
Install the dependency into your system by opening the terminal and execute the following command line:
38-
46+
Since JMEOS is not available on Maven Central, you need to register it in your local Maven repository so that the dependency
47+
can be resolved:
3948
_Linux_:
4049
```console
41-
example@john:~$ mvn install:install-file -Dfile=$path_to_jar_file/JMEOS.jar -DgroupId=org.jmeos -DartifactId=jmeos -Dversion=1.0-SNAPSHOT -Dpackaging=jar
50+
example@john:~$ mvn install:install-file -Dfile=$path_to_jar_file/JMEOS-fat.jar -DgroupId=org.jmeos -DartifactId=jmeos -Dversion=1.0-SNAPSHOT -Dpackaging=jar
4251
```
4352

4453
_Windows_:
4554
```cmd
46-
example@john:~$ mvn install:install-file -Dfile="$path_to_jar_file/JMEOS.jar" -DgroupId="org.jmeos" -DartifactId=jmeos -Dversion="1.0-SNAPSHOT" -Dpackaging=jar
55+
example@john:~$ mvn install:install-file -Dfile="$absolute_path_to_jar_file/JMEOS-fat.jar" -DgroupId="org.jmeos" -DartifactId=jmeos -Dversion="1.0-SNAPSHOT" -Dpackaging=jar
4756
```
4857

49-
where **$path_to_jar_file** is the absolute path to the **.jar** file previously generated and placed.
50-
51-
### 4. Add other dependencies
52-
53-
As JMEOS uses other dependencies *you should normally* add them but for simplicity **the dependencies have been added** with the JAR.
58+
where **$path_to_jar_file** is the absolute path to the **.jar** file previously copied and placed in your project.
5459

5560
You just need to refresh Maven with the ***"Reload all Maven Projects"*** button, and you should see all the dependencies appear in the ***"External Libraries"*** of your project.
5661

62+
## C. Running
63+
64+
On Windows, your project using JMEOS may not run well using the IDE. Therefore, using Docker will simplify the process.
65+
66+
Here's an example for a Dockerfile for a basic fresh project with no other dependencies:
67+
68+
```cmd
69+
FROM debian:bookworm-slim
70+
71+
RUN apt-get update \
72+
&& apt-get install -y git curl gnupg build-essential cmake \
73+
postgresql-server-dev-15 libproj-dev libjson-c-dev libgsl-dev libgeos-dev postgis \
74+
&& export GNUPGHOME="$(mktemp -d)" \
75+
&& curl -fL https://apt.corretto.aws/corretto.key | gpg --batch --import \
76+
&& gpg --batch --export '6DC3636DAE534049C8B94623A122542AB04F24E3' > /usr/share/keyrings/corretto.gpg \
77+
&& rm -r "$GNUPGHOME" \
78+
&& unset GNUPGHOME \
79+
&& echo "deb [signed-by=/usr/share/keyrings/corretto.gpg] https://apt.corretto.aws stable main" > /etc/apt/sources.list.d/corretto.list \
80+
&& apt-get update \
81+
&& apt-get install -y java-21-amazon-corretto-jdk
82+
83+
# Compile MobilityDB with MEOS (generates libmeos.so)
84+
RUN git clone https://github.com/MobilityDB/MobilityDB.git -b stable-1.3 /usr/local/src/MobilityDB
85+
RUN mkdir -p /usr/local/src/MobilityDB/build
86+
RUN cd /usr/local/src/MobilityDB/build && \
87+
cmake -DMEOS=ON .. && \
88+
make -j$(nproc) && \
89+
make install && \
90+
ldconfig
91+
92+
# Maven
93+
ENV MAVEN_HOME=/usr/share/maven
94+
ENV MAVEN_CONFIG="/root/.m2"
95+
COPY --from=maven:3.9.6-eclipse-temurin-11 ${MAVEN_HOME} ${MAVEN_HOME}
96+
COPY --from=maven:3.9.6-eclipse-temurin-11 /usr/local/bin/mvn-entrypoint.sh /usr/local/bin/mvn-entrypoint.sh
97+
COPY --from=maven:3.9.6-eclipse-temurin-11 /usr/share/maven/ref/settings-docker.xml /usr/share/maven/ref/settings-docker.xml
98+
RUN ln -s ${MAVEN_HOME}/bin/mvn /usr/bin/mvn
99+
100+
# Install JMEOS in the local Maven repository
101+
# (edit the JMEOS.jar path if needed at the root of your project)
102+
COPY lib/JMEOS-fat.jar /tmp/JMEOS-fat.jar
103+
RUN mvn install:install-file \
104+
-Dfile=/tmp/JMEOS-fat.jar \
105+
-DgroupId=org.jmeos \
106+
-DartifactId=jmeos \
107+
-Dversion=1.0-SNAPSHOT \
108+
-Dpackaging=jar
109+
110+
WORKDIR /app
111+
COPY pom.xml .
112+
# dependencies cache
113+
RUN mvn dependency:go-offline -q
114+
COPY src ./src
115+
RUN mvn package -DskipTests
116+
117+
ENV LD_LIBRARY_PATH=/usr/local/lib
118+
119+
# Entrypoint
120+
CMD ["java", "--add-opens", "java.base/java.lang=ALL-UNNAMED", "-Djava.library.path=/usr/local/lib", "-cp", "target/untitled-1.0-SNAPSHOT.jar:/tmp/JMEOS-fat.jar", "org.example.Main"]
121+
```
122+
123+
Note:
124+
- when cloning MobilityDB in the Dockerfile, you might want to change its version, e.g. "-b stable-1.3" instead of "-b master" depending on your needs (functions such as geom_in only available in meos_geo.h):
125+
```Ln 16: RUN git clone https://github.com/MobilityDB/MobilityDB.git -b master```
126+
- do not forget to adapt the entrypoint parameters to your project:
127+
- the parameters of target/ here depending on the artifactId and version of your pom, here:
128+
```target/untitled-1.0-SNAPSHOT.jar:/tmp/JMEOS-fat.jar"```
129+
- the program you're trying to run, here:
130+
```"org.example.Main"```

0 commit comments

Comments
 (0)