Debug perf manual

Changes

@@ -94,6 +94,12 @@ Working version
    review by Florian Angeletti, Anil Madhavapeddy, Gabriel Scherer,
    and Miod Vallat)
 
+- #?????: Document support for Linux perf and frame pointers.
+  (Tim McGilchrist, review by ???)
+
+- #?????: Document support for native debugging with GDB and LLDB.
+  (Tim McGilchrist, review by ???)
+
 ### Compiler user-interface and warnings:
 
 - #13428: support dump=[source | parsetree | lambda | ... | cmm | ...]

manual/README.md

@@ -8,14 +8,14 @@ Prerequisites
 
 - A LaTeX installation.
 
-- The HeVeA LaTeX-to-HTML converter (available in OPAM):
+- The HeVeA LaTeX-to-HTML converter (available in opam):
   <http://hevea.inria.fr/>
 
 Note that you must make sure `hevea.sty` is installed into TeX properly. Your
 package manager may not do this for you. Run `kpsewhich hevea.sty` to check.
 
 
-Building the manual
+Building the Manual
 --------
 
 0. Build the OCaml compiler (including the native one) from sources.
@@ -38,16 +38,16 @@ In the manual:
 
 - The PDF manual is in directory `texstuff` as file `manual.pdf`.
 
-Source files
+Source Files
 ------------
 The manual is written in an extended dialect of LaTeX and is split across many
 source files. During the build process, these source files are converted into
 classical LaTeX files using the tools available in the `manual/tools`
 directory. These files are then converted to the different output
-formats using either LaTeX or hevea.
+formats using either LaTeX or HeVeA.
 
 Each part of the manual corresponds to a specific directory, and each distinct
-chapters (or sometimes sections) are mapped to a distinct `.etex` file:
+chapter (or sometimes sections) are mapped to a distinct `.etex` file:
 
 - Part I, Introduction to OCaml: `tutorials`
   - The core language: `coreexamples.etex`
@@ -57,7 +57,7 @@ chapters (or sometimes sections) are mapped to a distinct `.etex` file:
   - Advanced examples with classes and modules: `advexamples.etex`
 
 - Part II, The OCaml language: `refman`
-  This part is divided in two very distinct chapters; the
+  This part is divided in two distinct chapters; the
   `OCaml language` chapter and the `Language extensions` chapter.
 
   - The OCaml language: `refman.etex`
@@ -85,8 +85,10 @@ chapters (or sometimes sections) are mapped to a distinct `.etex` file:
     - Optimisation with Flambda: `flambda.etex`
     - Fuzzing with afl-fuzz: `afl-fuzz.etex`
     - Runtime tracing with Runtime_events: `runtime_tracing.etex`
+    - The “Tail Modulo Constructor” program transformation: `tail-mod-cons.etex`
+    - Runtime detection of data races with ThreadSanitizer: `tsan.etex`
 
-Note that ocamlc,ocamlopt and the toplevel options overlap a lot.
+Note that `ocamlc`, `ocamlopt`, and the toplevel options overlap a lot.
 Consequently, these options are described together in the file
 `unified-options.etex` and then included from `comp.etex`, `native.etex`,
 and `top.etex`. If you need to update this list of options, the top comment
@@ -98,20 +100,22 @@ of `unified-options.etex` contains the relevant information.
     - The core library: `core.etex`
     - The standard library: `stdlib-blurb.etex`
     - The compiler front-end: `compilerlibs.etex`
-    - The unix library: Unix system calls: `libunix.etex`
-    - The str library: regular expressions and string processing: `libstr.etex`
+    - The Unix library: Unix system calls: `libunix.etex`
+    - The `str` library: regular expressions and string processing: `libstr.etex`
     - The threads library: `libthreads.etex`
     - The runtime_events library: `libruntime_events.etex`
     - The dynlink library: dynamic loading and linking of object files:
       `libdynlink.etex`
+    - Recently removed or moved libraries (Graphics, Bigarray, Num, LablTk):
+      `old.etex`
 
-Latex extensions
+Latex Extensions
 ----------------
 
 ### Sections (and subsections, and subsubsections)
 
 In order to provide stable links to all part of the manual, the standard
