Commits

camlspotter  committed d907125 Merge

doc update

  • Participants
  • Parent commits e3f2538, 4791f19

Comments (0)

Files changed (1)

 Introduction
 ===============================
 
-Many existing OCaml libraries, applications and the compiler itself do not produce or install the annotation files (.annot, .cmt, .cmti, .spot, .spit) which are essential for subexpression type queries (caml-types.el), definition seaches and code refactoring (TypeRex and OCamlSpotter). If you want to use development tools, you have to:
+Many existing OCaml libraries, applications and the compiler itself do not produce or install the annotation files (.annot, .cmt, .cmti, .spot, .spit) which are essential for sub-expression type queries (caml-types.el), definition seaches and code refactoring (TypeRex and OCamlSpotter). If you want to use these development tools, you have to:
 
 * Rebuild all the software from their source, adding -annot and -bin-annot options to compiler flags in build scripts i.e. Makefile/OCamlBuild/OMakefile.
 * Install those annotation files together with the library objects and signatures. (Require modification of the build scripts)
 * A very small compiler patch which activates -annot and -bin-annot if OCAML_ANNOT environment variable is defined. (You no longer need to add -annot/-bin-annot to the build scripts.)
 * A small tool to install annotation files to the library destination directory. (You no longer need to add annotation file installation to the build scripts.)
 
+You STILL need to recompile the compiler and the libraries, but no need of changing their build scripts. 
+
+Annot compiler patch
+===============================
+
 For the first workaround, you need a small patch available from::
 
     hg clone -b annot https://bitbucket.org/camlspotter/mutated_ocaml
 
 or included in this directory, ocaml-annot-<version>.patch.
 
-For the second one, you can use SpotInstall. This tool.
+You can also try OPAM compiler switch ``4.00.1+annot``. 
+
+SpotInstall
+==============================
+
 
 Installation
-==============================
+-----------------------------
 
 You need:
 
     omake 
     omake install
 
-Synopsis
-==============================
+You can also install SpotInstall via OPAM: ``opam install spotinstall``.
+But you know this is source package, as always, it might fail.
 
-Stay in the source code directory of ``<package>``, then
+Synopsis (how-to-use)
+------------------------------------
 
-::
+First of all, to produce the binary annotation files, 
+the library must be installed, either with:
 
-    spotinstall 
+* The patched compiler.
+* or, the vanilla compiler, adding ``-bin-annot`` compiler option at the build scripts of the library.
+
+Binary annotation files are now in the source directory, but not yet installed,
+since its build scripts often do not know how to install them.
+Let's use SpotInstall to copy these binary annotation files.
+
+Suppose the library provides OCamlFind package ``<package>``, then,
+staying in the source code directory::
+
     spotinstall <packages>
 
-The command checks the files in the installation directory of OCamlFind package ``<package>``, and if there are corresponding annotation files in the current and its sub directories, copy them to the installation directory. If ``<packages>`` is omitted, all the installed ocamlfind packages (except those from OCaml compiler) are searched.
+The command checks the files in the destination directory of OCamlFind package ``<package>``, and if there are corresponding annotation files in the source directory, copy them to the destination. 
+
+If ``<packages>`` is omitted, all the installed ocamlfind packages (except those from OCaml compiler) are searched. Normally it takes long time.
 
 If ``<package>`` is ``ocaml``, spotinstall works bit differently and copies the annotation files built under OCaml compiler source tree.
 
-
-Live with OPAM
+How to live with OPAM
 ===============================
 
-If you want to browse source files of OPAM packages.
+Note: OPAM is still in beta. It means that this explanation can become obsolete at any time.
 
 Keep the source files
 -----------------------
 
-OPAM removes compiled source files by default. Upgrade your OPAM at least 0.8.2, 
+OPAM removes compiled source files by default. 
+Upgrade your OPAM at least 0.8.2, 
 then set OPAMKEEPBUILDDIR environment variable with non-empty string.
 
 
 -----------------------
 
 Run ``spotinstall`` after ``opam install``, at the OPAM build directory.
+Usually, your OPAM build directory is at 
+``$HOME/.opam/<compiler switch>/build/``.
+
+How to live with GODI or others
+=====================================
+
+Dunno, since I do not use GODI. Good luck. But general keypoints are:
+
+* Keep the compiled source code, or no browsing possible
+* Somehow hook the packager's final installation phase, in order to exec spotinstall command. Probably wrapping ``ocamlfind install`` might be a good idea, though I have not tried it.
+
+How to live with OCaml binary packages from my preferred OS distribution
+=============================================================================
+
+No way. SpotInstall cannot help binaries.