code.delx.au - gnu-emacs-elpa/blob - packages/bug-hunter/README.org

   1 #+OPTIONS: toc:nil num:nil
   2 #+TITLE: [[file:hunter.png]] The Bug Hunter [[https://travis-ci.org/Malabarba/elisp-bug-hunter][file:https://travis-ci.org/Malabarba/elisp-bug-hunter.svg?branch=master]]
   3
   4 /Automatically debug and bisect your init (.emacs) file!/
   5
   6 The Bug Hunter is an Emacs library that finds the source of an error
   7 or unexpected behavior inside an elisp configuration file (typically
   8 ~init.el~ or ~.emacs~).
   9
  10 [[file:hunter-screencast.gif]]
  11
  12 * Usage Examples
  13
  14 ** Automated error hunting
  15 If your Emacs init file signals an error during startup, but you don’t
  16 know why, simply issue
  17 #+BEGIN_SRC text
  18 M-x bug-hunter-init-file RET e
  19 #+END_SRC
  20 and The Bug Hunter will find it for you.  Note that your ~init.el~
  21 (or ~.emacs~) must be idempotent for this to work.
  22
  23 ** Interactive hunt
  24
  25 If Emacs starts up without errors but something is not working as it
  26 should, invoke the same command, but choose the interactive option:
  27 #+BEGIN_SRC text
  28 M-x bug-hunter-init-file RET i
  29 #+END_SRC
  30 The Bug Hunter will start a separate Emacs instance several times, and
  31 then it will ask you each time whether that instance presented the
  32 problem you have. After doing this about 5--12 times, you’ll be given
  33 the results.
  34
  35 ** Assertion hunt
  36
  37 The Bug Hunter can also find your issue based on an assertion.
  38 Essentially, if you can write a code snippet that returns non-nil when
  39 it detects the issue, just provide this snippet as the assertion and
  40 the Bug Hunter will do the rest.
  41
  42 For example, let’s say there’s something in your init file that’s
  43 loading the ~cl~ library, and you don’t want that. You /know/ you’re
  44 not loading it yourself, but how can you figure out which external
  45 package is responsible for this outrage?
  46
  47 #+BEGIN_SRC text
  48 M-x bug-hunter-init-file RET a (featurep 'cl) RET
  49 #+END_SRC
  50
  51 *That’s it!* You’ll be given a nice buffer reporting the results:
  52
  53 [[file:cl-example.png]]
  54 - Are you getting obscure errors when trying to open /“.tex”/ files?
  55   - Don’t despair! Just use ~(find-file "dummy.tex")~ as the assertion.
  56 - Did ~ox-html~ stop working due to some arcane misconfiguration?
  57   - Just write an assertion that does an export and checks the result.
  58 - Does some random command suddenly bind itself to ~C-j~ and you can’t figure out why?
  59   - ~(eq (key-binding "\n") 'unwanted-command)~ is the assertion for you!
  60
  61 Finally, you can also use ~bug-hunter-file~ to hunt in other files.
  62
  63 * Installation
  64 The Bug Hunter is available from [[https://elpa.gnu.org/packages/bug-hunter.html][GNU Elpa]] to all Emacs versions since
  65 ~24.1~. To install, just issue
  66
  67 #+BEGIN_SRC text
  68 M-x package-install RET bug-hunter
  69 #+END_SRC
  70
  71 * init.org and other literate-style configs
  72
  73 Some people (me included) like to organize their init files by
  74 writting it in ~org-mode~ instead of Emacs-Lisp. This usually involves
  75 adding something like this to ~init.el~,
  76 #+BEGIN_SRC emacs-lisp
  77 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  78 ;;; Maybe some code up here ;;;
  79 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  80 (require 'org)
  81 (org-babel-tangle-file "~/.emacs.d/org-init.org"
  82                        "~/.emacs.d/org-init.el")
  83 (load "~/.emacs.d/org-init.el")
  84 #+END_SRC
  85
  86 At first, this makes the Bug-Hunter essentially useless, for it will
  87 do the hunting in ~init.el~ instead of the much more extensive
  88 ~org-init.el~. The name of the second file (~org-init.el~) will vary,
  89 but the point is the same. But fear not! There’s a simple solution:
  90
  91 1. If you have any code above the call to ~org-babel-tangle-file~, copy that to the top of ~org-init.el~ (or whatever is the name of your tangled file). This includes that ~(require 'org)~ over there.
  92 2. Invoke ~M-x~ ~bug-hunter-file~ (instead of ~bug-hunter-init-file~). It will ask you which file to debug, and you need to point it to your tangled output file ~org-init.el~.