[hcoop/debian/mlton.git] / doc / guide / localhost / EmacsDefUseMode

<!DOCTYPE html>\r
<html lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
<meta name="generator" content="AsciiDoc 8.6.9">\r
<title>EmacsDefUseMode</title>\r
<link rel="stylesheet" href="./asciidoc.css" type="text/css">\r
<link rel="stylesheet" href="./pygments.css" type="text/css">\r
\r
\r
<script type="text/javascript" src="./asciidoc.js"></script>\r
<script type="text/javascript">\r
/*<![CDATA[*/\r
asciidoc.install();\r
/*]]>*/\r
</script>\r
<link rel="stylesheet" href="./mlton.css" type="text/css">\r
</head>\r
<body class="article">\r
<div id="banner">\r
<div id="banner-home">\r
<a href="./Home">MLton 20180207</a>\r
</div>\r
</div>\r
<div id="header">\r
<h1>EmacsDefUseMode</h1>\r
</div>\r
<div id="content">\r
<div id="preamble">\r
<div class="sectionbody">\r
<div class="paragraph"><p>MLton provides an <a href="CompileTimeOptions">option</a>,\r
<span class="monospaced">-show-def-use <em>file</em></span>, to output precise (giving exact source\r
locations) and accurate (including all uses and no false data)\r
whole-program def-use information to a file.  Unlike typical tags\r
facilities, the information includes local variables and distinguishes\r
between different definitions even when they have the same name.  The\r
def-use Emacs mode uses the information to provide navigation support,\r
which can be particularly useful while reading SML programs compiled\r
with MLton (such as the MLton compiler itself).</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_screen_capture">Screen Capture</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Note the highlighting and the type displayed in the minibuffer.</p></div>\r
<div class="imageblock" style="text-align:center;">\r
<div class="content">\r
<img src="EmacsDefUseMode.attachments/def-use-capture.png" alt="EmacsDefUseMode.attachments/def-use-capture.png">\r
</div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_features">Features</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
Highlights definitions and uses.  Different colors for definitions, unused definitions, and uses.\r
</p>\r
</li>\r
<li>\r
<p>\r
Shows types (with highlighting) of variable definitions in the minibuffer.\r
</p>\r
</li>\r
<li>\r
<p>\r
Navigation: <span class="monospaced">jump-to-def</span>, <span class="monospaced">jump-to-next</span>, and <span class="monospaced">jump-to-prev</span>.  These work precisely (no searching involved).\r
</p>\r
</li>\r
<li>\r
<p>\r
Can list, visit and mark all references to a definition (within a program).\r
</p>\r
</li>\r
<li>\r
<p>\r
Automatically reloads updated def-use files.\r
</p>\r
</li>\r
<li>\r
<p>\r
Automatically loads previously used def-use files at startup.\r
</p>\r
</li>\r
<li>\r
<p>\r
Supports both <a href="http://www.gnu.org/software/emacs/">Gnu Emacs</a> and <a href="http://www.xemacs.org">XEmacs</a>.\r
</p>\r
</li>\r
</ul></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_download">Download</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>There is no separate package for the def-use mode although the mode\r
has been relatively stable for some time already.  To install the mode\r
you need to get the Emacs Lisp, <span class="monospaced">*.el</span>, files from MLton&#8217;s repository:\r
<a href="https://github.com/MLton/mlton/tree/master/ide/emacs"><span class="monospaced">emacs</span></a>.  The easiest way to get the files\r
is to use <a href="Git">Git</a> to access MLton&#8217;s <a href="Sources">sources</a>.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_setup">Setup</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>The easiest way to load def-use mode is to first tell Emacs where to\r
find the files.  For example, add</p></div>\r
<div class="listingblock">\r
<div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nv">add-to-list</span> <span class="ss">&#39;load-path</span> <span class="p">(</span><span class="nv">file-truename</span> <span class="s">&quot;path-to-the-el-files&quot;</span><span class="p">))</span>\r
</pre></div></div></div>\r
<div class="paragraph"><p>to your <span class="monospaced">~/.emacs</span> or <span class="monospaced">~/.xemacs/init.el</span>.  You&#8217;ll probably\r
also want to start <span class="monospaced">def-use-mode</span> automatically by adding</p></div>\r
<div class="listingblock">\r
<div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nb">require</span> <span class="ss">&#39;esml-du-mlton</span><span class="p">)</span>\r
<span class="p">(</span><span class="nv">def-use-mode</span><span class="p">)</span>\r
</pre></div></div></div>\r
<div class="paragraph"><p>to your Emacs init file.  Once the def-use mode is activated, you\r
should see the <span class="monospaced">DU</span> indicator on the mode line.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_usage">Usage</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>To use def-use mode one typically first sets up the program&#8217;s makefile\r
or build script so that the def-use information is saved each time the\r
program is compiled.  In addition to the <span class="monospaced">-show-def-use <em>file</em></span>\r
option, the <span class="monospaced">-prefer-abs-paths true</span> expert option is required.\r
Note that the time it takes to save the information is small (compared\r
to type-checking), so it is recommended to simply add the options to\r
the MLton invocation that compiles the program.  However, it is only\r
necessary to type check the program (or library), so one can specify\r
the <span class="monospaced">-stop tc</span> option.  For example, suppose you have a program\r
defined by an MLB file named <span class="monospaced">my-prg.mlb</span>, you can save the def-use\r
information to the file <span class="monospaced">my-prg.du</span> by invoking MLton as:</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>mlton -prefer-abs-paths true -show-def-use my-prg.du -stop tc my-prg.mlb</pre>\r
</div></div>\r
<div class="paragraph"><p>Finally, one needs to tell the mode where to find the def-use\r
information.  This is done with the <span class="monospaced">esml-du-mlton</span> command.  For\r
example, to load the <span class="monospaced">my-prg.du</span> file, one would type:</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>M-x esml-du-mlton my-prg.du</pre>\r
</div></div>\r
<div class="paragraph"><p>After doing all of the above, find an SML file covered by the\r
previously saved and loaded def-use information, and place the cursor\r
at some variable (definition or use, it doesn&#8217;t matter).  You should\r
see the variable being highlighted.  (Note that specifications in\r
signatures do not define variables.)</p></div>\r
<div class="paragraph"><p>You might also want to setup and use the\r
<a href="EmacsBgBuildMode">Bg-Build mode</a> to start builds automatically.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_types">Types</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p><span class="monospaced">-show-def-use</span> output was extended to include types of variable\r
definitions in revision <a href="https://github.com/MLton/mlton/commit/%3A%2FSVN%20r6333"><span class="monospaced">r6333</span></a>.  To get good type names, the\r
types must be in scope at the end of the program.  If you are using the\r
<a href="MLBasis">ML Basis</a> system, this means that the root MLB-file for your\r
application should not wrap the libraries used in the application inside\r
<span class="monospaced">local ... in ... end</span>, because that would remove them from the scope before\r
the end of the program.</p></div>\r
</div>\r
</div>\r
</div>\r
<div id="footnotes"><hr></div>\r
<div id="footer">\r
<div id="footer-text">\r
</div>\r
<div id="footer-badges">\r
</div>\r
</div>\r
</body>\r
</html>\r
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>EmacsDefUseMode</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>EmacsDefUseMode</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>MLton provides an <a href="CompileTimeOptions">option</a>,\r
	32	<span class="monospaced">-show-def-use <em>file</em></span>, to output precise (giving exact source\r
	33	locations) and accurate (including all uses and no false data)\r
	34	whole-program def-use information to a file. Unlike typical tags\r
	35	facilities, the information includes local variables and distinguishes\r
	36	between different definitions even when they have the same name. The\r
	37	def-use Emacs mode uses the information to provide navigation support,\r
	38	which can be particularly useful while reading SML programs compiled\r
	39	with MLton (such as the MLton compiler itself).</p></div>\r
	40	</div>\r
	41	</div>\r
	42	<div class="sect1">\r
	43	<h2 id="_screen_capture">Screen Capture</h2>\r
	44	<div class="sectionbody">\r
	45	<div class="paragraph"><p>Note the highlighting and the type displayed in the minibuffer.</p></div>\r
	46	<div class="imageblock" style="text-align:center;">\r
	47	<div class="content">\r
	48	<img src="EmacsDefUseMode.attachments/def-use-capture.png" alt="EmacsDefUseMode.attachments/def-use-capture.png">\r
	49	</div>\r
	50	</div>\r
	51	</div>\r
	52	</div>\r
	53	<div class="sect1">\r
	54	<h2 id="_features">Features</h2>\r
	55	<div class="sectionbody">\r
	56	<div class="ulist"><ul>\r
	57	<li>\r
	58	<p>\r
	59	Highlights definitions and uses. Different colors for definitions, unused definitions, and uses.\r
	60	</p>\r
	61	</li>\r
	62	<li>\r
	63	<p>\r
	64	Shows types (with highlighting) of variable definitions in the minibuffer.\r
65	</p>\r
66	</li>\r
67	<li>\r
68	<p>\r
69	Navigation: <span class="monospaced">jump-to-def</span>, <span class="monospaced">jump-to-next</span>, and <span class="monospaced">jump-to-prev</span>. These work precisely (no searching involved).\r
70	</p>\r
71	</li>\r
72	<li>\r
73	<p>\r
74	Can list, visit and mark all references to a definition (within a program).\r
75	</p>\r
76	</li>\r
77	<li>\r
78	<p>\r
79	Automatically reloads updated def-use files.\r
80	</p>\r
81	</li>\r
82	<li>\r
83	<p>\r
84	Automatically loads previously used def-use files at startup.\r
85	</p>\r
86	</li>\r
87	<li>\r
88	<p>\r
89	Supports both <a href="http://www.gnu.org/software/emacs/">Gnu Emacs</a> and <a href="http://www.xemacs.org">XEmacs</a>.\r
90	</p>\r
91	</li>\r
92	</ul></div>\r
93	</div>\r
94	</div>\r
95	<div class="sect1">\r
96	<h2 id="_download">Download</h2>\r
97	<div class="sectionbody">\r
98	<div class="paragraph"><p>There is no separate package for the def-use mode although the mode\r
99	has been relatively stable for some time already. To install the mode\r
100	you need to get the Emacs Lisp, <span class="monospaced">*.el</span>, files from MLton’s repository:\r
101	<a href="https://github.com/MLton/mlton/tree/master/ide/emacs"><span class="monospaced">emacs</span></a>. The easiest way to get the files\r
102	is to use <a href="Git">Git</a> to access MLton’s <a href="Sources">sources</a>.</p></div>\r
103	</div>\r
104	</div>\r
105	<div class="sect1">\r
106	<h2 id="_setup">Setup</h2>\r
107	<div class="sectionbody">\r
108	<div class="paragraph"><p>The easiest way to load def-use mode is to first tell Emacs where to\r
109	find the files. For example, add</p></div>\r
110	<div class="listingblock">\r
111	<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
112	</pre></div></div></div>\r
113	<div class="paragraph"><p>to your <span class="monospaced">~/.emacs</span> or <span class="monospaced">~/.xemacs/init.el</span>. You’ll probably\r
114	also want to start <span class="monospaced">def-use-mode</span> automatically by adding</p></div>\r
115	<div class="listingblock">\r
116	<div class="content"><div class="highlight"><pre><span class="p">(</span><span class="nb">require</span> <span class="ss">'esml-du-mlton</span><span class="p">)</span>\r
117	<span class="p">(</span><span class="nv">def-use-mode</span><span class="p">)</span>\r
118	</pre></div></div></div>\r
119	<div class="paragraph"><p>to your Emacs init file. Once the def-use mode is activated, you\r
120	should see the <span class="monospaced">DU</span> indicator on the mode line.</p></div>\r
121	</div>\r
122	</div>\r
123	<div class="sect1">\r
124	<h2 id="_usage">Usage</h2>\r
125	<div class="sectionbody">\r
126	<div class="paragraph"><p>To use def-use mode one typically first sets up the program’s makefile\r
127	or build script so that the def-use information is saved each time the\r
128	program is compiled. In addition to the <span class="monospaced">-show-def-use <em>file</em></span>\r
129	option, the <span class="monospaced">-prefer-abs-paths true</span> expert option is required.\r
130	Note that the time it takes to save the information is small (compared\r
131	to type-checking), so it is recommended to simply add the options to\r
132	the MLton invocation that compiles the program. However, it is only\r
133	necessary to type check the program (or library), so one can specify\r
134	the <span class="monospaced">-stop tc</span> option. For example, suppose you have a program\r
135	defined by an MLB file named <span class="monospaced">my-prg.mlb</span>, you can save the def-use\r
136	information to the file <span class="monospaced">my-prg.du</span> by invoking MLton as:</p></div>\r
137	<div class="listingblock">\r
138	<div class="content monospaced">\r
139	<pre>mlton -prefer-abs-paths true -show-def-use my-prg.du -stop tc my-prg.mlb</pre>\r
140	</div></div>\r
141	<div class="paragraph"><p>Finally, one needs to tell the mode where to find the def-use\r
142	information. This is done with the <span class="monospaced">esml-du-mlton</span> command. For\r
143	example, to load the <span class="monospaced">my-prg.du</span> file, one would type:</p></div>\r
144	<div class="listingblock">\r
145	<div class="content monospaced">\r
146	<pre>M-x esml-du-mlton my-prg.du</pre>\r
147	</div></div>\r
148	<div class="paragraph"><p>After doing all of the above, find an SML file covered by the\r
149	previously saved and loaded def-use information, and place the cursor\r
150	at some variable (definition or use, it doesn’t matter). You should\r
151	see the variable being highlighted. (Note that specifications in\r
152	signatures do not define variables.)</p></div>\r
153	<div class="paragraph"><p>You might also want to setup and use the\r
154	<a href="EmacsBgBuildMode">Bg-Build mode</a> to start builds automatically.</p></div>\r
155	</div>\r
156	</div>\r
157	<div class="sect1">\r
158	<h2 id="_types">Types</h2>\r
159	<div class="sectionbody">\r
160	<div class="paragraph"><p><span class="monospaced">-show-def-use</span> output was extended to include types of variable\r
161	definitions in revision <a href="https://github.com/MLton/mlton/commit/%3A%2FSVN%20r6333"><span class="monospaced">r6333</span></a>. To get good type names, the\r
162	types must be in scope at the end of the program. If you are using the\r
163	<a href="MLBasis">ML Basis</a> system, this means that the root MLB-file for your\r
164	application should not wrap the libraries used in the application inside\r
165	<span class="monospaced">local ... in ... end</span>, because that would remove them from the scope before\r
166	the end of the program.</p></div>\r
167	</div>\r
168	</div>\r
169	</div>\r
170	<div id="footnotes"><hr></div>\r
171	<div id="footer">\r
172	<div id="footer-text">\r
173	</div>\r
174	<div id="footer-badges">\r
175	</div>\r
176	</div>\r
177	</body>\r
178	</html>\r