Skip to content

Commit 0da767c

Browse files
mkcmsmkcms
committed
Update README to structurize it and provide customization examples
* Makefile (FILL_COMMENTARY): Do not fill lines that contain code. (readme-to-el): Indent code and convert all backticks to elisp style. * README.md: Divide into more sections. Add information about usage with language servers. * compiler-explorer.el: Regenerate commentary.
1 parent ed3952d commit 0da767c

File tree

3 files changed

+131
-28
lines changed

3 files changed

+131
-28
lines changed

‎Makefile‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,11 @@ FILL_COMMENTARY := --eval '(progn
2727
(search-forward "Code:")) \
2828
(goto-char (point-min)) \
2929
(while (re-search-forward "^;; *." nil t) \
30-
(fill-paragraph) \
31-
(end-of-line)) \
30+
(goto-char (line-beginning-position)) \
31+
(if (looking-at-p "^;; +") \
32+
(forward-line 1) \
33+
(fill-paragraph) \
34+
(end-of-line))) \
3235
(save-buffer))'
3336

3437
KEYMAP := --eval '(dolist (elt \
@@ -91,15 +94,18 @@ sandbox: ${ELC}
9194

9295
readme-to-el:
9396
sed README.md -r \
94-
-e 's/^#+ (.*) #*$$/\n;;; \1/' `# Rewrite headers` \
95-
-e '/^.*License.*/,/^<!/d' `# Delete license` \
96-
-e '/^<!--/d' `# Remove comments` \
97-
-e 's/^/;; /' `# Add lisp comment char` \
98-
-e 's/`M-x ([^`]+)`/M-x `\1'"'"'/g' `# Elisp backticks` \
99-
-e 's/Emacs package/Package/g' `# It's obviously for Emacs` \
97+
-e 's/^#+ (.*) #*$$/\n;;; \1/' `# Rewrite headers` \
98+
-e '/^.*License.*/,/^<!/d' `# Delete license` \
99+
-e '/^<!--/d' `# Remove comments` \
100+
-e '/```elisp/,/^```/ s/(.*)/ \1/' `# Indent code` \
101+
-e 's/^/;; /' `# Add lisp comment char` \
102+
-e 's/`M-x ([^`]+)`/M-x `\1'"'"'/g' `# Elisp backticks` \
103+
-e 's/`([^`]+)`/`\1'"'"'/g' `# Elisp backticks` \
104+
-e 's/Emacs package/Package/g' `# It's obviously for Emacs` \
100105
-e 's/(\[compiler[- ]explorer\]){2,}/https:\/\/godbolt.org/g' \
101106
-e '/^;* \[compiler-explorer/d' \
102107
> commentary.txt \
108+
&& sed -i commentary.txt -r -e '/^;; +```/d' \
103109
&& ( sed '1,/^;;; Commentary:/p;d' compiler-explorer.el \
104110
&& echo && cat commentary.txt && echo \
105111
&& sed '/^;;; Code:/,//p;d' compiler-explorer.el ) > changed.txt \

‎README.md‎

Lines changed: 56 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# compiler-explorer.el #
22

3-
Emacs package that provides a simple client for [compiler explorer][compiler-explorer] service.
3+
Emacs package that provides a client for [compiler explorer][compiler-explorer] service.
44

55
## Usage ##
66

@@ -9,25 +9,45 @@ language and display source&compilation buffers. Type something in the source
99
buffer; the compilation buffer will automatically update with compiled asm
1010
code. Another buffer displays output of the compiled and executed program.
1111

12+
### Compilation ###
13+
1214
`M-x compiler-explorer-set-compiler` changes the compiler for current session.
1315

1416
`M-x compiler-explorer-set-compiler-args` sets compilation options.
1517

1618
`M-x compiler-explorer-add-library` asks for a library version and adds it to
1719
current compilation. `M-x compiler-explorer-remove-library` removes them.
1820

21+
### Execution ###
22+
1923
`M-x compiler-explorer-set-execution-args` sets the arguments for the executed
2024
program.
2125

2226
`M-x compiler-explorer-set-input` reads a string from minibuffer that will be
2327
used as input for the executed program.
2428

