HCoop / hcoop / debian / mlton.git / blame
| Commit | Line | Data |
|---|---|---|
| 7f918cf1 CE |
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. |