Skip to content

Commit 26f9cac

Browse files
dmjiodmjio
authored
Doc updates. Add osx homebrew omp section. (#18)
1 parent 6f335a2 commit 26f9cac

File tree

1 file changed

+92
-56
lines changed

1 file changed

+92
-56
lines changed

‎README.md

Lines changed: 92 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
# Haskell ESTGi Debugger
22

3+
# Table of Contents
4+
1. [Introduction](#introduction)
5+
2. [Overview](#overview)
6+
3. [Setup](#setup)
7+
4. [Development](#development)
8+
9+
## Introduction
10+
311
This repository contains the components for Haskell debugging based on the Debug Adapter Protocol ([DAP](https://microsoft.github.io/debug-adapter-protocol)).
412

5-
* [`dap/`](dap/): Language and backend independent simple DAP library
6-
* [`dap-estgi-server/`](dap-estgi-server/): DAP server for External STG Interpreter (DAP-ESTGi)
7-
* [`dap-estgi-vscode-extension/`](dap-estgi-vscode-extension/): VSCode extension to support Haskell debugging using DAP-ESTGi server
13+
- [`dap/`](dap/): Language and backend independent simple DAP library
14+
- [`dap-estgi-server/`](dap-estgi-server/): DAP server for External STG Interpreter (DAP-ESTGi)
15+
- [`dap-estgi-vscode-extension/`](dap-estgi-vscode-extension/): VSCode extension to support Haskell debugging using DAP-ESTGi server
816

917
## Overview
1018

@@ -13,65 +21,93 @@ VSCode offers a nice debugger UI while the debugger features are provided by the
1321

1422
```mermaid
1523
flowchart LR
16-
subgraph User Interface
17-
A(VSCode) -.- |Plugin API| B(DAP ESTGi Extension)
18-
end
19-
B <-->|DAP via network| C(DAP ESTGi Server)
20-
subgraph Debugger
21-
C -.- |HS library API| D(External STG Interpreter)
22-
end
24+
subgraph User Interface
25+
A(VSCode) -.- |Plugin API| B(DAP ESTGi Extension)
26+
end
27+
B <-->|DAP via network| C(DAP ESTGi Server)
28+
subgraph Debugger
29+
C -.- |HS library API| D(External STG Interpreter)
30+
end
2331
2432
```
2533

2634
The `dap-estgi-server` and `dap-estgi-vscode-extension` are application specific components, while the
2735
`dap` library is designed to be application independent to support any project that needs a simple DAP framework.
2836

2937
## Setup
38+
- Enable `allow breakpoints everywhere` option in VSCode settings.
39+
40+
### Run `dap-estgi-extension`
41+
- Run `(cd dap-estgi-vscode-extension ; npm install)`
42+
- Open `dap-estgi-vscode-extension` folder by using the `Files/Open Folder` menu.
43+
- Open the `src/extension.ts` file.
44+
- Press F5 to run the extension in a new VSCode [Extension Development Host] window.
3045

31-
1. VSCode setup
32-
Enable `allow breakpoints everywhere` option in VSCode settings.
33-
2. Run `dap-estgi-extension`
34-
* Run: `(cd dap-estgi-vscode-extension ; npm install)`
35-
* Open `dap-estgi-vscode-extension` folder by using the `Files/Open Folder` menu.
36-
* Open the `src/extension.ts` file.
37-
* Press F5 to run the extension in a new VSCode [Extension Development Host] window.
38-
3. Start `dap-estgi-server`
46+
### Start `dap-estgi-server`
3947
`(cd dap-estgi-server ; stack run)`
40-
4. Compile debuggee program with GHC-WPC using stack
41-
* Add the following lines to debuggee's `stack.yaml`:
42-
```
43-
# use custom ext-stg whole program compiler GHC
44-
compiler: ghc-9.2.7
45-
compiler-check: match-exact
46-
ghc-variant: wpc
47-
setup-info:
48-
ghc:
49-
linux64-custom-wpc-tinfo6:
50-
9.2.7:
51-
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-x86_64-unknown-linux.tar.xz"
52-
macosx-custom-wpc:
53-
9.2.7:
54-
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-x86_64-apple-darwin.tar.xz"
55-
macosx-aarch64-custom-wpc:
56-
9.2.7:
57-
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-aarch64-apple-darwin.tar.xz"
58-
```
59-
* Run: `stack build`
60-
i.e. build the provided sample hello world: `(cd sample-program-to-debug ; stack build)`
61-
5. Open debuggee program in VSCode [Extension Development Host]
62-
* Open debugge project folder by using the `Files/Open Folder` menu.
63-
* Select the debug view on the side bar
64-
* Click to `create a launch.json file`, then select `Haskell DAP ESTGi`
65-
* Press F5 or the `Play` button to start debugging
66-
67-
## Setup in video
68-
1. VSCode setup
69-
![](docs-images/dap-01-vscode-setup-5fps.avif)
70-
2. Run `dap-estgi-extension`
71-
![](docs-images/dap-02-run-dap-estgi-extension-5fps.avif)
72-
3. Start `dap-estgi-server`
73-
![](docs-images/dap-03-start-dap-estgi-server-5fps.avif)
74-
4. Compile debuggee program with GHC-WPC using stack
75-
![](docs-images/dap-04-compile-debuggee-5fps.avif)
76-
5. Open debuggee program in VSCode [Extension Development Host]
77-
![](docs-images/dap-05-open-debuggee-in-vscode-5fps.avif)
48+
49+
**Note**: If using Darwin OSX and you receive
50+
51+
```
52+
external-stg-interpreter> * Missing (or bad) C library: omp
53+
external-stg-interpreter> This problem can usually be solved by installing the system package that
54+
external-stg-interpreter> provides this library (you may need the "-dev" version). If the library is
55+
external-stg-interpreter> already installed but in a non-standard location then you can use the flags
56+
external-stg-interpreter> --extra-include-dirs= and --extra-lib-dirs= to specify where it is.If the
57+
external-stg-interpreter> library file does exist, it may contain errors that are caught by the C
58+
external-stg-interpreter> compiler at the preprocessing stage. In this case you can re-run configure
59+
external-stg-interpreter> with the verbosity flag -v3 to see the error messages.
60+
```
61+
62+
Try installing `libomp` from [brew](https://formulae.brew.sh/formula/libomp) and then running:
63+
64+
65+
```bash
66+
$ stack run --extra-include-dirs=/usr/local/opt/libomp/include --extra-lib-dirs=/usr/local/opt/libomp/lib
67+
```
68+
69+
### Compile debuggee program with GHC-WPC using stack
70+
- Add the following lines to debuggee's `stack.yaml`:
71+
72+
```yaml
73+
# use custom ext-stg whole program compiler GHC
74+
compiler: ghc-9.2.7
75+
compiler-check: match-exact
76+
ghc-variant: wpc
77+
setup-info:
78+
ghc:
79+
linux64-custom-wpc-tinfo6:
80+
9.2.7:
81+
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-x86_64-unknown-linux.tar.xz"
82+
macosx-custom-wpc:
83+
9.2.7:
84+
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-x86_64-apple-darwin.tar.xz"
85+
macosx-aarch64-custom-wpc:
86+
9.2.7:
87+
url: "https://github.com/grin-compiler/foundation-pak/releases/download/ghc-9.2.7/ghc-9.2.7-aarch64-apple-darwin.tar.xz"
88+
```
89+
- Run `stack build`
90+
i.e. build the provided sample hello world: `(cd sample-program-to-debug ; stack build)`
91+
92+
### Open debuggee program in VSCode [Extension Development Host]
93+
- Open debugge project folder by using the `Files/Open Folder` menu.
94+
- Select the debug view on the side bar
95+
- Click to `create a launch.json file`, then select `Haskell DAP ESTGi`
96+
- Press F5 or the `Play` button to start debugging
97+
98+
## Development
99+
100+
### Allow breakpoints everywhere
101+
![](docs-images/dap-01-vscode-setup-5fps.avif)
102+
103+
### Run `dap-estgi-extension`
104+
![](docs-images/dap-02-run-dap-estgi-extension-5fps.avif)
105+
106+
### Start `dap-estgi-server`
107+
![](docs-images/dap-03-start-dap-estgi-server-5fps.avif)
108+
109+
### Compile debuggee program with GHC-WPC using stack
110+
![](docs-images/dap-04-compile-debuggee-5fps.avif)
111+
112+
### Open debuggee program in VSCode [Extension Development Host]
113+
![](docs-images/dap-05-open-debuggee-in-vscode-5fps.avif)

0 commit comments

Comments
 (0)