Skip to content

Commit

Permalink
Lint markdown - without changes to content
Browse files Browse the repository at this point in the history
  • Loading branch information
wolf99 committed Apr 2, 2024
1 parent edd6a13 commit 002828f
Show file tree
Hide file tree
Showing 85 changed files with 937 additions and 577 deletions.
93 changes: 35 additions & 58 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
# Contribution Guidelines


## Reporting Issues

If you encounter a problem when using infer or if you have any questions, please open a
Expand All @@ -14,6 +13,7 @@ We welcome contributions via [pull requests on GitHub](https://github.com/facebo

You'll want to install a few more dependencies to comfortably hack on the infer codebase;
in order to do this run `./build_infer.sh` which will allow you to then run:

```sh
make devsetup
```
Expand All @@ -23,14 +23,11 @@ make devsetup
- The default build mode ("dev") makes all build warnings *fatal*. If you want the build to ignore
warnings, for example to be able to test an infer executable before polishing the code to remove
warnings, you can build in "dev-noerror" mode with `make BUILD_MODE=dev-noerror`.

- Faster edit/build cycle when working on OCaml code inside infer/src/: build inside infer/src/
(skips building the models after infer has been built), and build only what is needed for type
checking with `make -j -C infer/src check`. You need to have run `make -j` at some point before.

- Alternatively, if you want to test your changes on a small example, build in bytecode mode:
`make -j -C infer/src byte`.

- In general, `make` commands from the root of the repository make sure that dependencies are in a
consistent and up-to-date state (e.g., they rebuild infer and the models before running steps that
use infer), while running `make` commands from within subdirectories generally assumes that
Expand All @@ -40,26 +37,23 @@ make devsetup
necessary before running the test, but running `make -C infer/tests/codetoanalyze/java/biabduction/ test`
will just execute the test.


### Debugging OCaml Code

- Printf-debug using `Logging.debug_dev`. It comes with a warning so
that you don't accidentally push code with calls to `debug_dev` to
the repo.

- Browse the documentation of OCaml modules in your browser with `make doc`

- When using `ocamldebug`, and in particular when setting break points
with `break @ <module> <line>` don't forget that an infer module `M`
is in reality called `InferModules__M`, or `InferBase__M`, or
... See the html documentation of the OCaml modules from `make doc`
if you're unsure of a module name.

```console
$ ledit ocamldebug infer/bin/infer.bc.exe
(ocd) break @ InferModules__InferAnalyze 100
Breakpoint 1 at 9409684: file backend/InferAnalyze.ml, line 99, characters 18-78
```
```console
$ ledit ocamldebug infer/bin/infer.bc.exe
(ocd) break @ InferModules__InferAnalyze 100
Breakpoint 1 at 9409684: file backend/InferAnalyze.ml, line 99, characters 18-78
```

- To test the infer OCaml code you can use the OCaml toplevel. To
build the OCaml toplevel with the infer modules pre-loaded, run
Expand All @@ -71,7 +65,6 @@ Breakpoint 1 at 9409684: file backend/InferAnalyze.ml, line 99, characters 18-78
Many operations require the results directory and database to be
initialized with `ResultsDir.assert_results_dir ""`.


## Contributor License Agreement

We require contributors to sign our Contributor License Agreement. In
Expand All @@ -88,80 +81,71 @@ Thanks!
### All Languages

- Indent with spaces, not tabs.

- Line width limit is 100 characters.

- In general, follow the style of surrounding code.

### OCaml

- The module IStd (infer/src/istd/IStd.ml) is automatically opened in every file. Beware that this
can cause weird errors such as:
```
$ pwd
/somewhere/infer/infer/src
$ cat base/toto.ml
let b = List.mem true [true; false]
$ make
[...]
File "base/toto.ml", line 1, characters 17-21:
Error: This variant expression is expected to have type 'a list
The constructor true does not belong to type list
```

```console
$ pwd
/somewhere/infer/infer/src
$ cat base/toto.ml
let b = List.mem true [true; false]
$ make
[...]
File "base/toto.ml", line 1, characters 17-21:
Error: This variant expression is expected to have type 'a list
The constructor true does not belong to type list
```

- All modules open `IStd` using `open! IStd`. This is to make that fact more explicit (there's also
the compilation flag mentioned above), and also it helps merlin find the right types. In
particular this also opens `Core.Std`.

- Do not add anything to `IStd` unless you have a compelling reason to do so, for instance if you
find some utility function is missing and is not provided by
[`Core`](https://ocaml.janestreet.com/ocaml-core/latest/doc/core/).

- Polymorphic equality is disabled; use type-specific equality instead, even for primitive types
(e.g., `Int.equal`). However, if your module uses a lot of polymorphic variants with no arguments
you may safely `open PolyVariantEqual`.

If you try and use polymorphic equality `=` in your code you will get a compilation error, such as:
```
Error: This expression has type int but an expression was expected of type
[ `no_polymorphic_compare ]
```

```console
Error: This expression has type int but an expression was expected of type
[ `no_polymorphic_compare ]
```

- Alias and use `module L = Logging` for all your logging needs. Refer to its API in Logging.mli for
documentation.

- Check that your code compiles without warnings with `make -j test_build` (this also runs as part
of `make test`).

- Apart from `IStd` and `PolyVariantEqual`, refrain from globally `open`ing modules. Using
local open instead when it improves readability: `let open MyModule in ...`.

- Avoid the use of module aliases, except for the following commonly-aliased modules. Use
module aliases consistently (e.g., do not alias `L` to a module other than `Logging`).
```OCaml
module CLOpt = CommandLineOption
module F = Format
module L = Logging
module MF = MarkupFormatter
```

```OCaml
module CLOpt = CommandLineOption
module F = Format
module L = Logging
module MF = MarkupFormatter
```

- Use `[@@deriving compare, equal]` to write comparison/equality functions whenever possible.
Watch out for [this issue](https://github.com/ocaml-ppx/ppx_deriving/issues/116) when writing
`type nonrec t = t [@@deriving compare]`.

- Use named arguments whenever the purpose of the argument is not immediately obvious. In
particular, use named arguments for boolean and integer parameters unless the name of the function
mentions them explicitly. Also use named arguments to disambiguate between several arguments of
the same type.

- Use named arguments for functions taken as argument; it is common to name a function argument
`f`. For instance: `List.map : 'a list -> f:('a -> 'b) -> 'b list`.

- In modules defining a type `t`, functions that take an argument of that type should generally have
that argument come first, except for optional arguments: `val f : ?optional:bool -> t -> ...`.

- Use the `_hum` suffix to flag functions that output human-readable strings.

- Format code with [ocamlformat](https://github.com/ocaml-ppx/ocamlformat).

### C/C++/Objective-C
Expand All @@ -172,20 +156,16 @@ Follow `clang-format` (see ".clang-format" at the root of the repository).

- Make sure infer builds: `make -j test_build`. Refer to the [installation
document](https://github.com/facebook/infer/blob/main/INSTALL.md) for details.

- Run the tests: `make -j 4 test` (adjust 4 to the number of cores available of your machine). The
tests (almost) all consist of the same three ingredients:
1. Some source code to run infer on.
2. An "issues.exp" file where each line represents one item of output of the test. For most tests,
one line is one issue reported by infer.
3. A `Makefile` that orchestrates the test, for instance running infer on the source code and
comparing the results with issues.exp using `diff`.

- If your changes modified some of the expected outputs and if the changes make sense, you can
update the expected test results by running `make test-replace`.

- If relevant, add a test for your change.

- To add a test that infer finds (or does not find) a particular issue, add your test in
"infer/tests/codetoanalyze/{language}/{analyzer}/". Look at the `Makefile` in that directory and
make sure it runs your test. "{analyzer}" is often an infer analyzer (as in
Expand All @@ -200,21 +180,18 @@ Follow `clang-format` (see ".clang-format" at the root of the repository).
- Test procedures documenting current limitations of the analyzer should have the prefix `FP_`
(for "false positive") or `FN_` (for "false negative") and a comment explaining why the analyzer
gets the wrong answer.


- To add a test that a certain build system integration or a command-line option works in a certain
way, add a test in "infer/tests/build_systems/".

- If you created a new Makefile for your test, add it to the root "Makefile", either to the
`DIRECT_TESTS` (first case) or to the `BUILD_SYSTEMS_TESTS` variable (second case). Gate the
test appropriately if it depends on Java or Clang or Xcode (see how other tests do it).

- It can be useful to look at the debug HTML output of infer to see the detail of the symbolic
execution. For instance:
```sh
$ infer --debug -- clang -c examples/hello.c
$ firefox infer-out/captured/hello.c.*.html
```

```console
infer --debug -- clang -c examples/hello.c
firefox infer-out/captured/hello.c.*.html
```

## Updating infer.opam and infer.opam.locked

Expand Down
6 changes: 3 additions & 3 deletions FILES.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#Files in infer/bin/
# Files in infer/bin/

## Top-level commands

*infer* : Main command to run Infer. Check out the docs for instructions on how to use it.
`infer` : Main command to run Infer. Check out the docs for instructions on how to use it.

*infer-<command>* : Infer subcommands. Running `infer-<command> [options]` is the same as running `infer <command> [options]`.
`infer-<command>` : Infer subcommands. Running `infer-<command> [options]` is the same as running `infer <command> [options]`.
6 changes: 0 additions & 6 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ the instructions in our [Getting
Started](http://fbinfer.com/docs/getting-started/#get-infer)
page to install Infer.


## Infer dependencies for MacOSX

Here are the prerequisites to be able to compile Infer on MacOSX. This
Expand All @@ -35,7 +34,6 @@ You can install some of these dependencies using
brew install autoconf automake cmake opam pkg-config sqlite gmp mpfr java
```


## Infer dependencies for Linux

Here are the prerequisites to be able to compile Infer on Linux. This
Expand All @@ -52,7 +50,6 @@ is required to compile everything from source.

See also the distro-specific instructions for Ubuntu and Debian below.


## Install Infer from source

Run the following commands to get Infer up and running:
Expand All @@ -78,7 +75,6 @@ Objective-C source code.
See `./build-infer.sh --help` for more options, eg `./build-infer.sh`
on its own will build the analyzers for both Java and C/ObjC.


## Install Infer from source without opam

If for some reason you prefer to install Infer's OCaml dependencies by
Expand All @@ -94,13 +90,11 @@ sudo make install
export PATH=`pwd`/infer/bin:$PATH
```


## How to install the dependencies on Linux

See the Dockerfile in docker/ for inspiration. It includes the
dependencies needed to build Infer on Debian 9 (stretch).


### Setting up opam

Get opam from your distribution, or from the
Expand Down
1 change: 1 addition & 0 deletions ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
Please make sure your issue is not addressed in the [FAQ](https://fbinfer.com/docs/support#troubleshooting).

Please include the following information:

- [ ] The version of infer from `infer --version`.
- [ ] Your operating system and version, for example "Debian 9", "MacOS High Sierra", whether you are using Docker, etc.
- [ ] Which command you ran, for example `infer -- make`.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,5 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).

Infer is MIT-licensed.

Note: Enabling Java support may require you to download and install
Note: Enabling Java support may require you to download and install
components licensed under the GPL.
4 changes: 1 addition & 3 deletions docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,18 @@ contains a docker file to install Infer within a
[docker](https://www.docker.com/) container. This can be used to
quickly try Infer or to deploy Infer.


## Pre-requisites

To use this docker image, you will need a working docker
installation. See the instructions for
[Linux](http://docs.docker.com/linux/step_one/) or
[MacOSX](http://docs.docker.com/mac/step_one/) as appropriate.


## How to use

This docker file will use the latest
[released](https://github.com/facebook/infer/releases) version of
Infer.
Infer.

1. Get docker running, e.g. using Docker Quickstart Terminal.
2. go to the version of your choice, e.g. `cd docker/1.1.0/`
Expand Down
3 changes: 1 addition & 2 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Contents
--------

- `Hello.java`: try this example by running
```infer -- javac Hello.java ```
```infer -- javac Hello.java```

- `Hello.m`: try this example by running
```infer -- clang -c Hello.m```
Expand Down Expand Up @@ -38,4 +38,3 @@ Note
The infer toplevel command must be in your PATH for the commands above to
succeed. Otherwise, modify the commands to use the correct path to infer, eg
```../infer/bin/infer -- javac Hello.java```

6 changes: 3 additions & 3 deletions facebook-clang-plugins/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,8 @@ Structure of the repository
---------------------------

- libtooling : frontend plugins (currently a clang-to-json AST exporter),

- clang-ocaml : OCaml libraries to process the JSON output of frontend plugins,


Quick start
-----------

Expand All @@ -19,13 +17,15 @@ The plugin requires recent version of the clang compiler, re-compiled from sourc
To compile and use the required version of clang, please run ./clang/setup.sh.

Caveat:

- Because of the nature of C++, clang and the plugins need to be compiled with the exact same C++ libraries.
- Also, the default stripping command of clang in release mode breaks plugins.

Once the target compiler is installed, `make test` should run the unit tests.

OCaml users may also run:
```

```console
make -C clang-ocaml test #requires proper ocaml libraries, see included clang-ocaml/README
```

Expand Down
Loading

0 comments on commit 002828f

Please sign in to comment.