Newer
Older
The replication package for the CP-DSL provides instructions on how to install
CP-DSL and how to use it. Firstly, we address the installation of CP-DSL in
Eclipse, Vim and Jupyter. Secondly, we provide a how-to for UVic and MITgcm
utilizing the three different editors.
The CP-DSL provides a set of plugins for Eclipse integration,
an Language Server (LS) implementing the Language Server Protocol (LSP)
and a Jupyter kernel. To run any example, only one of the three editor setup
is necessary.
*Note:* We are conducting extensive tests with our case studies that
will show technical issues with the DSL. Therefore, we will provide updates
to the replication package which will be uploaded to Zenodo, accordingly.
Current technical limitations are listed in: `Limitations.md`
## Sources
- CP-DSL `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl`
- Replication package `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl-replication`
- Jupyter Kernel `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl-jupyter-kernel`
- Jupyter LSP `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl-jupyter-setup`
## The remainder contains
- Setup of the Editors
- Eclipse Setup
- Vim Setup
- Jupyter Setup
- Utilizing the CP-DSL
- Using Eclipse
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
Eclipse is a versatile Integrated Development Environment (IDE) based on Java.
Before you can install the CP-DSL in Eclipse you need to install Eclipse.
- *Installing Java*
- Most Linux distributions come with packages for Java. Install Java 11 or later.
- For Windows and Mac, you find installers at
https://www.oracle.com/java/technologies/downloads/#java11
- *Installing Eclipse*
- Download Eclipse from the Eclipse website https://www.eclipse.org/downloads/
- Click on the Download button for *Get Eclipse IDE 2021‑12*, this directs you
to a download page for the current version of Eclipse. As of today this is
the 2021-12 edition. Howver, CP-DSL should also work with previous and
later versions of Eclipse.
- Click on the Download button for the current version. This should start the
download and show the donate page, which can be ignored.
- Wait until the download is complete.
- Depending on your platform you may have zip, dmg or tar.gz archive.
- Upack the archive and run the installer within the archive. On Linux this
can be done with:
- `tar -xvzpf eclipse-inst-jre-linux64.tar.gz` (unpack archive)
- `eclipse-installer/eclipse-inst` (run installer)
- The installer will present different options of IDE setups. You can choose
any one of them, as installing CP-DSL later will automatically install all
dependencies. However, to speed things up, select *Eclipse Modeling Tools*.
- Start the installation. This may take a while.
- After downloading, the installer will ask you whether you trust the Eclipse
certificates. Check both of them and check "Remember accepted certificates".
- Click on "Trust selected".
- Click on "Launch" (or terminate and use regular startup options for Eclipse
from you systems menu)
- *Install CP-DSL*
- Open Eclipse. If you pressed on "Launch" in the previous step, this will
automatically happen.
- Eclipse starts up and asks for a workspace directory. You may take the
default or use a different name. The documentation will use `eclipse-workspace`
as the name for the workspace directory.
- Now Eclipse shows its start screen and we can start to install the CP-DSL
extension.
- Click on *Help* and then *Install new Software* menu entry. This opens up
the Install dialog.
- Here we need to add the update site for CP-DSL. Therefore, click on
*Add ...* button on the ride side. This allows us to add a new repository.
- Enter `cp-dsl` as name and `https://maui.se.informatik.uni-kiel.de/repo/oceandsl/snapshot/`
as URL for the repository.
- Click on *Add*
- Below the row with "Work with:" and the *Add* button, a list appears with
the entry `Configuration DSL`. Check the checkbox in front and click the
*Next >* button. `Configuration DSL` comprises of three features for
`Configuration`, `Declaration` and `Templates`.
- On the next page of the installation dialog these three features are shown.
- Click on *Finish* to download them.
- Now a *Security Warning* pops up indicating that our packages are not signed.
Unfortunately, this is still true, as the signing process is not trivial,
but will be fixed in future releases.
- To proceed with clicking on *Install Anyway*.
- Eclipse will install the extension and ask to restart.
- Click on *Restart Now*. This ensures that the features are installed
correctly.
- Now you are setup.
## Vim Setup
For the Vim setup, we use its extension mechanism and a special LSP
plugins and Java. Please note, we provide Debian/Ubuntu compatible installation
commands in our documentation. The correct command for your distribution or
operating system may differ.
### Prequisites
- Install the Vim LSP plugin from `https://github.com/prabirshrestha/vim-lsp`
- Install Java preferably Java 11.
### Installation
- Copy `org.oceandsl.configuration.ide-1.0.0-SNAPSHOT-ls.jar` to a tooling
directory, e.g., `~/bin` in your home directory.
- Copy the `example.vimrc` to your home folder and rename it to
`.vimrc`. In case you already have one, you need to merge both
files accordingly.
- Open the `.vimrc` in an editor and fix the path to the jar file.
- Create a directory `~/.vim`
- Start `vim`
- Type `:PlugInstall`, this should install all necessary plugin parts.
- Exit `vim` with ESC :x (depending on the number of open buffers, you might
have to do this twice).
- Merge or copy the `filetype.vim` to the `~/.vim` directory. This provides
- Start `vim` again with a file name ending with `.oconf`, e.g., `example.oconf`
This will start the LSP. Otherwise the LSP stays inactive.
- You can check the status that the LS is available with `:LspStatus`.
In case the status is offline or exited, some error might have occured.
One option is that the wrong java version is used. You can check this on
command line with `java -version`.
In case the status is online, you are ready to go. Context help is available
with CTRL-Space, similarily to Eclipse.
**Notes:**
- Vim only provides editing capabilites. Compilation must be performed
by a command-line compiler.
The Jupyter setup requires a working kernel. Unfortunately, currently the
kernel is not operational. Thus, the setup does not function. We will fix this
issue and provide an update of the replication package.
- Kernel sources `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl-jupyter-kernel`
- Docker setup (optional) for Jupyter `https://git.se.informatik.uni-kiel.de/oceandsl/cp-dsl-jupyter-setup`
- LSP for Jupyter `https://github.com/krassowski/jupyterlab-lsp`
- JuypterLab
Jupyter can be run in a docker container or setup natively on a machine.
For this use the docker setup. However, to run the system in your own
Jupyter installation, you can follow the steps below.
For the general Jupyter setup including LSP support, please follow
the instructions in the following referenced documentation:
`https://jupyterlab-lsp.readthedocs.io/en/latest/Installation.html`
The installation of a language server is explained here:
`https://jupyterlab-lsp.readthedocs.io/en/latest/Configuring.html#language_servers`
To add a language server, you need to add a block of JSON configuration
code in `./jupyter_server_config.json`
```
"oconf": {
"version": 2,
"argv": ["java", "-cp", "javassist-3.26.0-GA.jar", "-jar", "org.oceandsl.configuration.ide-1.3.0-SNAPSHOT-ls.jar"],
"languages": ["oconf"],
"mime_types": ["text/oconf", "text/x-oconf"]
}
```
Please note that Jupyter needs the fully qualified path to the two
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
`org.oceandsl.configuration.ide-1.0.0-SNAPSHOT-ls.jar`.
The language kernel must be placed in `share/jupyter/kernels` depending
on your Jupyter installation location. Create a new directory there
named `oconf` and create `logback.xml` in that place. Our default
content for the `logback.xml` is:
```
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<property value="path/to/log/file.log" name="HOME_LOG"/>
<appender name="FILE-ROLLING" class="ch.qos.logback.core.FileAppender">
<file>${HOME_LOG}</file>
<encoder>
<pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
</encoder>
</appender>
<root level="debug">
<appender-ref ref="FILE-ROLLING"/>
</root>
</configuration>
```
Please change `path/to/log/file` to an appropriate name and location.
Create the `kernel.json` file an fill it with following content:
```
{
"argv": ["path/to/cp-dsl-jupyter-kernel/bin/cp-dsl-jupyter-kernel", "{connection_file}" ],
"display_name": "Configuration and Parametrization",
"language": "oconf"
}
```
Place the file in your `share/jupyter/kernels/oconf/` directory.
Please adapt `path/to/` to the location of the jupyter kernel directory.
# Setup of Scientific Models
We use two Earth System Climate Models as case studies for the CP-DSL.
In the following we instruct how to use them.
MITgcm is a Earth System Climate Model (ESCM) available from
`http://mitgcm.org/`. The documentation can be found at
`https://mitgcm.readthedocs.io/en/latest/`.
To setup the model, you have to can get the code with:
`git clone https://github.com/MITgcm/MITgcm.git`
MITgcm has a set of prepared configurations in its verification directory.
You can create configuration files for most tutorial project based on the
example configurations, we provide in the projects/MITgcm directory.
See below in **Using Eclipse** how to import the project and generate code.
The generated code has then to be moved to the prepared configuration
directories. Alternativly, you set the Eclipse output directory to your
MITgcm verification directory.
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
## UVic Project Setup
UVic is a Earth System Climate Model (ESCM) from the University of
Victoria Canada. It can be obtained at http://terra.seos.uvic.ca/model/
To get the code you have to request access to the code from the
public model contact (email address available on the website of the
model).
Download the code and extract it into a folder. UVic does not come
with a set of test and example configurations. Thus, you have to
use the one provided in this replication package. Lets assume
your model resides in `uvic-model/uvic-run-1`.
- Open Eclipse with a clean workspace.
- Create a new project that should reside in
`uvic-model/uvic-run-1`
- You can now copy the `uvic.oconf` file from the replication package
to the project.
- Open the file in Eclipse. Eclipse might ask you to add the XText
nature, please do so. In case the `uvic.oconf` is opened in a plain
text editor, choose *Open with ...* to select the right editor.
- You can now manipulate settings for the example.
- Save the file. This generates the necessary configuration files.
- You can now compile the project following the instructions in the
respective `uvic-installation.md`
# Utilizing the CP-DSL
Depending on the editor there are some minor differences in how to use the
different editors with the CP-DSL tooling. The prepared specifications and
declaration for UVic and MITgcm can be found in this repository/archive in the
`projects` directory.
## Using Eclipse
We will illustrate how to use Eclipse with the UVic case study. However, most
steps are identical for the MITgcm setup. Differences will be noted below.
- Startup Eclipse with the installed CP-DSL (see above)
- Click on *File* > *Import...*
- This opens the *Import Wizard*
- Click on the arrow or plus sign informt of the entry *General*
- Select *Existing Projects into Workspace*
- Click *Next>*
- This opens the *Import Projects* dialog
- Click on the *Browse...* button to select the directory of the UVic project.
- This opens a file dialog.
- Navigate to the `cp-dsl-replication/projects/` directory.
- Select `UVic` and click *Open*.
- Now there should be one project listed under projects.
- Click *Finish*
- If the welcome pane is still shown, close it by clicking on the X new the
label *Welcome*.
- Now you should see the IDE with a *Model Explorer* and an *Outline* on the
left, a large empty area (for the editor) and a *Properties* and *Problem*
view at the bottom.
- Click in the *Model Explorer* on the arrow/plus sign in front of the word
UVic. This unfolds the project and you can see 4 files labeled:
- configuration.oconf
- control.in.template
- mk.in.template
- uvic.decl
There might also be a `src-gen` folder. Ignore that for now.
- Double clicking on `configuration.oconf` open the editor for the
configuration and parameter selection editor of the CP-DSL. Here you can
explore the settings we currently use with UVic.
- The file uvic.decl contains the declaration of all features, settings and
parameters UVic has.
- The files `control.in.template` and `mk.in.template` contain the templates
for the `control.in` and `mk.in` files used to configure UVic.
- To translate the `configuration.oconf` into a valid UVic setup, you can either
build the project under the menu *Project* > *Build Project* (which might
be grayed out when the IDE is set to automatically build the project) or
by opening `configuration.oconf`, editing something (e.g., adding one white
space) and saving again (Ctrl-S) which triggers the automatic build.
- The generated files can be found in `src-gen`.
MITgcm can be imported in the same way. However, the MITgcm project contains
multiple oconf files. The translate in different subdirectories under src-gen.