# ForSyDe DevTools Visualizer

This is the [ForSyDe DevTools](https://github.com/sthaeron/forsyde-devtools/)
stripped-down visualizer. It still contains parts of the compiler since these
are needed by the visualizer.

## JSON schema derived types
[`src/SKGraphSchema.hs`](src/SKGraphSchema.hs) includes the schema-derived
types, as specified by
[SKGraphSchema.json](https://github.com/kieler/klighd-vscode/blob/main/schema/klighd/SKGraphSchema.json).
Some additional types have also been added from the [KLighD-VSCode
source](https://github.com/kieler/klighd-vscode/blob/main/packages/klighd-core/src/skgraph-models.ts)
which were not yet present in the schema at the time when implementation was
started.

It has a top to bottom hierarchy in contrast to the bottom-up inheritance based
structure in the schema due to the design of Haskell's type system. Each type
has a JSON encoder defined mapping it to the schema.

## Language server
[`src/LSP.hs`](src/LSP.hs) contains the language server implementation as well
as the transformation from the source model consumed by the visualizer (ForSyDe
IR) into SKGraphSchema. The language server implements the diagram server
protocol and communicates with the diagram client.

## VS Code extension
[vscode-ext](vscode-ext) contains the source for the VS Code extension
utilizing [KLighD-VSCode](https://github.com/kieler/klighd-vscode).

## Other files
For the visualizer to run, it also needs the files:
- [`src/ArgumentsLSP.hs`](src/ArgumentsLSP.hs): Defines the command line
  parameters for the language server.
- [`src/ForSyDeIR.hs`](src/ForSyDeIR.hs): The source model for the visualizer,
  representing an SDF graph.
- [`src/SDFSchedule.hs`](src/SDFSchedule.hs): The part of the compiler which
  schedules the SDF graph represented by ForSyDe IR.
- [`src/CoreIR.hs`](src/CoreIR.hs): Helper functions for interacting with GHC
  Core. Used to transform ForSyDe-Shallow SDF models into the visualizer source
  model.
- [`src/CoreIRToForSyDeIR.hs`](src/CoreIRToForSyDeIR.hs): The part of the
  compiler which transforms the GHC Core input into the visualizer source
  model.
- [`src/Utilities.hs`](src/Utilities.hs): Various helper functions, e.g. to
  compile a source file into GHC Core.

## Building and running

The ForSyDe DevTools compiler and LSP have been developed using a specific
version of the GHC API as the frontend. The current version of GHC being used
is `9.10.2`. We suggest installing this specific version of GHC using `ghcup`.
The installation instructions for `ghcup` can be found
[here](https://www.haskell.org/ghcup/install/); all config options can be left
as default.

Once you have `ghcup` installed, you can use the following commands to install
and set GHC `9.10.2` as your current version:

```
ghcup install ghc 9.10.2
ghcup set ghc 9.10.2
```

The ForSyDe DevTools LSP depends on the OpenBLAS and LAPACK external libraries.
These have to be installed separately, using your system's package manager. For
a Debian-based system, this would be:

```
apt install libblas-dev liblapack-dev
```

To be able to run the ForSyDe DevTools LSP without using `stack` or `cabal`,
the ForSyDe Shallow library needs to be installed globally on your system. This
can be done with the following command:

```sh
cabal v1-install forsyde-shallow
```

If this command fails, it's still possible to run the language server via
stack: `stack run forsyde-lsp-exe`, or the binary with the parameter
`--forsyde-pkgpath` set to the line of `find $HOME/.stack -name
'*forsyde-shallow*' | grep -o '^.*/pkgdb'` which matches with the GHC version,
9.10.2. If multiple are visible, then pick any.

From this point, you can simply use `stack install` to build and install the
language server.

This will install the and LSP to `~/.local/bin`. Make sure this directory is in
your shell path. Check by running `echo $PATH`. If it is not included, add
`export PATH="$HOME/.local/bin:$PATH"` to your shell configuration file. Then
reinitialize your terminal shell.

If you have successfully installed and added the compiler and LSP executables
to your shell path, you should be able to run `forsyde-lsp-exe --help`.

Install the VS Code extensions [KLighD
Diagrams](https://marketplace.visualstudio.com/items?itemName=kieler.klighd-vscode)
and
[Haskell](https://marketplace.visualstudio.com/items?itemName=haskell.haskell).
In addition, you also need
[npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager)
for building the extension (ideally NodeJS 22 or later.
[NVM](https://github.com/nvm-sh/nvm) can be used if the host OS does not have
the right version).

To build and install the VS Code extension:
```sh
cd ./vscode-ext
npm install
npm run compile
./node_modules/vsce/vsce package
code --install-extension forsyde-vscode-extension-0.1.0.vsix
cd ..
```

If you had trouble with the `cabal v1-install forsyde-shallow` command, you
need to give the package path manually to VS Code. Open VS Code settings and
search for forsyde. Follow the instructions on the configuration entry (should
be similar instructions as from above).

Turn on *Settings>Render Options>Debug Options* and *Settings>Preferences>Client
Layout* in the diagram window if the diagram is not visible.

The visualizer can also be run with the [KLighD
CLI](https://github.com/kieler/klighd-vscode/releases) application without the source code next to it in the view. You can also use the `../client-binary/klighd-linux` binary included in this package in the instructions below.
```sh
stack run forsyde-lsp-exe
# In another terminal:
./klighd-linux --ls_port 5007 examples/model/SDF_example_002.hs
# Or:
./klighd-linux --ls_port 5007 serve
```
