@@ -4,7 +4,29 @@ SPDX-FileCopyrightText: 2022 Alliander N.V.
44SPDX-License-Identifier: Apache-2.0
55-->
66
7- # Development
7+ # Development for CoMPAS SCL Validator
8+
9+
10+ ---
11+ ** Note**
12+ Mac M1 chip users, see [ below] ( #mac-m1 )
13+
14+ ---
15+
16+
17+ Since version 1.2.x the JAR Files of RiseClipse are distributed through Maven Central Repository. The JAR Files can be
18+ retrieved from there and don't need to be build locally anymore. Only the OCL Files for the SCL validation still need to
19+ be downloaded from RiseClipse GIT Repository. This is still done using Git Submodules.
20+
21+ To clone the project or update the project this means that the Git commands are sometimes a little different. To clone
22+ the project use the following command
` git clone --recurse-submodules [email protected] :com-pas/compas-scl-validator.git ` .
23+ This will also clone the submodules.
24+
25+ Tip: The URL to the submodules are configured in the file ` .gitmodules ` , but these are using the SSH URL. There is a way
26+ described [ here] ( https://git-scm.com/book/en/v2/Git-Tools-Submodules ) to overwrite the URL locally with an HTTPS URL of
27+ the GIT Repository.
28+
29+ Check the [ Development] ( DEVELOPMENT.md ) page for more detail information how to develop in this GIT repository.
830
931## Git
1032
@@ -56,6 +78,22 @@ maven module is created here, see [README.md](riseclipse/riseclipse-p2-to-m2/REA
5678Example about how to use Eclipse OCL was found
5779[ here] ( https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.ocl.doc%2Fhelp%2FPivotStandalone.html ) .
5880
81+ ## Building the application
82+
83+ You can use Maven to build the application and see if all tests are working using:
84+
85+ ``` shell script
86+ ./mvnw clean verify
87+ ```
88+
89+ This should normally be enough to also run the application, but there were cases that we need to build using:
90+
91+ ``` shell script
92+ ./mvnw clean install
93+ ```
94+
95+ This to make the local modules available for the app module to run the application.
96+
5997## Running the application in dev mode
6098
6199You can run your application in dev mode that enables live coding using:
@@ -66,22 +104,77 @@ You can run your application in dev mode that enables live coding using:
66104
67105> ** _ NOTE:_ ** Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/ .
68106
69- ## Packaging and running the application
107+ ### Application depends on a running KeyCloak instance for dev mode
70108
71- The application can be packaged using:
109+ There is a KeyCloak instance need to be running on port 8089 by default in dev mode.
110+ See [ Security] ( README.md#security ) for default values, if custom keycloak is used.
72111
73- ``` shell script
74- ./mvnw package
112+ There is a preconfigured keycloak instance available in
113+ the [ CoMPAS Deployment Repository] ( https://github.com/com-pas/compas-deployment ) . This repository can be cloned and
114+ when going to this directory the following command can be executed to create a local Docker Image with configuration.
115+
116+ ``` shell
117+ cd < CoMPAS Deployment Repository Directory> /compas/keycloak
118+ docker build -t compas_keycloak .
75119```
76120
77- It produces the ` quarkus-run.jar ` file in the ` app/target/quarkus-app/ ` directory. Be aware that it’s not an _ über-jar_
78- as the dependencies are copied into the ` app/target/quarkus-app/lib/ ` directory.
121+ There is now a Docker Image ` compas_keycloak ` created that can be started using the following command
122+
123+ ``` shell
124+ docker run --rm --name compas_keycloak \
125+ -p 8089:8080
126+ -d compas_keycloak:latest
127+ ```
128+
129+ ## Testing the application
130+
131+ The application is tested with unit and integration tests, but you can also manually test the application using for
132+ instance Postman. And there is also a way to test this service with the CoMPAS OpenSCD Frontend application.
133+
134+ ### Postman
135+
136+ To manually test the application there is a Postman collection in the directory ` postman ` that can be imported
137+ and used to execute REST XML Calls.
138+
139+ To make the call work we also need to import an environment and authorisation collection. These files can be found
140+ in [ CoMPAS Deployment Repository] ( https://github.com/com-pas/compas-deployment ) in the directory ` postman `
141+ (` auth.collection.json ` and ` local.environment.json ` ).
142+
143+ In the authorisation collection there are called for the 3 users known within the Demo KeyCloak instance.
144+ If one of these calls are executed there is a variable ` bearer ` filled.
145+
146+ Now one of the SCL Auto Alignment calls can be executed, the variable ` bearer ` is added to the header of the request.
147+ After the call is executed the result should be shown in Postman.
79148
80- If you want to build an _ über-jar_ , execute the following command:
149+ ### CoMPAS OpenSCD Frontend application
150+
151+ To test the SCL Validator with the CoMPAS OpenSCD application just run the application in dev mode, including the
152+ KeyCloak instance. For further instruction how to start the CoMPAS OpenSCD application and use this locally see
153+ the file ` DEVELOPMENT.md ` in [ CoMPAS OpenSCD application] ( https://github.com/com-pas/compas-open-scd ) .
154+
155+ ## Docker Images
156+
157+ ### Creating a Docker image with native executable
158+
159+ The CoMPAS SCL Validator currently isn't build as Native executable, GraalVM has a lot of problems to strip the
160+ Eclipse libraries and make them work as Native executable.
161+
162+ ### Creating a Docker image with JVM executable
163+
164+ The release action is creating a Docker Image which runs the application using a JVM. You can create a Docker Image
165+ with JVM executable using:
81166
82167``` shell script
83- ./mvnw package -Dquarkus.package.type=uber-jar
168+ ./mvnw package -Pjvm-image
84169```
85170
86- The application is now runnable using ` java -jar app/target/quarkus-app/quarkus-run.jar ` .
171+ ## Mac M1
172+
173+ The Mac M1 chip is ARM based. In order to make this project work, you need to install the x86 version of your IDE.
174+ You also need Rosetta2 to virtualize your os. In the x86 version of your IDE, you also need to install the x86 Java version.
175+ You can use SDK-Man to easily switch between java versions.
87176
177+ While calling maven scripts, you need to add the os.arch flag.
178+ ``` shell script
179+ ./mvnw clean compile -Dos.arch=x86_64
180+ ```
0 commit comments