29+
### Session management ###
30+
31+
`M-x compiler-explorer-new-session` kills the current session and creates a new
32+
one, asking for source language.
33+
34+
`M-x compiler-explorer-previous-session` lets you restore previous sessions.
35+
36+
`M-x compiler-explorer-discard-session` kills the current or selected sessions
37+
and forgets about them forever.
38+
39+
`M-x compiler-explorer-exit` kills the current session.
40+
41+
### ASM ###
42+
2543
`M-x compiler-explorer-browse-opcode-documentation` opens a website that
2644
contains the documentation for the opcode at point.
2745

2846
`M-x compiler-explorer-jump` jumps to ASM block for the source line at point
2947
and vice versa.
3048

49+
### Tools ###
50+
3151
`M-x compiler-explorer-add-tool` asks for the name of a tool, adds it to
3252
current compilation and displays a new buffer showing the tool's output.
3353

@@ -39,16 +59,11 @@ remove.
3959
`M-x compiler-explorer-set-tool-input` reads a string from minibuffer that will
4060
be used as input for an added tool.
4161

42-
`M-x compiler-explorer-load-example` prompts for a name of a builtin example
43-
and loads it.
44-
45-
`M-x compiler-explorer-new-session` kills the current session and creates a new
46-
one, asking for source language.
4762

48-
`M-x compiler-explorer-previous-session` lets you restore previous sessions.
63+
### Other commands ###
4964

50-
`M-x compiler-explorer-discard-session` kills the current or selected sessions
51-
and forgets about them forever.
65+
`M-x compiler-explorer-load-example` prompts for a name of a builtin example
66+
and loads it.
5267

5368
`M-x compiler-explorer-make-link` generates a link for current compilation so
5469
it can be opened in a browser and shared.
@@ -58,7 +73,38 @@ generated by the website or by this package.
5873

5974
`M-x compiler-explorer-layout` cycles between different layouts.
6075

61-
`M-x compiler-explorer-exit` kills the current session.
76+
## Customization
77+
78+
Additional customization is possible via `M-x customize-group`
79+
`compiler-explorer`.
80+
81+
### Usage with language servers
82+
83+
The following snippet sets up the built-in eglot package to start a language
84+
server for each session, and to automatically create and update a
85+
`compile_flags.txt` file (recognized by clangd) to have the same compiler
86+
arguments that are set for the current session. This requires that the
87+
`compiler-explorer-make-temp-file` custom variable is non-nil.
88+
89+
```elisp
90+
91+
(add-hook 'compiler-explorer-new-session-hook #'eglot-ensure)
92+
93+
(defun my/compiler-explorer-params-change-hook (what value)
94+
"Hook run when compilation parameters WHAT change to VALUE."
95+
(pcase what
96+
('compiler-args
97+
(with-current-buffer compiler-explorer--buffer
98+
(when (derived-mode-p 'c-mode 'c++-mode)
99+
(with-temp-file "compile_flags.txt"
100+
(insert (mapconcat #'identity
101+
(split-string-and-unquote value) "\n")))
102+
(when (eglot-current-server)
103+
(eglot-reconnect (eglot-current-server))))))))
104+
105+
(add-hook 'compiler-explorer-params-change-hook
106+
#'my/compiler-explorer-params-change-hook)
107+
```
62108

63109
## License ##
64110

