Merge pull request #1218 from souragc/main

Update documentation

Author: souragc

clang/docs/checkedc/3C/CONTRIBUTING.md

@@ -1,10 +1,7 @@
 # Contributing to 3C
 
-Issues and pull requests related to 3C should be submitted to [CCI's
-`checkedc-clang`
-repository](https://github.com/correctcomputation/checkedc-clang), not
-[Microsoft's](https://github.com/microsoft/checkedc-clang), except as
-stated below.
+Issues and pull requests related to 3C should be submitted to 
+[checkedc](https://github.com/checkedc/checkedc-llvm-project) repo.
 
 ## Issues
 
@@ -28,39 +25,133 @@ able to use your work yourself (subject to your ability to keep up
 with us) and we may even direct users who want the functionality to
 your version.
 
-If your contribution does not touch any 3C-specific code (or is a
-codebase-wide cleanup of low risk to 3C) and you can reasonably submit
-it to [Microsoft's
-repository](https://github.com/microsoft/checkedc-clang) instead, we
-generally prefer that you do so. If such a contribution has particular
-benefit to 3C, feel free to let us know, and we may assist you in
-getting your contribution accepted upstream and/or ensure it is merged
-quickly to CCI's repository.
-
-If the previous paragraph does not apply, just submit a pull request
-to CCI's repository. You must grant the same license on your
-contribution as the existing codebase. We do not have a formal
-contributor license agreement (CLA) process at this time, but we may
+You must grant the same license on your contribution as the existing codebase.
+We do not have a formal contributor license agreement (CLA) process at this time, but we may
 set one up and require you to complete it before we accept your
-contribution. Also be aware that we need to keep 5C ([our proprietary
-extension of
-3C](README.md#what-3c-users-should-know-about-the-development-process))
-working, so you may have to wait for us to address 5C-specific
-problems arising from your 3C pull request and/or we may ask you to
-make specific changes to your pull request to accommodate 5C's code.
-
-At the appropriate time during development of a pull request, please
-run the [regression tests](development.md#regression-tests) and
-correct any failures. (For example, it may not make sense to do this
-on a draft pull request containing an unfinished demonstration of an
-idea.) All regression tests must pass (or be disabled if appropriate)
-before your pull request can be merged. If you're changing behavior
-(as opposed to just cleaning up the code), we'll typically require you
-to add or update enough tests to exercise the important behavior
-changes (i.e., those tests fail before your code change and pass after
-it). If there's a concern that your change might affect other cases
-that are not adequately tested yet, we may ask you to add tests for
-those cases as well.
-
-See the [developer's guide](development.md) for additional information
-that may be helpful as you work on 3C.
+contribution.
+
+## Testing
+
+3C has a regression test suite located in `clang/test/3C`. At the
+appropriate time during development of a pull request, please run it
+and correct any failures. (For example, it may not make sense to run
+it on a draft pull request containing an unfinished demonstration of
+an idea.) The easiest way to run it is to run the following in your
+build directory:
+
+```
+ninja check-3c
+```
+
+This command will build everything needed that hasn't already been
+built, run the test suite, report success or failure (exit 0 or 1, so
+you can use it in scripts), and display some information about any
+failures, which may or may not be enough for you to understand what
+went wrong.
+
+For deeper troubleshooting, run the following in your build directory
+to build all dependencies of the test suite:
+
+```
+ninja check-3c-deps
+```
+
+Then run the following in the `clang/test/3C` directory:
+
+```
+llvm-lit -vv TEST.c
+```
+
+where `TEST.c` is the path of the test you want to run (you can also
+specify more than one test). This assumes you've put the `bin`
+subdirectory of your build directory on your `$PATH` or arranged some
+other means of running `llvm-lit` from there. The first `-v` makes
+`llvm-lit` display the stdout and stderr of failed tests; the second
+makes it display the `RUN` commands as they execute so you can tell
+which one failed.
+
+Every `.c` file under `clang/test/3C` is a test file. There are a few
+in subdirectories, so `*.c` will not pick up all of them; instead you
+can use `llvm-lit -vv .` to specify all test files under the current
+directory.
+
+### Diagnostic verification
+
+3C supports the standard Clang diagnostic verifier
+([`VerifyDiagnosticConsumer`](https://clang.llvm.org/doxygen/classclang_1_1VerifyDiagnosticConsumer.html#details))
+for testing errors and warnings reported by 3C via its main `DiagnosticsEngine`.
+(Some 3C errors and warnings are reported via other means and cannot be tested
+this way; the best solution we have for them right now is to `grep` the stderr
+of 3C.) Diagnostic verification can be enabled via the usual `-Xclang -verify`
+compiler option; other diagnostic verification options (`-Xclang
+-verify=PREFIX`, etc.) should also work as normal. These must be passed as
+_compiler_ options, not `3c` options; for example, if you are using `--` on the
+`3c` command line, these options must be passed _after_ the `--`.
+
+Some notes about diagnostic verification in the context of 3C:
+
+* Parsing of the source files uses some of the compiler logic and thus may
+  generate compiler warnings, just as if you ran `clang` on the code. These are
+  sent to the diagnostic verifier along with diagnostics generated by 3C's
+  analysis. If you find it distracting to have to include the compiler warnings
+  in the set of expected diagnostics for a test, you can turn them off via the
+  `-Wno-everything` compiler option (which does not affect diagnostics generated
+  by 3C's analysis).
+
+* The `3c` tool works in several passes, where each pass runs on all translation
+  units: first `3c` parses the source files, then it runs several passes of
+  analysis. If a pass encounters at least one error, `3c` exits at the end of
+  that pass. Diagnostic verification does not change the _point_ at which `3c`
+  exits, but it changes the exit _code_ to indicate the result of verification
+  rather than the presence of errors. The verification includes the diagnostics
+  from all passes up to the point at which `3c` exits (i.e., the same
+  diagnostics that would be displayed if verification were not used). However,
+  an error that doesn't go via the main `DiagnosticsEngine` will cause an
+  unsuccessful exit code regardless of diagnostic verification. (This is
+  typically the behavior you want for a test.)
+
+* Diagnostic verification is independent for each translation unit, so in tests
+  with multiple translation units, you'll have to be careful that preprocessing
+  of each translation unit sees the correct set of `expected-*` directives for
+  the diagnostics generated for that translation unit (or an
+  `expected-no-diagnostics` directive if that translation unit generates no
+  diagnostics, even if other translation units do generate diagnostics). Be
+  warned that since which translation unit generated a given diagnostic isn't
+  visible to a normal user, we don't put much work into coming up with sensible
+  rules for this, but it should at least be deterministic for testing.
+
+Note that some 3C tests use diagnostic verification on calls to `clang` rather
+than `3c`, so if you see `expected-*` directives in a test, you can look at the
+`RUN` commands to see which command has `-Xclang -verify` and is using the
+directives. If you want to verify diagnostics of more than one `RUN` command in
+the same test, you can use different directive prefixes (`-Xclang
+-verify=PREFIX`).
+
+## Coding guidelines
+
+Please follow [LLVM coding
+standards](https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly)
+in your code. Specifically:
+
+* The maximum length of a line: 80 chars
+
+* All comments should start with a Capital letter.
+
+* All Local variables, including fields and parameters, should start
+  with a Capital letter (similar to PascalCase). Short names are
+  preferred.
+
+* A space between the conditional keyword and `(` i.e., `if (`,
+  `while (`, ``for (` etc.
+
+* Space after the type name, i.e., `Type *K` _not_ `Type* K`.
+
+* Space before and after `:` in iterators, i.e., `for (auto &k : List)`
+
+Our goal is that all files should be formatted with `clang-format` and
+pass `clang-tidy` ([more information](clang-tidy.md)), and nonempty
+files should have a final newline (surprisingly, `clang-format` cannot
+enforce this). However, until we have better automation, we decided it
+isn't reasonable to require contributors to manually run these tools
+and fix style nits in each change; instead, we periodically run the
+tools on the entire 3C codebase.

clang/docs/checkedc/3C/INSTALL.md

@@ -19,18 +19,15 @@ fiddly](#mac-os-x), but we have managed it so far.
 
 ## Basics
 
-As described [here](README.md#which-checkedc-clang-repository-to-use),
-you can use either
-https://github.com/correctcomputation/checkedc-clang or
-https://github.com/microsoft/checkedc-clang (or, of course, a
+Start by cloning [checkedc](https://github.com/checkedc/checkedc-llvm-project) repo (or, of course, a
 third-party fork, though we can't be responsible for that). Assuming
 you have already cloned one of these repositories, run the following
-(from the `checkedc-clang` directory or whatever you named your clone)
+(from the `checkedc-llvm-project` directory or whatever you named your clone)
 for a basic build:
 
 ```
 # Get a copy of the Checked C system headers. Use Microsoft's
-# "checkedc" repository regardless of which "checkedc-clang"
+# "checkedc" repository regardless of which "checkedc-llvm-project"
 # repository you use.
 git clone https://github.com/microsoft/checkedc llvm/projects/checkedc-wrapper/checkedc
 

clang/docs/checkedc/3C/README.md

@@ -12,94 +12,37 @@ safety.
 This document describes 3C in general. Here are the [build
 instructions](INSTALL.md). The inference logic is implemented in the
 [`clang/lib/3C` directory](../../../lib/3C) in the form of a library
-that can potentially be used in multiple contexts. As of November
-2020, the only way to use 3C is via the `3c` command line tool in the
+that can potentially be used in multiple contexts.
+
+There are two ways to
+use 3C.
+- The first method is using the command line tool `3c` 
 [`clang/tools/3c` directory](../../../tools/3c); its usage is
 documented in [the readme there](../../../tools/3c/README.md).
+- The second method is to use a vscode extension along with
+clangd lsp plugin. Steps to build and use the plugin can be
+found [here](https://3clsp.github.io/). Note that 3CLSP is based on
+an older fork and therefore won't have the latest changes to 3C.
 
 ## What 3C users should know about the development process
 
-Checked C development as a whole is led by Microsoft in the
-https://github.com/microsoft/checkedc-clang repository. 3C is included
-in the Checked C codebase, but 3C development is led by [Correct
-Computation, Inc.](https://correctcomputation.com/) (CCI) in the
-https://github.com/correctcomputation/checkedc-clang repository, which
-is a fork of Microsoft's repository; changes are periodically merged
-back and forth. (That is, CCI plays roughly the role of a ["subsystem
-maintainer"](https://www.kernel.org/doc/html/latest/process/2.Process.html#how-patches-get-into-the-kernel)
-for 3C, for those familiar with that term from Linux kernel
-development.) Both 3C and the rest of the Checked C tools (including
-the compiler) are available in both repositories, but the repositories
-will generally have different versions of different parts of the code
-at any given time, so [you'll have to decide which repository is more
-suitable for your work](#which-checkedc-clang-repository-to-use).
+The development of Checked C exclusively takes place in the repository
+located at https://github.com/checkedc/checkedc-llvm-project. 3C is included
+in the Checked C codebase. Initially 3C development was led by [Correct
+Computation, Inc.](https://correctcomputation.com/). As of now, 3C is
+integrated into [checkedc](https://github.com/checkedc/checkedc-llvm-project)
+checkedc-llvm-project repo and all furthur development will be in
+[checked](https://github.com/checkedc/checkedc-llvm-project) repo.
 
-Issues and pull requests related to 3C should be submitted to CCI's
+Issues and pull requests related to 3C should be submitted to 
+[checkedc](https://github.com/checkedc/checkedc-llvm-project)
 repository; see [CONTRIBUTING.md](CONTRIBUTING.md) for more
 information.
 
 As of March 2021, 3C is pre-alpha quality and we are just starting to
-establish its public presence and processes. CCI is also working on a
-proprietary extension of 3C called 5C ("**C**orrect **C**omputation's
-**C**hecked-**C**-**C**onvert"). Our current plan is that 3C will
-contain the core inference logic, while 5C will add features to
-enhance developer productivity. If you'd like more information about
-5C, please contact us at [email protected].
-
-### Which `checkedc-clang` repository to use?
-
-We typically recommend that serious 3C users use CCI's repository to
-get 3C fixes and enhancements sooner, but in some scenarios, you may
-be better off with Microsoft's repository. Here, in detail, are the
-factors we can think of that might affect your decision (as of March
-2021):
-
-- CCI strives to merge changes reasonably quickly from Microsoft's
-  repository to CCI's, but most 3C-specific changes are made first in
-  CCI's repository and merged to Microsoft's in batches every few
-  months. Thus, CCI's repository typically gives you a significantly
-  newer version of 3C, while Microsoft's repository typically gives
-  you a somewhat newer version of the rest of the Checked C codebase,
-  including some shared code used by 3C. The implication of that last
-  point is that a fix to the shared code in Microsoft's repository
-  would benefit Microsoft's copy of 3C immediately but would not take
-  effect on CCI's copy until the next merge from Microsoft to CCI, so
-  CCI's copy of 3C is not always newer in _all_ respects.
-
-- While the [3C regression tests](CONTRIBUTING.md#testing) are run on
-  every change to either repository, CCI's copy of 3C undergoes
-  additional testing: a set of "benchmark" tests that run nightly,
-  plus manual use by CCI engineers. If a change to CCI's repository
-  passes the regression tests but breaks the additional tests, we will
-  generally fix the problem quickly. But if the same happens in
-  Microsoft's repository, functionality of Microsoft's copy of 3C that
-  is not covered by the regression tests could remain broken for some
-  time. The problem would likely be detected the next time CCI tries
-  to merge from Microsoft, in which case we would try to get a fix
-  into Microsoft's repository reasonably quickly.
-
-- The 3C regression tests are run regularly on Windows on Microsoft's
-  repository but not on CCI's. A change that breaks the regression
-  tests on Windows generally won't be made to Microsoft's repository,
-  but such a change could be made to CCI's and the problem may not be
-  detected until the next time CCI tries to merge to Microsoft (or a
-  user reports the problem to us). So you're less likely to encounter
-  Windows-specific problems with Microsoft's repository.
-
-- On the other hand, some CCI engineers work on Mac OS X and
-  frequently run the regression tests and other manual tests on CCI's
-  copy of 3C on Mac OS X, while we are unaware of any testing of
-  Microsoft's copy of 3C on Mac OS X. So you may be less likely to
-  encounter Mac-specific problems with CCI's repository. But so far,
-  when we've seen Mac-specific problems, we've usually gotten a fix
-  into Microsoft's repository reasonably quickly.
+establish its public presence and processes.
 
 As noted in the [setup instructions](INSTALL.md#basics), both 3C and
 the Checked C compiler depend on the Checked C system headers, which
 Microsoft maintains in [a subdirectory of a separate repository named
 `checkedc`](https://github.com/microsoft/checkedc/tree/master/include).
-CCI has [a fork of this
-repository](https://github.com/correctcomputation/checkedc), but
-currently it is used only for submitting changes to Microsoft. All
-users should use Microsoft's `checkedc` repository regardless of which
-`checkedc-clang` repository they use.