Commit | Line | Data |
---|---|---|
7f918cf1 CE |
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! |