From 4936054c078466b404f5ce5e7a365bf862b326b5 Mon Sep 17 00:00:00 2001 From: souragc Date: Fri, 29 Sep 2023 21:26:07 +0000 Subject: [PATCH] Update documentation --- clang/docs/checkedc/3C/CONTRIBUTING.md | 171 +++++++++++++++++++------ clang/docs/checkedc/3C/INSTALL.md | 9 +- clang/docs/checkedc/3C/README.md | 95 +++----------- 3 files changed, 153 insertions(+), 122 deletions(-) diff --git a/clang/docs/checkedc/3C/CONTRIBUTING.md b/clang/docs/checkedc/3C/CONTRIBUTING.md index ab534c153dd2..9d807b30d144 100644 --- a/clang/docs/checkedc/3C/CONTRIBUTING.md +++ b/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. diff --git a/clang/docs/checkedc/3C/INSTALL.md b/clang/docs/checkedc/3C/INSTALL.md index 049a4bc2b678..0a2385288125 100644 --- a/clang/docs/checkedc/3C/INSTALL.md +++ b/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 diff --git a/clang/docs/checkedc/3C/README.md b/clang/docs/checkedc/3C/README.md index 03d1c690e22a..b331c41ae3e8 100644 --- a/clang/docs/checkedc/3C/README.md +++ b/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 info@correctcomputation.com. - -### 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.