$Id: automli-readme.txt 1008 2008-05-08 13:49:18Z jim $ This is the README file for automli. See http://www.farrand.net/automli.shtml OVERVIEW Automatically generate .mli files from .ml files, using a specification contained in a .mla files. LICENSE Copyright (C) Jim Farrand 2003-5 Distributable under the GNU Public License. See ./LICENSE for details. AUTHOR Jim Farrand STATUS automli should be considered beta quality software. It works reasonably well, but needs more testing, so you should expect to find bugs. There are some know issues with automli, see the BUGS section below. INSTALLATION make all Copy automli and automlir to somewhere in your path. USAGE automli [-revised|-old] FILES [-ocamlc args] automlir [-revised|-old] FILES [-ocamlc args] -revised Input files in revised syntax -old Input files in old syntax (Default) -ocamlc Remaining arguments passed to ocamlc. -help Display this list of options --help Display this list of options automli foo.ml Create foo.mli, which contains type declarations for everything in foo.ml. automli foo.mla Will generate a mli file for foo.ml, using the foo.mla to specify what should be exported. automli will generate old syntax output, automlir will generate revised syntax. (Two executables are necessary because they have to be linked with different camlp4 libraries.) -revised and -old select the syntax to use for input files. The last flag applies to ALL input files, you cannot currently mix old and new syntax. Everything on the command line after -ocamlc is passed to ocamlc when it is used to produce the mli file. For example: automli foo.mla -ocamlc -I lib If foo.ml needs to load modules from lib to compile. Possible declarations in a .mla file: export all ; export none ; Set the default to export everything, or to hide everything. The default is to export everything. You can only have one of these declarations. export type foo ; Export the type "foo" from the ml file. Use this when you have an "export none" declaration to choose what to export. Replace "type" with "typedef", "privdef", "value", "class", "classtype", "exception", "module" or "moduletype" to export something other than a type. privdef causes a private type definition to be exported, so along as the type is exported. typedef causes the definition for a type to be exported as long as the type is exported, overriding privdef. hide type foo ; Hide the type "foo" in the ml file. Use this when you have an "export none" declration to choose what to hide. Again, replace "type" with one of the values listed above to hide something other than a type. fixed ; The interface has been fixed, do not update the MLI file. See also the examples directory. NOTES Remember that MLI files are not there just to annoy you. A traditional (i.e. not automatically generated) MLI file ensures that a module conforms to some interface, If you put automli into your build process, you are switching off a whole layer of checking which the compiler does for you. Remember to add "fixed" declarations when the interface to your module has stablised. Also, automatically generating MLI files using a makefile will spoil seperate compilation, as all modules which depend on a module will need to be rebuilt whenever the module implementation changes. Finally, MLI files usually contain a bunch of comments documenting the functions and types in a module. Automli modules do not, so you need to consider how people will know what your module does. BUGS Two previous issues with recursive types and open constraints on objects have been fixed. There no other known issues, if you find any, please report them. TO DO Things which need doing, which I *might* do: * Some more testing * Proper error reporting (line numbers in MLA files etc.) * Comments in MLA files. * Did I miss anything we might want to export? * Compare interface to the old one before overwriting, to avoid * Specify -old/-revised for individual files. * Dynamically load camlp4 modules. automli could do a lot of other stuff, which I probably won't do because it currently seems like too much effort: * Mark individual functions etc. as fixed, rather than the whole module. This would be very useful, but would require parsing the old MLI file before writing a new one. * It would be handy if comments could be placed next to entries in the MLA file which are automatically output to the MLI file. This would solve the "MLI files have no documentation" problem. FEEDBACK Yes, please get in touch with me. Note, I really don't understand camlp4. If there is a smarter/cleaner way to do this. comments please send me an e-mail. In particular, automli relies on the MLast module from camlp4. As this module is undocumented, I can't really assume that the interface is fixed, so automli may break in version of O'Caml later than 3.07 (or even earlier, I haven't checked). CHANGELOG 0.6: Export everything when called on .ml file. 0.5: Private type definitions. 0.4: Several fixes, changes and improvements.