4.8 Command line
The IDE also works in a terminal, without a window. validate checks a project and ends. run validates a project, runs it with its bridges in the IDE's Docker container and prints what happens until it is stopped.
4.8.1 Commands#
Usage:
karpfen-ide [<folder>]
karpfen-ide validate <folder> [--format text|json]
karpfen-ide run <folder> [--descriptor <file>] [--bridge <file>]... [--capture] [--verbose]
| Command | Effect |
|---|---|
karpfen-ide <folder> | Opens the window on the folder. Without a folder the window opens on its welcome view. |
karpfen-ide validate <folder> | Validates the whole project, prints the findings and ends. |
karpfen-ide run <folder> | Validates the project, runs it and prints what happens until it is stopped. |
karpfen-ide validate --help, karpfen-ide run --help | Prints the usage and ends with status 0. -h does the same. |
Options may stand before or after the folder. A value follows its option as the next argument or after =, as in --bridge=http.kbridge.json. -- ends the options, so a folder after it may start with -. A folder that is itself named validate or run must be written with a path in front, as in ./run, when it is the first argument.
A wrong command line prints karpfen-ide: and what is wrong, then the usage, on the error output, and ends with status 2. Wrong are an unknown option, a missing, second or empty folder, a folder that does not exist, an option without its value, a second --descriptor or --format, a format other than text or json, a bridge named twice, and an option that the command does not take.
karpfen-ide: unknown option '--frmat'
4.8.2 Starting it#
| From | Command |
|---|---|
| The sources | ./gradlew :app:ide:run --args="validate /absolute/path/to/project" |
| The application on macOS | karpfen-ide.app/Contents/MacOS/karpfen-ide validate <folder> |
| The application on Linux | karpfen-ide/bin/karpfen-ide validate <folder> |
| The application on Windows | karpfen-ide\karpfen-ide.exe validate <folder> |
From the sources the folder must be an absolute path. ./gradlew :app:ide:createDistributable builds the application into app/ide/build/compose/binaries/main/app/. On Windows the application is built with a console, so the commands have somewhere to print, and opening the window by a double-click also opens a console window.
4.8.3 Validating#
karpfen-ide validate examples/lamp
The command runs the same checks as Validate in the window, see 4.4 Validating. It prints one line per finding, errors first, and then a summary. A project without findings prints No problems found.
lamp.kstates:13: error: mismatched input 'STATMACHINE' expecting 'STATEMACHINE'
switch.kstates:8: warning: This EVAL has no return, so it yields no value; return the value it computes
1 error and 1 warning
The language features are those of the .karpfenproject file of the folder, see 4.1.7 Language features. karpfen-ide validate examples/spares checks the example with attachable state machines, whose project file switches on macros. A finding about a behaves after is printed at the line of the metamodel, as in spares.kmeta:4: error: ....
With --format json it prints one JSON document instead, for a program to read.
karpfen-ide validate examples/lamp --format json
{
"root": "/home/me/karpfen-IDE/examples/lamp",
"errorCount": 1,
"warningCount": 1,
"problems": [
{
"path": "lamp.kstates",
"line": 13,
"column": 1,
"severity": "error",
"message": "mismatched input 'STATMACHINE' expecting 'STATEMACHINE'",
"code": "syntax-error"
},
{
"path": "switch.kstates",
"line": 8,
"column": 33,
"severity": "warning",
"message": "This EVAL has no return, so it yields no value; return the value it computes",
"code": "kstates.eval-without-return"
}
]
}
| Member | Meaning |
|---|---|
root | The folder of the project, as an absolute path. |
errorCount, warningCount | How many errors and warnings the project has. |
problems | The findings, sorted by path, line and column. |
path | The file, relative to the folder. |
line, column | Where the finding starts. Both count from 1. |
severity | error, warning, info or hint. |
message | What is wrong, in words. |
code | The stable name of the kind of finding. |
4.8.4 Running#
karpfen-ide run examples/lamp --descriptor lamp.kenv.json --bridge http.kbridge.json --capture
| Option | Meaning |
|---|---|
--descriptor <file> | The descriptor to run, relative to the folder or absolute. It can be left out when the project has exactly one. |
--bridge <file> | A bridge file of the project to start with the run. Give the option once per bridge. Without it no bridge starts. |
--capture | Writes the log of the run to a file in karpfen-runs/, as Capture run to file does in the window, see 4.5.8 Captured logs. |
--verbose | Also prints every line of the runtime's log. |
The choice of files is checked against the project, and a wrong choice ends with status 2, a message and the usage.
| Case | Message |
|---|---|
| The project has no descriptor. | the project has no environment descriptor (*.kenv.json) |
The project has several descriptors, and --descriptor is missing. | the project has several environment descriptors; choose one with --descriptor: and the list |
--descriptor names no descriptor of the project. | <file> is no environment descriptor of the project; and the list |
--bridge names no bridge file of the project. | <file> is no bridge file of the project; and the list |
A run goes through these steps.
-
It validates the whole project. With an error it prints the findings as
validatedoes and does not run. With warnings only it prints them the same way, thenThe run goes on despite the warnings., and runs. - It starts the runtime in the IDE's Docker container. The first run builds the runtime image.
- It deploys the descriptor and starts the bridges.
- It prints what happens until you stop it with Ctrl+C or a terminate signal.
- It stops the bridges and the environment, removes the runtime container and ends.
Stopping the environment in step 5 also drops it, so the runtime forgets it before the container goes. A run whose environment another client stops or drops ends with The run ended on its own., as 4.5.5 Stopping a run describes.
This is what a run of the lamp with one bridge prints. The switch is pressed once through the bridge, and then the run is stopped. The first run prints a line for each step of building the image as well.
Running lamp.kenv.json with http.kbridge.json
Docker: not started
Run lamp: preparing
Run lamp: waiting for the runtime
Docker: checking the Docker engine
Docker: creating the container
Docker: starting the container
Docker: waiting for the runtime
Docker: running at 127.0.0.1:65457
Run lamp: deploying
http.kbridge.json: not running
Checking the runtime at http://127.0.0.1:65457: done, The runtime is up and supports the IDE
Creating the environment: done, env-1794579423685
Connecting to the environment: done, Connected as karpfen-ide-254666e10161
Uploading lamp.kmeta: done
Uploading lamp-events.kmeta: done
Uploading lamp.kmodel: done
Attaching lamp.kstates to lamp: done
Attaching switch.kstates to wallSwitch: done
Setting the tick delay to 500 ms: done
Setting the event time to live to 5000 ms: done
Listening to 2 event domains: done, service, switch
Switching on runtime features: skipped, The project switches on no language feature that needs one
Activating the environment: done
Switching observation on: done, The runtime read the model as analyzed
Starting the environment: done
14:17:03.888 lamp starts in off
14:17:03.890 wallSwitch starts in down
14:17:03.892 engine Engine started with 2 state machine(s), tickDelay=500ms
14:17:03.895 lamp runs the entry actions of off
lamp: off
wallSwitch: down
Confirming the start: done, Every state machine reported its state
Run lamp: running
http.kbridge.json: starting
http.kbridge.json: running, 0 in, 0 out
14:17:04.896 lamp off -> full
14:17:04.898 wallSwitch down -> up
lamp: on > full
wallSwitch: up
14:17:05.397 lamp runs the entry actions of on
14:17:05.399 lamp runs the entry actions of full
14:17:05.414 wallSwitch runs the entry actions of up
Stop requested.
Shutting down the run and its bridges, then the runtime.
Run lamp: stopped
http.kbridge.json: not running
14:17:06.405 engine Engine stopped after 5 ticks
Docker: not started
Shut down.
| Line | Meaning |
|---|---|
Running <descriptor> with <bridges> | What the run was asked to do. , captured to a file is added with --capture, and , parallel branches on threads of their own while the project has Parallel branches on threads switched on, see 4.1.7 Language features. |
Docker: ... | What the runtime container does, in the words of the Runtime tool window. |
Run <name>: <phase> | The phase of the run, as in 4.5.4.2 The runs. |
<step>: done, skipped or failed, with a detail | A step of the deployment. |
<object>: <states>, <object> (<definition>): <states> | The active states of the state machine instance on that object, whenever the runtime reports new ones. An instance of a definition also names its definition. An instance that ends and a later one on the same object are two instances, so the first states of the later one are printed too. |
<bridge file>: ... | The state of a bridge, and once it runs how many messages it took in and sent out. |
<time> <object> <text> | A line of the simplified log, as the Log pane shows it. |
<severity>: <file>:<line>:<column>: <message> | A problem of the preparation or the run. |
[stdout] ..., [stderr] ... | A line of the runtime's log, with --verbose. |
Captured to karpfen-runs/<file> | Where the run is captured. |
Stop requested., Shutting down ..., Shut down. | The end of the run. What the bridges and the runtime say while they stop stands in between. |
A descriptor with definitions uploads each of them in a step Uploading the definition <file>. The objects get and lose instances of the definitions while the run goes on, and the simplified log says so in lines such as bulb attaches glowing, bulb exchanges glowing for flickering and bulb detaches flickering, see 4.5.4.7 State machine instances. This is part of what a run of examples/spares prints when the event flicker comes in:
bulb (glowing): lit
spare (glowing): lit
14:20:16.500 bulb exchanges glowing for flickering
14:20:16.501 bulb starts in on
bulb (flickering): on
A descriptor with fragments uploads each of them in a step Uploading the fragment <file>. The states of a fragment carry the name of their container state in front, so a run of examples/pages prints lines such as lamp: self test > self test/wiring > self test/wiring/measuring, see 4.5.4.8 Pages.
A run that does not get going says why and ends with one of these lines.
| Line | Status |
|---|---|
The run does not start: the project has errors. | 1 |
The run did not start. | 3 |
The run does not start: the deployment is blocked. | 3 |
The run failed. | 3 |
The run ended on its own. | 3 |
4.8.5 What a run reads from the project#
A run without a window takes one thing from .karpfenproject: which features are on, the optional language features and the features of the project such as Parallel branches on threads. Everything else in that file, such as the bridges ticked in the window, is ignored. Nothing is written, neither to .karpfenproject nor to the settings of the user. A run without a window has no debugger, so breakpoints never halt it, also when the project has them switched on. It has no time limit and ends only when it is stopped.
4.8.6 Exit statuses#
| Status | Meaning |
|---|---|
| 0 | The validation found no error. Warnings are allowed. Also after --help. |
| 1 | The project has errors. A run did not start. |
| 2 | The command line was wrong. A message and the usage are printed. |
| 3 | A run could not start, failed or ended on its own, or the folder could not be opened as a project. |
A run that is stopped by a signal ends with the status the system gives a process that got that signal. A run started through Gradle therefore makes the Gradle task fail when it is stopped.