doc/guide/src/EmacsDefUseMode.adoc

   1 EmacsDefUseMode
   2 ===============
   3
   4 MLton provides an <:CompileTimeOptions:option>,
   5 ++-show-def-use __file__++, to output precise (giving exact source
   6 locations) and accurate (including all uses and no false data)
   7 whole-program def-use information to a file.  Unlike typical tags
   8 facilities, the information includes local variables and distinguishes
   9 between different definitions even when they have the same name.  The
  10 def-use Emacs mode uses the information to provide navigation support,
  11 which can be particularly useful while reading SML programs compiled
  12 with MLton (such as the MLton compiler itself).
  13
  14
  15 == Screen Capture ==
  16
  17 Note the highlighting and the type displayed in the minibuffer.
  18
  19 image::EmacsDefUseMode.attachments/def-use-capture.png[align="center"]
  20
  21
  22 == Features ==
  23
  24 * Highlights definitions and uses.  Different colors for definitions, unused definitions, and uses.
  25 * Shows types (with highlighting) of variable definitions in the minibuffer.
  26 * Navigation: `jump-to-def`, `jump-to-next`, and `jump-to-prev`.  These work precisely (no searching involved).
  27 * Can list, visit and mark all references to a definition (within a program).
  28 * Automatically reloads updated def-use files.
  29 * Automatically loads previously used def-use files at startup.
  30 * Supports both http://www.gnu.org/software/emacs/[Gnu Emacs] and http://www.xemacs.org[XEmacs].
  31
  32
  33 == Download ==
  34
  35 There is no separate package for the def-use mode although the mode
  36 has been relatively stable for some time already.  To install the mode
  37 you need to get the Emacs Lisp, `*.el`, files from MLton's repository:
  38 <!ViewGitDir(mlton,master,ide/emacs)>.  The easiest way to get the files
  39 is to use <:Git:> to access MLton's <:Sources:sources>.
  40
  41 /////
  42 If you only want the Emacs lisp files, you can use the following
  43 command:
  44 ----
  45 svn co svn://mlton.org/mlton/trunk/ide/emacs mlton-emacs-ide
  46 ----
  47 /////
  48
  49 == Setup ==
  50
  51 The easiest way to load def-use mode is to first tell Emacs where to
  52 find the files.  For example, add
  53
  54 [source,cl]
  55 ----
  56 (add-to-list 'load-path (file-truename "path-to-the-el-files"))
  57 ----
  58
  59 to your `~/.emacs` or `~/.xemacs/init.el`.  You'll probably
  60 also want to start `def-use-mode` automatically by adding
  61
  62 [source,cl]
  63 ----
  64 (require 'esml-du-mlton)
  65 (def-use-mode)
  66 ----
  67
  68 to your Emacs init file.  Once the def-use mode is activated, you
  69 should see the `DU` indicator on the mode line.
  70
  71 == Usage ==
  72
  73 To use def-use mode one typically first sets up the program's makefile
  74 or build script so that the def-use information is saved each time the
  75 program is compiled.  In addition to the ++-show-def-use __file__++
  76 option, the ++-prefer-abs-paths true++ expert option is required.
  77 Note that the time it takes to save the information is small (compared
  78 to type-checking), so it is recommended to simply add the options to
  79 the MLton invocation that compiles the program.  However, it is only
  80 necessary to type check the program (or library), so one can specify
  81 the ++-stop tc++ option.  For example, suppose you have a program
  82 defined by an MLB file named `my-prg.mlb`, you can save the def-use
  83 information to the file `my-prg.du` by invoking MLton as:
  84
  85 ----
  86 mlton -prefer-abs-paths true -show-def-use my-prg.du -stop tc my-prg.mlb
  87 ----
  88
  89 Finally, one needs to tell the mode where to find the def-use
  90 information.  This is done with the `esml-du-mlton` command.  For
  91 example, to load the `my-prg.du` file, one would type:
  92
  93 ----
  94 M-x esml-du-mlton my-prg.du
  95 ----
  96
  97 After doing all of the above, find an SML file covered by the
  98 previously saved and loaded def-use information, and place the cursor
  99 at some variable (definition or use, it doesn't matter).  You should
 100 see the variable being highlighted.  (Note that specifications in
 101 signatures do not define variables.)
 102
 103 You might also want to setup and use the
 104 <:EmacsBgBuildMode:Bg-Build mode> to start builds automatically.
 105
 106
 107 == Types ==
 108
 109 `-show-def-use` output was extended to include types of variable
 110 definitions in revision <!ViewSVNRev(6333)>.  To get good type names, the
 111 types must be in scope at the end of the program.  If you are using the
 112 <:MLBasis:ML Basis> system, this means that the root MLB-file for your
 113 application should not wrap the libraries used in the application inside
 114 `local ... in ... end`, because that would remove them from the scope before
 115 the end of the program.