From 426926c151f11f595fd7fa5f75be7e59284a3252 Mon Sep 17 00:00:00 2001
From: David Malcolm <dmalcolm@redhat.com>
Date: Wed, 9 May 2018 10:56:09 -0400
Subject: [PATCH 22/83] FIXME: work on the blurb

---
 000-README.rst | 174 +--------------------------------------------------------
 1 file changed, 3 insertions(+), 171 deletions(-)

diff --git a/000-README.rst b/000-README.rst
index c4f74f9..038d364 100644
--- a/000-README.rst
+++ b/000-README.rst
@@ -1,184 +1,16 @@
-**********************
-Easier static analysis
-**********************
+**********************************************
+Compiler-assisted Performance Analysis for GCC
+**********************************************
 
 Summary
 =======
 
-This patch kit provides an easy way to make integrate 3rd-party static
-analysis tools into gcc, and have them report through gcc's diagnostic
-subsystem.
-
-Here's an example showing gcc running a bank of 3rd-party checkers on this
-source file::
-
-  #include <stdlib.h>
-
-  void test ()
-  {
-    void *ptr_1;
-    void *ptr_2;
-
-    ptr_1 = malloc (64);
-    if (!ptr_1)
-      return;
-    ptr_2 = malloc (64);
-    if (!ptr_2)
-      return;
-
-    free (ptr_2);
-    free (ptr_1);
-  }
-
-via a simple command-line:
-
-  $ ./xgcc -B. -c conditional-leak.c -frun-analyzers=policy.json
-  conditional-leak.c:13:5: error: Potential leak of memory pointed to by 'ptr_1' [clang-analyzer:Memory leak]
-       return;
-       ^
-  conditional-leak.c:8:11: note: state 1 of 4: Memory is allocated
-     ptr_1 = malloc (64);
-             ^
-  conditional-leak.c:9:7: note: state 2 of 4: Assuming 'ptr_1' is non-null
-     if (!ptr_1)
-         ^
-  conditional-leak.c:12:7: note: state 3 of 4: Assuming 'ptr_2' is null
-     if (!ptr_2)
-         ^
-  conditional-leak.c:13:5: note: state 4 of 4: Potential leak of memory pointed to by 'ptr_1'
-       return;
-       ^
-  conditional-leak.c:13:0: error: Memory leak: ptr_1 [cppcheck:memleak]
-       return;
-
-Of the checkers, clang's static analyzer and cppcheck both identify the
-memory leak; the former also identifies the control flow.
-
-Extensive metadata is captured about what checkers were run, and what
-they emitted, using the "Firehose" interchange format:
-
-  http://firehose.readthedocs.io/en/latest/index.html
-
-It should be easy to watermark the binaries with this information.
-
-
 Statement of the problem
 ========================
 
-Static analysis is done too late, if at all: static analysis tools are run
-as an optional extra, "on the side", rather than in developers' normal
-workflow.  Analysis results are reviewed (if at all) in some kind of
-on-the-side tool (e.g. Red Hat's internal errata tool, Fedora QA tooling, etc),
-rather than when the code is being edited, or patches being prepared.
-
-It would be better to have an easy way for developers to run analyzer(s)
-as they're doing development, as part of their edit-compile-test cycle
-- analysis problems are reported immediately, and can be acted on
-immediately.
-
-It would also be good to have a way to run analyzer(s) when packages are
-built, with a variety of precanned policies for analyzers.  For example,
-network-facing daemons could be run with a higher strictness of checking.
-
-It would also be good to tag binaries with information on what analyzers
-were run, what options they were invoked with, etc.
-Potentially have "dump_file" information from optimization passes stored
-in the metadata also.   Have a tool to query all of this.
-
-Can/should we break the build if there are issues?
-
-Yes: but have a way to opt-in easily: if the tool is well-integrated with the
-    compiler: e.g.
-        -frun-analyzers=/usr/share/analyzers/userspace/network-facing-service
-then upstream developers and packagers can turn on the setting, and see what
-breaks, and fix it naturally within an compile-edit-test cycle
-
-This gives a relatively painless way to opt-in to increasing levels of
-strictness (e.g. by an upstream project, or by an individual developer).
-
-Does this slow the build down?
-Yes: but you can choose which analyzers run, and can choose to turn them off.
-It ought to parallelize well.  I believe users will prefer to turn them on,
-and have Koji builders burn up the extra CPU cycles.
-This may make much more sense for binary distributions (e.g. Fedora, Debian)
-that it does for things like Gentoo.
-
-User stories:
-
-* upstream developer
-* distribution packager (Fedora, Debian, Gentoo)
-* RHEL packager
-* Fedora security team (setting policy etc)
-  * setting policy
-  * after a vulnerability, looking to assess the scope
-* RHEL security team
-  * setting policy
-  * after a vulnerability, looking to assess the scope
-
-Which analyzers?
-  * clang-analyzer
-  * cppcheck
-  * findbugs
-  * cpychecker???
-  * anything else?
-
-Look at Firehose:
-  https://github.com/fedora-static-analysis/firehose
-
-and look at mock-with-analysis:
-  https://github.com/fedora-static-analysis/mock-with-analysis
-
-Do we run the risk of breaking "configure" tests?
-
-UI ideas:
-
-A new option in GCC 8:
-  -frun-analyzers=PATH_TO_POLICY_FILE
-
-e.g.:
-
-  -frun-analyzers=/usr/share/analyzers/userspace/network-facing-service
-  -frun-analyzers=/usr/share/analyzers/userspace/application
-  -frun-analyzers=/usr/share/analyzers/userspace/default
-  -frun-analyzers=/usr/share/analyzers/kernel
-
-or whatnot.
-
-Idea is to provide mechanism, and for the distribution to decide on some standard policies.
-
-(mechanism vs policy)
-
-
-$ rpm -qf /usr/share/analyzers/userspace/network-facing-service
-analysis-policy-userspace-network-facing-service-0.1-1.noarch.fc27
-
-hence would have:
-
-  BuildRequires: analysis-policy-userspace-network-facing-service
-
-which would "Require" the analyzers themselves.
-
-See
-  https://fedoraproject.org/wiki/Toolchain/Watermark
-
-
-Ability to sandbox a gcc plugin by running the plugin inside another cc1.
-
-
 Known unknowns
 ==============
 
-How does one suppress a specific false-positive site?
-Do we need a pragma for it?  (though pragmas ought to already affect some of
-the underlying checkers...)
-
-Do we really want .json for the policy format?
-If we're expecting users to edit this, we need great error messages,
-and probably support for comments.  Would YAML or somesuch be better?
-
-Should the "checkers" subdirectory be its own project?
-
-
 Notes to self
 =============
 
-- 
1.8.5.3

