doc/guide/src/EmacsBgBuildMode.adoc

   1 EmacsBgBuildMode
   2 ================
   3
   4 Do you really want to think about starting a build of you project?
   5 What if you had a personal slave that would restart a build of your
   6 project whenever you save any file belonging to that project?  The
   7 bg-build mode does just that.  Just save the file, a compile is
   8 started (silently!), you can continue working without even thinking
   9 about starting a build, and if there are errors, you are notified
  10 (with a message), and can then jump to errors.
  11
  12 This mode is not specific to MLton per se, but is particularly useful
  13 for working with MLton due to the longer compile times.  By the time
  14 you start wondering about possible errors, the build is already on the
  15 way.
  16
  17 == Functionality and Features ==
  18
  19 * Each time a file is saved, and after a user configurable delay
  20 period has been exhausted, a build is started silently in the
  21 background.
  22 * When the build is finished, a status indicator (message) is
  23 displayed non-intrusively.
  24 * At any time, you can switch to a build process buffer where all the
  25 messages from the build are shown.
  26 * Optionally highlights (error/warning) message locations in (source
  27 code) buffers after a finished build.
  28 * After a build has finished, you can jump to locations of warnings
  29 and errors from the build process buffer or by using the `first-error`
  30 and `next-error` commands.
  31 * When a build fails, bg-build mode can optionally execute a user
  32 specified command.  By default, bg-build mode executes `first-error`.
  33 * When starting a build of a particular project, a possible previous
  34 live build of the same project is interrupted first.
  35 * A project configuration file specifies the commands required to
  36 build a project.
  37 * Multiple projects can be loaded into bg-build mode and bg-build mode
  38 can build a given maximum number of projects concurrently.
  39 * Supports both http://www.gnu.org/software/emacs/[Gnu Emacs] and
  40 http://www.xemacs.org[XEmacs].
  41
  42
  43 == Download ==
  44
  45 There is no package for the mode at the moment.  To install the mode you
  46 need to fetch the Emacs Lisp, `*.el`, files from the MLton repository:
  47 <!ViewGitDir(mlton,master,ide/emacs)>.
  48
  49
  50 == Setup ==
  51
  52 The easiest way to load the mode is to first tell Emacs where to find the
  53 files.  For example, add
  54
  55 [source,cl]
  56 ----
  57 (add-to-list 'load-path (file-truename "path-to-the-el-files"))
  58 ----
  59
  60 to your `~/.emacs` or `~/.xemacs/init.el`.  You'll probably also want
  61 to start the mode automatically by adding
  62
  63 [source,cl]
  64 ----
  65 (require 'bg-build-mode)
  66 (bg-build-mode)
  67 ----
  68
  69 to your Emacs init file.  Once the mode is activated, you should see
  70 the `BGB` indicator on the mode line.
  71
  72
  73 === MLton and Compilation-Mode ===
  74
  75 At the time of writing, neither Gnu Emacs nor XEmacs contain an error
  76 regexp that would match MLton's messages.
  77
  78 If you use Gnu Emacs, insert the following code into your `.emacs` file:
  79
  80 [source,cl]
  81 ----
  82 (require 'compile)
  83 (add-to-list
  84  'compilation-error-regexp-alist
  85  '("^\\(Warning\\|Error\\): \\(.+\\) \\([0-9]+\\)\\.\\([0-9]+\\)\\.$"
  86    2 3 4))
  87 ----
  88
  89 If you use XEmacs, insert the following code into your `init.el` file:
  90
  91 [source,cl]
  92 ----
  93 (require 'compile)
  94 (add-to-list
  95  'compilation-error-regexp-alist-alist
  96  '(mlton
  97    ("^\\(Warning\\|Error\\): \\(.+\\) \\([0-9]+\\)\\.\\([0-9]+\\)\\.$"
  98     2 3 4)))
  99 (compilation-build-compilation-error-regexp-alist)
 100 ----
 101
 102 == Usage ==
 103
 104 Typically projects are built (or compiled) using a tool like http://www.gnu.org/software/make/[`make`],
 105 but the details vary.  The bg-build mode needs a project configuration file to
 106 know how to build your project.  A project configuration file basically contains
 107 an Emacs Lisp expression calling a function named `bg-build` that returns a
 108 project object.  A simple example of a project configuration file would be the
 109 (<!ViewGitFile(mltonlib,master,com/ssh/async/unstable/example/smlbot/Build.bgb)>)
 110 file used with smlbot:
 111
 112 [source,cl]
 113 ----
 114 sys::[./bin/InclGitFile.py mltonlib master com/ssh/async/unstable/example/smlbot/Build.bgb 5:]
 115 ----
 116
 117 The `bg-build` function takes a number of keyword arguments:
 118
 119 * `:name` specifies the name of the project.  This can be any
 120 expression that evaluates to a string or to a nullary function that
 121 returns a string.
 122
 123 * `:shell` specifies a shell command to execute.  This can be any
 124 expression that evaluates to a string, a list of strings, or to a
 125 nullary function returning a list of strings.
 126
 127 * `:build?` specifies a predicate to determine whether the project
 128 should be built after some files have been modified.  The predicate is
 129 given a list of filenames and should return a non-nil value when the
 130 project should be built and nil otherwise.
 131
 132 All of the keyword arguments, except `:shell`, are optional and can be left out.
 133
 134 Note the use of the `nice` command above.  It means that background
 135 build process is given a lower priority by the system process
 136 scheduler.  Assuming your machine has enough memory, using nice
 137 ensures that your computer remains responsive.  (You probably won't
 138 even notice when a build is started.)
 139
 140 Once you have written a project file for bg-build mode.  Use the
 141 `bg-build-add-project` command to load the project file for bg-build
 142 mode.  The bg-build mode can also optionally load recent project files
 143 automatically at startup.
 144
 145 After the project file has been loaded and bg-build mode activated,
 146 each time you save a file in Emacs, the bg-build mode tries to build
 147 your project.
 148
 149 The `bg-build-status` command creates a buffer that displays some
 150 status information on builds and allows you to manage projects (start
 151 builds explicitly, remove a project from bg-build, ...) as well as
 152 visit buffers created by bg-build.  Notice the count of started
 153 builds.  At the end of the day it can be in the hundreds or thousands.
 154 Imagine the number of times you've been relieved of starting a build
 155 explicitly!