-`\section`, `\subsection` and `\subsubsection` macros are replaced by
+`\section`, `\subsection`, and `\subsubsection` macros are replaced by
 variants that take the section label as their first argument.
 For instance, in the manual, you have to write
 ```latex
@@ -121,20 +125,20 @@ rather than
 ```latex
 \section{Basics\label{s:basics}}
 ```
-This restriction ensures that hevea picks the section label when generating the
-header ids.
+This restriction ensures that HeVeA picks the section label when generating the
+header IDs.
 
 A similar macro, `\lparagraph`, is provided for paragraphs.
 
-### Caml environments
+### Caml Environments
 
 The tool `tools/ocamltex` is used to generate the LaTeX code for the examples
 in the introduction and language extension parts of the manual. It implements
 two pseudo-environments: `caml_example` and `caml_eval`.
 
-The pseudo-environment `caml_example` evaluates its contents using an ocaml
+The pseudo-environment `caml_example` evaluates its contents using an OCaml
 interpreter and then translates both the input code and the interpreter output
-to LaTeX code, e.g.
+to LaTeX code, e.g.,
 ```latex
 \begin{caml_example}{toplevel}
 let f x = x;;
@@ -148,12 +152,12 @@ let f x = x
 ```
 
 The {verbatim} or {toplevel} argument of the environment corresponds to the mode
-of the example. Three modes are available -- toplevel, verbatim and signature.
+of the example. Three modes are available -- toplevel, verbatim, and signature.
 The `toplevel` mode mimics the appearance and behavior of the toplevel. In
 particular, toplevel examples must end with a double semi-colon `;;`, otherwise
 an error would be raised. The `verbatim` does not require a final `;;` and is
 intended to be a lighter mode for code examples. If you want to declare a
-signature instead of ocaml code, you must use the `{signature}` argument to the
+signature instead of OCaml code, you must use the `{signature}` argument to the
 `caml_example` environment.
 
 ```latex
@@ -219,20 +223,20 @@ let pi = 4. *. atan 1.;;
 let f x = x +. pi;;
 \end{caml_example}
 ```
-Beware that the detection code for these pseudo-environments is quite brittle
+Beware that the detection code for these pseudo-environments is quite brittle,
 and the environments must start and end at the beginning of the line.
 
 ### Quoting
 
 The tool `tools/texquote2` provides support for verbatim-like quotes using
-`\"` delimiters. More precisely, outside of caml environments and verbatim
+`\"` delimiters. More precisely, outside of Caml environments and verbatim
 environments, `texquote2` translates double quotes `"text"` to
 `\machine{escaped_text}`.
 
-### BNF grammar notation
+### BNF Grammar Notation
 
 The tool `tools/transf` provides support for BNF grammar notations and special
-quotes for non-terminal. When transf is used, the environment `syntax` can
+quotes for non-terminal. When `transf` is used, the environment `syntax` can
 be used to describe grammars using BNF notation:
 ```latex
 \begin{syntax}
@@ -257,11 +261,11 @@ Moreover, outside of the syntax environment, `@`-quotes can be used
 to introduce fragment of grammar: `@'(' module-expr ')'@`. As a consequence,
 when this extension is used `@` characters must be escaped as `\@`.
 This extension is used mainly in the language reference part of the manual.
-and a more complete description of the notation used is available in the
+A more complete description of the notation used is available in the
 first subsection of `refman/refman.etex`.
 
-Consistency tests
+Consistency Tests
 -----------------
 
-The `tests` folder contains consistency tests that checks that the manual
+The `tests` folder contains consistency tests that checks that the manual,
 and the rest of the compiler sources stay synced.

manual/src/allfiles.etex

@@ -69,7 +69,9 @@ and as a
 \input{ocamldep.tex}
 \input{ocamldoc.tex}
 \input{debugger.tex}
+\input{native-debugger.tex}
 \input{profil.tex}
+\input{profile-perf.tex}
 \input{intf-c.tex}
 \input{flambda.tex}
 \input{afl-fuzz.tex}

manual/src/cmds/Makefile

@@ -10,8 +10,8 @@ TEXQUOTE = $(OCAMLRUN) $(TOOLS)/texquote2
 TRANSF = $(OCAMLRUN) $(TOOLS)/transf
 
 FILES = comp.tex top.tex runtime.tex native.tex lexyacc.tex intf-c.tex \
-  ocamldep.tex profil.tex debugger.tex ocamldoc.tex \
-  warnings-help.tex flambda.tex tail-mod-cons.tex \
+  ocamldep.tex profil.tex profile-perf.tex debugger.tex native-debugger.tex \
+  ocamldoc.tex warnings-help.tex flambda.tex tail-mod-cons.tex \
   afl-fuzz.tex runtime-tracing.tex unified-options.tex tsan.tex
 
 etex-files: $(FILES)