GOPHERSPACE.DE - P H O X Y
gophering on gopher.beastieboy.net
    _______________________________

     INSTALLING STUMPWM ON FREEBSD

     Nicolas Herry
    _______________________________


       2017/03/10


Table of Contents
_________________

1 Installing StumpWM on FreeBSD
.. 1.1 How to install StumpWM
..... 1.1.1 Install SBCL
..... 1.1.2 Install Quicklisp
..... 1.1.3 Install StumpWM
..... 1.1.4 Get emacs hook up to StumpWM sessions
..... 1.1.5 Configure your X session





1 Installing StumpWM on FreeBSD
===============================

  There is an [excellent guide] describing in details how to install
  [StumpWM] and start playing with it interactively through emacs and
  SLIME. There are, however, a few things that have changed since this
  guide has been written, or just some traps I fell into that I thought
  I should describe as well.


[excellent guide]
http://www.kaashif.co.uk/2015/06/28/hacking-stumpwm-with-common-lisp/

[StumpWM] http://stumpwm.github.io/

1.1 How to install StumpWM
~~~~~~~~~~~~~~~~~~~~~~~~~~

  The official documentation recommends checking out the code from the
  repository, installing the dependencies with Quicklisp and
  /configure-make-make-installing/ the source code. I used to do just
  that for years and it works very well. However, before I read the
  guide, I did not realise there was another option: installing StumpWM
  itself through Quicklisp. That way, you obtain a proper release (not
  just whatever current code happens to be in GitHub), a clean
  installation in your Quicklisp repository and an easy way to hook up
  an interactive session to it.


1.1.1 Install SBCL
------------------

  The first step is indeed to install a Lisp compiler. David Bjergaard,
  StumpWM's current maintainer and main developer [has recently
  announced that only SBCL will be supported in the future], which has
  the merit of cutting short the question of which implementation to
  choose. There is a catch however: [there used to be some problems with
  threading support for SBCL on FreeBSD]. Everything is fine now, and
  one can now build SBCL and get a multithreaded environment. Note that
  I said build: for some reason, the pre-built packages don't have
  threading support activated. The only option left to us is then to
  install the port:

  ,----
  | # cd /usr/ports/lang/sbcl
  | # make sure you select Threading in the options
  | # make config 
  | # make install
  `----

  As of writing, the above gets you SBCL version 1.3.13. Note that as a
  test, I also downloaded the latest vanilla source code from the
  official site (version 1.3.14), built and installed the thing in a
  hierarchy in my home directory. This builds fine, including
  multithreading, but I noted a difference where the Quicklisp
  dependencies are stored: my sbcl 1.3.13 from ports put them in
  `~/quicklisp', whereas the vanilla 1.3.14 put them in
  `~/.quicklisp'. I haven't checked whether this is a change in the
  defaults, or just some configuration option that differs between the
  ports and the official release. Keep this in mind when you set up
  emacs to load the slime-helper, for example. For the remainder of this
  guide, I consider that sbcl was installed from the ports and that
  quicklisp dependencies are written to `~/quicklisp'.


[has recently announced that only SBCL will be supported in the future]
http://nongnu.13855.n7.nabble.com/StumpWM-1-0-0-Released-td219024.html

[there used to be some problems with threading support for SBCL on
FreeBSD] https://bugs.freebsd.org/bugzilla/show_bug.cgi?id%3D184425


1.1.2 Install Quicklisp
-----------------------

  [Quicklisp] can be installed exactly as described by Kaashif
  Hymabaccus:

  ,----
  | $ curl -O https://beta.quicklisp.org/quicklisp.lisp
  | $ sbcl --load /path/to/quicklisp.lisp
  `----

  And then in the REPL:

  ,----
  | * (quicklisp-quickstart:install)
  | * (ql:add-to-init-file)
  `----


[Quicklisp] https://www.quicklisp.org/beta/


1.1.3 Install StumpWM
---------------------

  There are two options here: either clone the official GitHub
  repository and follow the instructions given in the manual, or just
  trust Quicklisp to do the right thing and install everything. I find
  the latter easier to manage in the long run: Quicklisp installs all
  the dependencies, and is able to update the project automatically and
  cleanly. No surprises with dependencies or anything.

  ,----
  | * (ql:quickload "stumpwm")
  `----

  This will install StumpWM along with its dependencies (that is, `clx',
  `cl-ppcre' and `alexandria') and will proceed recursively down the
  dependency chain to install everyting needed to run StumpWM.


1.1.4 Get emacs hook up to StumpWM sessions
-------------------------------------------

  A major aspect of Lisp development is the ability to connect to a
  session and interact with it, modifying code straight on the live
  system. In the case of StumpWM, this means the ability to configure
  the whole system, adding or removing features and behaviours, changing
  the keybindings and controlling the whole Window manager from within
  emacs. All without restarting StumpWM, just like you never have to
  restart emacs when you modify it.

  The setup requires on the server side sbcl to create a swank server
  and on the client side emacs to communicate with the Lisp session
  through [SLIME]. Installing everything is made very simple by
  Quicklisp.

  In an sbcl REPL:

  ,----
  | * (ql:quickload "swank")
  | * (ql:quickload "quicklisp-slime-helper")
  `----

  You can then instruct StumpWM to create the server. Following the good
  advice in the blog post, have it listen to port `4004' instead of the
  standard `4005', so you won't connect to this session by accident. In
  your `~/.stumpwmrc', write the following:

  ,----
  | (in-package :stumpwm)
  | 
  | (require :swank)
  | (swank-loader:init) 
  | (swank:create-server :port 4004
  |                      :style swank:*communication-style*
  |                      :dont-close t)
  | 
  `----

  Now, in you emacs config, write the following:

  ,----
  | (load (expand-file-name "~/quicklisp/slime-helper.el"))
  `----


[SLIME] https://common-lisp.net/project/slime/


1.1.5 Configure your X session
------------------------------

  Starting X in our case means starting sbcl and asking it to load
  stumpwm. Create the file `startstumpwm' with the following content:

  ,----
  | (require :stumpwm)
  | (stumpwm:stumpwm)
  `----

  I must confess here that since I've been using Unix, I've never used
  anything like a Desktop Environment, which means that I don't know how
  to tell KDE or Gnome to use StumpWM for windows management. If, like
  me, you still rely on `startx' and friends, write the following in
  your `~/.xinitrc':

  ,----
  | exec sbcl --load ~/bin/startstumpwm --eval '(quit)'
  `----

  Note that we explictly ask sbcl to quit by passing
  ,----
  | --eval '(quit)'
  `----
  Otherwise, after you quit StumpWM, sbcl would leave the REPL open, and
  your X session would keep running forever. Again, it's very possible
  this last bit isn't necessary if you start your X session through
  other means.