Merge: Autocast and literal arrays

[nit.git] / share / man / nitc.md

diff --git a/share/man/nitc.md b/share/man/nitc.md
index f98d50d..bc21fd3 100644 (file)
--- a/share/man/nitc.md
+++ b/share/man/nitc.md
@@ -115,11 +115,14 @@ See the documentation of these specific modules for details.
 
 `--log`
 :   Generate various log files.
-    Currently unused.
+
+    The tool will generate some files in the logging directory (see `--log-dir`).
+    These files are intended to the advanced user and the developers of the tools.
 
 `--log-dir`
 :   Directory where to generate log files.
-    Currently unused.
+
+    By default the directory is called `logs` in the working directory.
 
 
 `-h`, `-?`, `--help`
@@ -274,6 +277,36 @@ will increase.
 :   Do not compile dead methods (semi-global).
     Need `--rta`.
 
+## LINK-BOOST OPTIMIZATIONS
+
+In `--separate` and in `--erasure` modes, some optimization can be gained by hijacking the linker process.
+
+Warning: these optimisations are not portable since they use extra features of the GNU linker `ld`.
+However, there is very few reasons to not use them if GNU `ld` is available.
+
+`--link-boost`
+:   Enable all link-boost optimizations.
+
+`--colors-are-symbols`
+:   Store colors as symbols instead of static data.
+
+    By default, the various identifiers used to implement OO-mechanisms are stored as genuine constant static variables.
+
+    This option uses linker symbols to encode these identifiers.
+    This makes the compiled program faster since less indirections are required to get the values.
+    It also produces executables that are a little bit smaller since static memory does not have to store the colors.
+
+`--substitute-monomorph`
+:   Replace monomorphic trampolines with direct call.
+
+    Late-binding is implemented with *trampolines*, that are small functions that just select and jump the to right implementations.
+    If, at link-time, is it known that the target will always by the same implementation then all calls to the trampoline are replaced by
+    direct calls to this single implementation.
+
+    Note that using trampolines as indirection slows down the executable.
+    However, it is expected that the gain of monomorphic direct-calls overcompensates the additional indirections in polymorphic trampoline-calls.
+
+    Note: automatically enable option `--trampoline-call`.
 
 ## DANGEROUS OPTIMIZATIONS
 
@@ -323,27 +356,29 @@ Usually you do not need them since they make the generated code slower.
 `--no-shortcut-equal`
 :   Always call == in a polymorphic way.
 
+`--no-tag-primitive`
+:   Use only boxes for primitive types.
+
+The separate compiler uses tagged values to encode common primitive types like Int, Bool and Char.
+This option disables tags and forces such primitive values to be boxed.
+The drawback is that each boxing costs a memory allocation thus increases the amount of work for the garbage collector.
+
+However, in some cases, it is possible that this option improves performance since the absence of tags simplify the implementation
+of OO mechanisms like method calls or equality tests.
+
 `--no-inline-intern`
 :   Do not inline call to intern methods.
 
 `--colo-dead-methods`
 :   Force colorization of dead methods.
 
-`--colors-are-symbols`
-:   Store colors as symbols instead of static data.
-
-    By default, the various identifiers used to implement OO-mechanisms are stored as genuine constant static variables.
-
-    This option uses linker symbols to encode these identifiers.
-    This makes the compiled program faster since less indirections are required to get the values.
-    It also produces executables that are a little bit smaller since static memory does not have to store the colors.
-
-    Warning: the usage of linker symbols is not portable on all toolchains (eg. Mac OS X).
-    Also, this option does nothing on some platforms (like android).
-
 `--no-gcc-directive`
 :   Disable advanced gcc directives for optimization.
 
+`--trampoline-call`
+:   Use an indirection when calling.
+
+    Just add the trampolines of `--substitute-monomorph` without doing any aditionnal optimizations.
 
 ## INTERNAL OPTIONS
 
@@ -400,6 +435,11 @@ They are useless for a normal user.
 `--stub-man`
 :   Generate a stub manpage in pandoc markdown format.
 
+`--keep-going`
+:   Continue after errors, whatever the consequences.
+
+The tool does not stop after some errors but continue until it produces incorrect result, crashes, erases the hard drive, or just continue forever in an infinite loop.
+This option is used to test the robustness of the tools by allowing phases to progress on incorrect data.
 
 # ENVIRONMENT VARIABLES