literate-programming/guide.md

• About
• Setup
  • Installing Emacs
  • Installing required Emacs packages
  • Configuring Emacs using Elisp code
• Test
  • Running geiser
  • Literate programming document
• Report

About

This section aims to provide the minimal steps required to get literate programming in org-mode working for GNU Guile.

Setup

Installing Emacs

We will use GNU Guix to create a reproducible environment, in which we will run Emacs, install Emacs packages and configure Emacs using Elisp code.

Reproducible Emacs using GNU Guix

Create manifest.scm

cat <<EOT > manifest.scm
(specifications->manifest
 '("gnutls"
   "guile"
   "bash"
   "emacs"))
EOT

cat manifest.scm

Create channels.scm

guix describe --format='channels' > 'channels.scm'
cat 'channels.scm'

(list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (branch #f) (commit "a1cb645d83") (introduction (make-channel-introduction "9edb3f66fd" (openpgp-fingerprint "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))

Install packages

command -V guile
ls -al $(command -V guile)

# compare to guile installed in the environment created via guix shell:

guix time-machine \
     --channels="channels.scm" -- \
     shell \
     --cores=8 \
     --manifest="manifest.scm" -- \
     which guile && ls -al $(which guile)

Command for running Emacs inside reproducible environment

guix time-machine \
     --channels="channels.scm" -- \
     shell \
     --cores=8 \
     --pure \
     --container \
     --network \
     --no-cwd \
     --preserve='TERM' \
     --manifest="manifest.scm" -- \
     emacs \
     --no-init-file \
     --no-site-file \
     --no-site-lisp \
     --no-splash \
     --no-x-resources \
     --no-desktop \
     --no-loadup \
     --no-window-system

Or with graphical window:

guix time-machine \
     --channels="channels.scm" -- \
     shell \
     --cores=8 \
     --pure \
     --container \
     --network \
     --no-cwd \
     --share=/tmp/.X11-unix \
     --preserve='DISPLAY' \
     --preserve='TERM' \
     --manifest="manifest.scm" -- \
     emacs \
     --no-init-file \
     --no-site-file \
     --no-site-lisp \
     --no-splash \
     --no-x-resources \
     --no-desktop \
     --no-loadup

Installing required Emacs packages

Add melpa-stable package repository

To install geiser, we need to add the package repository, from which we can pull it.

Run the following elisp code:

(require 'package)
;; (add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)

Install org

org is already installed. Not sure how to tell Emacs, that it should instead install org from GNU Elpa, so do this manually:

• M-x list-pack RET
• search for org from GNU Elpa
• install org

Installing geiser-guile

As Elisp code:

(package-install 'geiser-guile)

Configuring Emacs using Elisp code

The following Elisp code needs to be evaluated, to be able to evaluate org source blocks of Scheme code using GNU Guile:

;; Tell Emacs to use the command `guile` to evaluate Scheme
;; code.
(setq scheme-program-name "guile")

;; The following enables source blocks of specific
;; programming languages to be executed. By default only
;; elisp is allowed to be executed. First we define an
;; association list of languages to booleans, which enable
;; or disable support for a language.
(setq org-babel-load-languages
      '((scheme . t)))

;; Then we use org-babel-do-load-languages to actually tell
;; org babel, that the languages should be supported.
(org-babel-do-load-languages
 'org-babel-load-languages
 '((scheme . t)))

;; The following defines a procedure, which determins, which
;; source blocks of programming languages can be run without
;; confirmation, depending on the language. The procedure
;; can then be used as org-confirm-babel-evaluate value.
(defun xiaolong/org-confirm-babel-evaluate (lang body)
  (not
   (or (string= lang "scheme"))))

;; Set a procedure predicate for org babel, to determin, which languages can
;; be run without confirmation.
(setq org-confirm-babel-evaluate 'xiaolong/org-confirm-babel-evaluate)

Test

Running geiser

Run geiser-guile using the following command:

M-x run-geiser RET

Since only geiser-guile is installed, this should start a Geiser Guile REPL.

Literate programming document

Now we should be all set to try some literate programming in Scheme.

Here is an example document:

cat example.org

1. Open a new .org file.
2. Paste the example.org document into the buffer of the .org file.
3. Place the cursor inside the usemember source block.
4. Input C-c C-c to evaluate the source block.

Report

The above does not seem to work. The result of the example source block is merely the following:

Geiser Interpreter produced no output