summaryrefslogtreecommitdiff
path: root/readme.org
blob: 3b8a6ca542489b0ab109617f43de63b0827f6b02 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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
#+TITLE: Geiser and Guile talk to each other
#+OPTIONS: d:nil
#+EXPORT_FILE_NAME: geiser-guile.texi
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Geiser Guile: (geiser-guile).
#+TEXINFO_DIR_DESC: Support for Guile in Geiser

* Overview

This package provides support for using [[https://www.gnu.org/software/guile/][GNU Guile]] in Emacs with
[[http://geiser.nongnu.org][Geiser]].

Provided [[https://gitlab.com/emacs-geiser/geiser][geiser]] is installed in your system, if this package's
directory is in your load path, just add ~(require 'geiser-guile)~ to
your initialisation files and then ~M-x geiser-guile~ to start a REPL.
Scheme files with a Guile module declaration should be automatically
recognised as Guile-flavoured Geiser buffers.

The easiest way of installing this package is using NonGNU Elpa or
MELPA.  If you're in Emacs 28 or higher, the former is already enabled
and all you need is the familiar

#+begin_src elisp
  M-x install-package RET geiser-guile RET
#+end_src

That will also install geiser, and its fine info manual.  Please refer
to it (or its [[https://geiser.nongnu.org][online version]]) for a general description of how geiser
schemes work.  We provide below some additional details specific to
geiser-guile.

* Start up

  When launching the Guile REPL, geiser will invoke the binary
  configured in ~geiser-guile-binary~ (simply "guile" by default)
  which in turn will load ~geiser-guile-init-file~, if any.

  Note, however, that specifying ~geiser-guile-init-file~ is /not/
  equivalent to changing Guile's initialization file (=~/.guile=),
  because the former is loaded using the =-l= flag, together with =-q=
  to disable loading the second.  But there are subtle differences
  in the way Guile loads the initialization file versus how it loads
  a file specified via the =-l= flag.  If what you want is just
  loading =~/.guile=, leave ~geiser-guile-init-file~ alone and set
  ~geiser-guile-load-init-file~ to ~t~ instead.

  One can also provide a global list of paths to add to Guile's
  =%load-path= via ~geiser-guile-load-path~.

* Texinfo docstrings

  You can enable processing of texinfo in docstrings by customizing
  ~geiser-guile-doc-process-texinfo~ to a non-nil value.  If enabled and
  docstring is a valid texinfo snippet, it will be converted into a plain text
  before being displayed.

* Debugging support

  Guile supports all the debugger commands supported by Geiser (it's
  in fact used as the reference for the implementation and design of
  that support).  When the REPL would normally enter its debug mode,
  with a prompt of the style:

      scheme@(guile-user) [1]>

  showing a debugging level, Geiser will instead bring you to the
  =*Geiser Dbg*= buffer, where you can access a menu of debugging
  commands via the ~,~ (comma) key.

  The geiser-guile customization group will show you, among many
  other, a few flags fine-tuning interaction with the debugger, as
  well as things like the detail level of error messages (e.g. via
  ~geiser-guile-warning-level~).

* Tramp support
  Geiser guile can be used remotely via tramp connections: the REPL
  process will be run in the machine where the tramp-accessed file
  lives.  Implemented by Felipe Lema.