Summary: `make doc` will use `jbuilder` (which in turn uses `odoc`) to generate the documentation for infer's modules. This is useful to browse the APIs of infer and gives a more discoverable place to host more general documentation about infer's internals. Besides the actual plumbing necessary to generate the docs, this diff also - Moves the various infer/src/*/README.md to index.mld files that make it to the generated docs - Fixes some doc comments that would anger `ocamldoc` Closes #435 Reviewed By: mbouaziz Differential Revision: D8314572 fbshipit-source-id: 4a5c70emaster
Jules Villard
7 years ago
committed by
Facebook Github Bot
parent
aee02e27ef
commit
710dae8ee4
@ -1,12 +0,0 @@
|
||||
# Intermediate Representation
|
||||
|
||||
The Intermediate Representation is a format used by the back-end for analysis. It is produced by one of the front-ends, one for each program analyzed.
|
||||
|
||||
The main entry point is the intermediate language in [Sil](Sil.mli).
|
||||
|
||||
The control flow graph module is [Cfg](Cfg.mli).
|
||||
|
||||
The call graph module is [Cg](Cg.mli).
|
||||
|
||||
The type environment module is [Tenv](Tenv.mli).
|
||||
|
||||
@ -0,0 +1,11 @@
|
||||
{1 Library InferIR: Intermediate Representation}
|
||||
The Intermediate Representation, called [SIL], is a format used by the back-end for analysis. It is produced by the front-ends.
|
||||
|
||||
The entry point of this library is the module:
|
||||
{!module-InferIR}.
|
||||
|
||||
The main entry point is the intermediate language in {!module-InferIR.Sil}.
|
||||
|
||||
The control flow graph module is {!module-InferIR.Cfg}.
|
||||
|
||||
The type environment module is {!module-InferIR.Tenv}.
|
||||
@ -1,3 +0,0 @@
|
||||
# AbsInt
|
||||
|
||||
Code + utilities for the Infer.AI abstract interpretation framework.
|
||||
@ -0,0 +1,5 @@
|
||||
{1 Library InferGenerated}
|
||||
Source code that is generated from ATD definitions.
|
||||
|
||||
The entry point of this library is the module:
|
||||
{!module-InferGenerated}.
|
||||
@ -1,9 +0,0 @@
|
||||
# Back End
|
||||
|
||||
The back end is responsible for the analysis of a project starting from an intermediate representation stored in the results directory, typically `infer-out`.
|
||||
|
||||
The main entry point for infer binary is [infer.ml](infer.ml).
|
||||
|
||||
Entry point for the analysis is module [InferAnalyze](InferAnalyze.ml).
|
||||
|
||||
Module [InferPrint](InferPrint.ml) is used to export the analysis results.
|
||||
@ -1,2 +1,6 @@
|
||||
{1 Library InferBase}
|
||||
Utility modules that are somewhat specific to infer, usually because
|
||||
they depend on Config.ml.
|
||||
|
||||
The entry point of this library is the module:
|
||||
{!module-InferBase}.
|
||||
@ -1,3 +0,0 @@
|
||||
# Checkers
|
||||
|
||||
Transfer functions, abstract domains, and checker configuration.
|
||||
@ -1,29 +0,0 @@
|
||||
# Clang Front-End
|
||||
|
||||
This is the front-end for the clang compiler.
|
||||
|
||||
The main entry point is [`ClangWrapper`](ClangWrapper.ml).
|
||||
|
||||
## General structure
|
||||
1. Given a compilation command from the build system, sanitize it, attach `ASTExporter` clang plugin to the relevant commands and run it.
|
||||
2. Parse the AST from Biniou format to OCaml data structure.
|
||||
3. (optional) Invoke translation to `SIL` via [`CFrontend`](cFrontend.ml).
|
||||
4. (optional) Invoke linters via [`CFrontend_checkers_main`](CFrontend_checkers_main.ml). [More on linters](http://fbinfer.com/docs/linters.html)
|
||||
|
||||
## Format of the AST
|
||||
OCaml data structure is defined in `atd` format. The `clang_ast_t.atd` file is generated from comments in [ASTExporter.h](https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ASTExporter.h) file.
|
||||
|
||||
For more information, refer to the relevant documentation in `facebook-clang-plugins`:
|
||||
- [libtooling/ATD_GUIDELINES.md](https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ATD_GUIDELINES.md)
|
||||
- [clang-ocaml/README.md](https://github.com/facebook/facebook-clang-plugins/blob/master/clang-ocaml/README.md)
|
||||
|
||||
## Hacking on `.atd` file
|
||||
1. Create a simple example (`example.cpp`) source file with construct that needs to be exported. The smaller the better.
|
||||
2. Export extra information by changing code in [`libtooling/ASTExporter.h`](https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ASTExporter.h). For more information, refer to the [ATD_GUIDELINES](https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ATD_GUIDELINES.md).
|
||||
3. Compile Infer with the new version of `facebook-clang-plugins`. Running `make all` from top level of Infer repository will do that. Sometimes there may be compilation errors due to `.atd` file changes - they need to be fixed.
|
||||
4. Use newly exported information information in the frontend.
|
||||
|
||||
Tips & Tricks:
|
||||
- To view the AST in a human readable version, Infer can generate `.bdump` file: `infer -g -- clang -c example.cpp && sh example.cpp.ast.sh`. Then open `example.cpp.ast.bdump`
|
||||
- To inspect ast dump visually: `clang -c example.cpp -Xclang -ast-dump`. It doesn't include all the information that Infer sees, but it's pretty concise
|
||||
- If running `bdump` is failing (it happens on huge sources sometimes), there is a way to view it in "Yojson" format. To do that, replace all occurrences of `BiniouASTExporter` with `YojsonASTExporter` in `.ast.sh` script.
|
||||
@ -1,5 +0,0 @@
|
||||
# Eradicate @Nullable Checker
|
||||
|
||||
Eradicate is a type checker for `@Nullable` annotations for Java. The goal is to eradicate null pointer exceptions. See [Eradicate](http://fbinfer.com/docs/eradicate.html).
|
||||
|
||||
The main entry point is module [Eradicate](eradicate.mli).
|
||||
@ -0,0 +1,63 @@
|
||||
{1 Library infer}
|
||||
These are the modules used by infer that are not packaged into sub-libraries.
|
||||
|
||||
The entry point of this library is the module:
|
||||
{!module-InferModules}.
|
||||
|
||||
|
||||
The modules are split into several directories in the source tree of infer.
|
||||
|
||||
{2 absint/}
|
||||
Code + utilities for the Infer.AI abstract interpretation framework. Start at {!module-InferModules.AbstractInterpreter}.
|
||||
|
||||
{2 backend/}
|
||||
The backend is responsible for the analysis of a project starting from an intermediate representation stored in the results directory, typically [infer-out].
|
||||
|
||||
The entry point for the analysis is the module {!module-InferModules.InferAnalyze}.
|
||||
|
||||
The module {!module-InferModules.InferPrint} is used to export the analysis results.
|
||||
|
||||
{2 checkers/}
|
||||
Transfer functions, abstract domains, and checker configuration.
|
||||
|
||||
{2 clang/}
|
||||
This is the frontend for the clang compiler. The main entry point is {!module-InferModules.ClangWrapper}.
|
||||
|
||||
{3 General structure}
|
||||
+ Given a compilation command from the build system, sanitize it, attach [ASTExporter] clang plugin to the relevant commands and run it.
|
||||
+ Parse the AST (Abstract Syntax Tree) from the Biniou format into an OCaml data structure.
|
||||
+ If enabled, invoke translation to [SIL] via {!module-InferModules.CFrontend}.
|
||||
+ If enabled, invoke linters via {!module-InferModules.CFrontend_checkers_main}. More on linters here: {:http://fbinfer.com/docs/linters.html}.
|
||||
|
||||
{3 Format of the AST}
|
||||
The OCaml data type is defined in [atd] format. The [clang_ast_t.atd] file is generated from the comments in the {{:https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ASTExporter.h} [ASTExporter.h]} file.
|
||||
|
||||
For more information, refer to the relevant documentation in [facebook-clang-plugins]:
|
||||
- {{:https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ATD_GUIDELINES.md} [libtooling/ATD_GUIDELINES.md]}
|
||||
- {{:https://github.com/facebook/facebook-clang-plugins/blob/master/clang-ocaml/README.md} [clang-ocaml/README.md]}
|
||||
|
||||
{3 Hacking on the [.atd] file}
|
||||
+ Create a simple example ([example.cpp]) source file with construct that needs to be exported. The smaller the better.
|
||||
+ Export the extra information by changing the code in {{:https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ASTExporter.h} [libtooling/ASTExporter.h]}. For more information, refer to the {{:https://github.com/facebook/facebook-clang-plugins/blob/master/libtooling/ATD_GUIDELINES.md} [ATD_GUIDELINES]}.
|
||||
+ Compile Infer with the new version of [facebook-clang-plugins]. Running [make] from top level of Infer repository will do that. Sometimes there may be compilation errors due to [.atd] file changes - they need to be fixed.
|
||||
+ Use newly exported information information in the frontend.
|
||||
|
||||
Tips & Tricks:
|
||||
- To view the AST in a human readable version, Infer can generate [.bdump] file: [infer -g -- clang -c example.cpp && sh example.cpp.ast.sh]. Then open [example.cpp.ast.bdump].
|
||||
- To inspect AST dump visually: [clang -c example.cpp -Xclang -ast-dump]. It doesn't include all the information that Infer sees, but it's pretty concise
|
||||
- If running [bdump] is failing (it happens on huge sources sometimes), there is a way to view it in "Yojson" format. To do that, replace all occurrences of [BiniouASTExporter] with [YojsonASTExporter] in the [.ast.sh] script.
|
||||
|
||||
{2 eradicate/ }
|
||||
Eradicate [@Nullable] Checker
|
||||
|
||||
Eradicate is a type checker for [@Nullable] annotations for Java. The goal is to eradicate null pointer exceptions. See the online docs at {:http://fbinfer.com/docs/eradicate.html}.
|
||||
|
||||
The main entry point is module {!module-InferModules.Eradicate}.
|
||||
|
||||
{2 java/}
|
||||
Java Frontend; this is the frontend for Java compilers.
|
||||
|
||||
The main entry point is {!module-InferModules.JMain}.
|
||||
|
||||
{2 infer executable}
|
||||
You'll find the infer binary in infer.ml. It is not part of this library.
|
||||
@ -1,2 +1,6 @@
|
||||
{1 Library InferStdLib}
|
||||
Utility modules not specific to infer. In particular, nothing here
|
||||
should depend on Config.ml.
|
||||
|
||||
The entry point of this library is the module:
|
||||
{!module-InferStdlib}.
|
||||
@ -1,5 +0,0 @@
|
||||
# Java Front-End
|
||||
|
||||
This is the front-end for java compilers.
|
||||
|
||||
The main entry point is [JMain](jMain.ml).
|
||||
Loading…
Reference in new issue