‎compiler-explorer.el‎

Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
;;
3131
;;; compiler-explorer.el
3232
;;
33-
;; Package that provides a simple client for https://godbolt.org service.
33+
;; Package that provides a client for https://godbolt.org service.
3434
;;
3535
;;
3636
;;; Usage
@@ -41,6 +41,9 @@
4141
;; compiled asm code. Another buffer displays output of the compiled and
4242
;; executed program.
4343
;;
44+
;;
45+
;;; Compilation
46+
;;
4447
;; M-x `compiler-explorer-set-compiler' changes the compiler for current
4548
;; session.
4649
;;
@@ -50,18 +53,41 @@
5053
;; it to current compilation. M-x `compiler-explorer-remove-library'
5154
;; removes them.
5255
;;
56+
;;
57+
;;; Execution
58+
;;
5359
;; M-x `compiler-explorer-set-execution-args' sets the arguments for the
5460
;; executed program.
5561
;;
5662
;; M-x `compiler-explorer-set-input' reads a string from minibuffer that
5763
;; will be used as input for the executed program.
5864
;;
65+
;;
66+
;;; Session management
67+
;;
68+
;; M-x `compiler-explorer-new-session' kills the current session and
69+
;; creates a new one, asking for source language.
70+
;;
71+
;; M-x `compiler-explorer-previous-session' lets you restore previous
72+
;; sessions.
73+
;;
74+
;; M-x `compiler-explorer-discard-session' kills the current or selected
75+
;; sessions and forgets about them forever.
76+
;;
77+
;; M-x `compiler-explorer-exit' kills the current session.
78+
;;
79+
;;
80+
;;; ASM
81+
;;
5982
;; M-x `compiler-explorer-browse-opcode-documentation' opens a website
6083
;; that contains the documentation for the opcode at point.
6184
;;
6285
;; M-x `compiler-explorer-jump' jumps to ASM block for the source line at
6386
;; point and vice versa.
6487
;;
88+
;;
89+
;;; Tools
90+
;;
6591
;; M-x `compiler-explorer-add-tool' asks for the name of a tool, adds it
6692
;; to current compilation and displays a new buffer showing the tool's
6793
;; output.
@@ -75,17 +101,12 @@
75101
;; M-x `compiler-explorer-set-tool-input' reads a string from minibuffer
76102
;; that will be used as input for an added tool.
77103
;;
78-
;; M-x `compiler-explorer-load-example' prompts for a name of a builtin
79-
;; example and loads it.
80104
;;
81-
;; M-x `compiler-explorer-new-session' kills the current session and
82-
;; creates a new one, asking for source language.
83105
;;
84-
;; M-x `compiler-explorer-previous-session' lets you restore previous
85-
;; sessions.
106+
;;; Other commands
86107
;;
87-
;; M-x `compiler-explorer-discard-session' kills the current or selected
88-
;; sessions and forgets about them forever.
108+
;; M-x `compiler-explorer-load-example' prompts for a name of a builtin
109+
;; example and loads it.
89110
;;
90111
;; M-x `compiler-explorer-make-link' generates a link for current
91112
;; compilation so it can be opened in a browser and shared.
@@ -95,7 +116,37 @@
95116
;;
96117
;; M-x `compiler-explorer-layout' cycles between different layouts.
97118
;;
98-
;; M-x `compiler-explorer-exit' kills the current session.
119+
;; ## Customization
120+
;;
121+
;; Additional customization is possible via M-x `customize-group'
122+
;; `compiler-explorer'.
123+
;;
124+
;; ### Usage with language servers
125+
;;
126+
;; The following snippet sets up the built-in eglot package to start a
127+
;; language server for each session, and to automatically create and
128+
;; update a `compile_flags.txt' file (recognized by clangd) to have the
129+
;; same compiler arguments that are set for the current session. This
130+
;; requires that the `compiler-explorer-make-temp-file' custom variable is
131+
;; non-nil.
132+
;;
133+
;;
134+
;; (add-hook 'compiler-explorer-new-session-hook #'eglot-ensure)
135+
;;
136+
;; (defun my/compiler-explorer-params-change-hook (what value)
137+
;; "Hook run when compilation parameters WHAT change to VALUE."
138+
;; (pcase what
139+
;; ('compiler-args
140+
;; (with-current-buffer compiler-explorer--buffer
141+
;; (when (derived-mode-p 'c-mode 'c++-mode)
142+
;; (with-temp-file "compile_flags.txt"
143+
;; (insert (mapconcat #'identity
144+
;; (split-string-and-unquote value) "\n")))
145+
;; (when (eglot-current-server)
146+
;; (eglot-reconnect (eglot-current-server))))))))
147+
;;
148+
;; (add-hook 'compiler-explorer-params-change-hook
149+
;; #'my/compiler-explorer-params-change-hook)
99150
;;
100151
;;
101152

0 commit comments

Comments
 (0)