Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | <!DOCTYPE html>\r |
2 | <html lang="en">\r | |
3 | <head>\r | |
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r | |
5 | <meta name="generator" content="AsciiDoc 8.6.9">\r | |
6 | <title>EmacsBgBuildMode</title>\r | |
7 | <link rel="stylesheet" href="./asciidoc.css" type="text/css">\r | |
8 | <link rel="stylesheet" href="./pygments.css" type="text/css">\r | |
9 | \r | |
10 | \r | |
11 | <script type="text/javascript" src="./asciidoc.js"></script>\r | |
12 | <script type="text/javascript">\r | |
13 | /*<![CDATA[*/\r | |
14 | asciidoc.install();\r | |
15 | /*]]>*/\r | |
16 | </script>\r | |
17 | <link rel="stylesheet" href="./mlton.css" type="text/css">\r | |
18 | </head>\r | |
19 | <body class="article">\r | |
20 | <div id="banner">\r | |
21 | <div id="banner-home">\r | |
22 | <a href="./Home">MLton 20180207</a>\r | |
23 | </div>\r | |
24 | </div>\r | |
25 | <div id="header">\r | |
26 | <h1>EmacsBgBuildMode</h1>\r | |
27 | </div>\r | |
28 | <div id="content">\r | |
29 | <div id="preamble">\r | |
30 | <div class="sectionbody">\r | |
31 | <div class="paragraph"><p>Do you really want to think about starting a build of you project?\r | |
32 | What if you had a personal slave that would restart a build of your\r | |
33 | project whenever you save any file belonging to that project? The\r | |
34 | bg-build mode does just that. Just save the file, a compile is\r | |
35 | started (silently!), you can continue working without even thinking\r | |
36 | about starting a build, and if there are errors, you are notified\r | |
37 | (with a message), and can then jump to errors.</p></div>\r | |
38 | <div class="paragraph"><p>This mode is not specific to MLton per se, but is particularly useful\r | |
39 | for working with MLton due to the longer compile times. By the time\r | |
40 | you start wondering about possible errors, the build is already on the\r | |
41 | way.</p></div>\r | |
42 | </div>\r | |
43 | </div>\r | |
44 | <div class="sect1">\r | |
45 | <h2 id="_functionality_and_features">Functionality and Features</h2>\r | |
46 | <div class="sectionbody">\r | |
47 | <div class="ulist"><ul>\r | |
48 | <li>\r | |
49 | <p>\r | |
50 | Each time a file is saved, and after a user configurable delay\r | |
51 | period has been exhausted, a build is started silently in the\r | |
52 | background.\r | |
53 | </p>\r | |
54 | </li>\r | |
55 | <li>\r | |
56 | <p>\r | |
57 | When the build is finished, a status indicator (message) is\r | |
58 | displayed non-intrusively.\r | |
59 | </p>\r | |
60 | </li>\r | |
61 | <li>\r | |
62 | <p>\r | |
63 | At any time, you can switch to a build process buffer where all the\r | |
64 | messages from the build are shown.\r | |
65 | </p>\r | |
66 | </li>\r | |
67 | <li>\r | |
68 | <p>\r | |
69 | Optionally highlights (error/warning) message locations in (source\r | |
70 | code) buffers after a finished build.\r | |
71 | </p>\r | |
72 | </li>\r | |
73 | <li>\r | |
74 | <p>\r | |
75 | After a build has finished, you can jump to locations of warnings\r | |
76 | and errors from the build process buffer or by using the <span class="monospaced">first-error</span>\r | |
77 | and <span class="monospaced">next-error</span> commands.\r | |
78 | </p>\r | |
79 | </li>\r | |
80 | <li>\r | |
81 | <p>\r | |
82 | When a build fails, bg-build mode can optionally execute a user\r | |
83 | specified command. By default, bg-build mode executes <span class="monospaced">first-error</span>.\r | |
84 | </p>\r | |
85 | </li>\r | |
86 | <li>\r | |
87 | <p>\r | |
88 | When starting a build of a particular project, a possible previous\r | |
89 | live build of the same project is interrupted first.\r | |
90 | </p>\r | |
91 | </li>\r | |
92 | <li>\r | |
93 | <p>\r | |
94 | A project configuration file specifies the commands required to\r | |
95 | build a project.\r | |
96 | </p>\r | |
97 | </li>\r | |
98 | <li>\r | |
99 | <p>\r | |
100 | Multiple projects can be loaded into bg-build mode and bg-build mode\r | |
101 | can build a given maximum number of projects concurrently.\r | |
102 | </p>\r | |
103 | </li>\r | |
104 | <li>\r | |
105 | <p>\r | |
106 | Supports both <a href="http://www.gnu.org/software/emacs/">Gnu Emacs</a> and\r | |
107 | <a href="http://www.xemacs.org">XEmacs</a>.\r | |
108 | </p>\r | |
109 | </li>\r | |
110 | </ul></div>\r | |
111 | </div>\r | |
112 | </div>\r | |
113 | <div class="sect1">\r | |
114 | <h2 id="_download">Download</h2>\r | |
115 | <div class="sectionbody">\r | |
116 | <div class="paragraph"><p>There is no package for the mode at the moment. To install the mode you\r | |
117 | need to fetch the Emacs Lisp, <span class="monospaced">*.el</span>, files from the MLton repository:\r | |
118 | <a href="https://github.com/MLton/mlton/tree/master/ide/emacs"><span class="monospaced">emacs</span></a>.</p></div>\r | |
119 | </div>\r | |
120 | </div>\r | |
121 | <div class="sect1">\r | |
122 | <h2 id="_setup">Setup</h2>\r | |
123 | <div class="sectionbody">\r | |
124 | <div class="paragraph"><p>The easiest way to load the mode is to first tell Emacs where to find the\r | |
125 | files. For example, add</p></div>\r | |
126 | <div class="listingblock">\r | |
127 | <div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nv">add-to-list</span> <span class="ss">'load-path</span> <span class="p">(</span><span class="nv">file-truename</span> <span class="s">"path-to-the-el-files"</span><span class="p">))</span>\r | |
128 | </pre></div></div></div>\r | |
129 | <div class="paragraph"><p>to your <span class="monospaced">~/.emacs</span> or <span class="monospaced">~/.xemacs/init.el</span>. You’ll probably also want\r | |
130 | to start the mode automatically by adding</p></div>\r | |
131 | <div class="listingblock">\r | |
132 | <div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nb">require</span> <span class="ss">'bg-build-mode</span><span class="p">)</span>\r | |
133 | <span class="p">(</span><span class="nv">bg-build-mode</span><span class="p">)</span>\r | |
134 | </pre></div></div></div>\r | |
135 | <div class="paragraph"><p>to your Emacs init file. Once the mode is activated, you should see\r | |
136 | the <span class="monospaced">BGB</span> indicator on the mode line.</p></div>\r | |
137 | <div class="sect2">\r | |
138 | <h3 id="_mlton_and_compilation_mode">MLton and Compilation-Mode</h3>\r | |
139 | <div class="paragraph"><p>At the time of writing, neither Gnu Emacs nor XEmacs contain an error\r | |
140 | regexp that would match MLton’s messages.</p></div>\r | |
141 | <div class="paragraph"><p>If you use Gnu Emacs, insert the following code into your <span class="monospaced">.emacs</span> file:</p></div>\r | |
142 | <div class="listingblock">\r | |
143 | <div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nb">require</span> <span class="ss">'compile</span><span class="p">)</span>\r | |
144 | <span class="p">(</span><span class="nv">add-to-list</span>\r | |
145 | <span class="ss">'compilation-error-regexp-alist</span>\r | |
146 | <span class="o">'</span><span class="p">(</span><span class="s">"^\\(Warning\\|Error\\): \\(.+\\) \\([0-9]+\\)\\.\\([0-9]+\\)\\.$"</span>\r | |
147 | <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">))</span>\r | |
148 | </pre></div></div></div>\r | |
149 | <div class="paragraph"><p>If you use XEmacs, insert the following code into your <span class="monospaced">init.el</span> file:</p></div>\r | |
150 | <div class="listingblock">\r | |
151 | <div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nb">require</span> <span class="ss">'compile</span><span class="p">)</span>\r | |
152 | <span class="p">(</span><span class="nv">add-to-list</span>\r | |
153 | <span class="ss">'compilation-error-regexp-alist-alist</span>\r | |
154 | <span class="o">'</span><span class="p">(</span><span class="nv">mlton</span>\r | |
155 | <span class="p">(</span><span class="s">"^\\(Warning\\|Error\\): \\(.+\\) \\([0-9]+\\)\\.\\([0-9]+\\)\\.$"</span>\r | |
156 | <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span><span class="p">)))</span>\r | |
157 | <span class="p">(</span><span class="nv">compilation-build-compilation-error-regexp-alist</span><span class="p">)</span>\r | |
158 | </pre></div></div></div>\r | |
159 | </div>\r | |
160 | </div>\r | |
161 | </div>\r | |
162 | <div class="sect1">\r | |
163 | <h2 id="_usage">Usage</h2>\r | |
164 | <div class="sectionbody">\r | |
165 | <div class="paragraph"><p>Typically projects are built (or compiled) using a tool like <a href="http://www.gnu.org/software/make/"><span class="monospaced">make</span></a>,\r | |
166 | but the details vary. The bg-build mode needs a project configuration file to\r | |
167 | know how to build your project. A project configuration file basically contains\r | |
168 | an Emacs Lisp expression calling a function named <span class="monospaced">bg-build</span> that returns a\r | |
169 | project object. A simple example of a project configuration file would be the\r | |
170 | (<a href="https://github.com/MLton/mltonlib/blob/master/com/ssh/async/unstable/example/smlbot/Build.bgb"><span class="monospaced">Build.bgb</span></a>)\r | |
171 | file used with smlbot:</p></div>\r | |
172 | <div class="listingblock">\r | |
173 | <div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nv">bg-build</span>\r | |
174 | <span class="ss">:name</span> <span class="s">"SML-Bot"</span>\r | |
175 | <span class="ss">:shell</span> <span class="s">"nice -n5 make all"</span><span class="p">)</span>\r | |
176 | </pre></div></div></div>\r | |
177 | <div class="paragraph"><p>The <span class="monospaced">bg-build</span> function takes a number of keyword arguments:</p></div>\r | |
178 | <div class="ulist"><ul>\r | |
179 | <li>\r | |
180 | <p>\r | |
181 | <span class="monospaced">:name</span> specifies the name of the project. This can be any\r | |
182 | expression that evaluates to a string or to a nullary function that\r | |
183 | returns a string.\r | |
184 | </p>\r | |
185 | </li>\r | |
186 | <li>\r | |
187 | <p>\r | |
188 | <span class="monospaced">:shell</span> specifies a shell command to execute. This can be any\r | |
189 | expression that evaluates to a string, a list of strings, or to a\r | |
190 | nullary function returning a list of strings.\r | |
191 | </p>\r | |
192 | </li>\r | |
193 | <li>\r | |
194 | <p>\r | |
195 | <span class="monospaced">:build?</span> specifies a predicate to determine whether the project\r | |
196 | should be built after some files have been modified. The predicate is\r | |
197 | given a list of filenames and should return a non-nil value when the\r | |
198 | project should be built and nil otherwise.\r | |
199 | </p>\r | |
200 | </li>\r | |
201 | </ul></div>\r | |
202 | <div class="paragraph"><p>All of the keyword arguments, except <span class="monospaced">:shell</span>, are optional and can be left out.</p></div>\r | |
203 | <div class="paragraph"><p>Note the use of the <span class="monospaced">nice</span> command above. It means that background\r | |
204 | build process is given a lower priority by the system process\r | |
205 | scheduler. Assuming your machine has enough memory, using nice\r | |
206 | ensures that your computer remains responsive. (You probably won’t\r | |
207 | even notice when a build is started.)</p></div>\r | |
208 | <div class="paragraph"><p>Once you have written a project file for bg-build mode. Use the\r | |
209 | <span class="monospaced">bg-build-add-project</span> command to load the project file for bg-build\r | |
210 | mode. The bg-build mode can also optionally load recent project files\r | |
211 | automatically at startup.</p></div>\r | |
212 | <div class="paragraph"><p>After the project file has been loaded and bg-build mode activated,\r | |
213 | each time you save a file in Emacs, the bg-build mode tries to build\r | |
214 | your project.</p></div>\r | |
215 | <div class="paragraph"><p>The <span class="monospaced">bg-build-status</span> command creates a buffer that displays some\r | |
216 | status information on builds and allows you to manage projects (start\r | |
217 | builds explicitly, remove a project from bg-build, …) as well as\r | |
218 | visit buffers created by bg-build. Notice the count of started\r | |
219 | builds. At the end of the day it can be in the hundreds or thousands.\r | |
220 | Imagine the number of times you’ve been relieved of starting a build\r | |
221 | explicitly!</p></div>\r | |
222 | </div>\r | |
223 | </div>\r | |
224 | </div>\r | |
225 | <div id="footnotes"><hr></div>\r | |
226 | <div id="footer">\r | |
227 | <div id="footer-text">\r | |
228 | </div>\r | |
229 | <div id="footer-badges">\r | |
230 | </div>\r | |
231 | </div>\r | |
232 | </body>\r | |
233 | </html>\r |