From b7af834883b3b1a1ad593bacc0c8bb30d0b2f2f6 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Tue, 19 Mar 2024 14:08:54 -0700 Subject: [PATCH 1/7] Remove old documentation Signed-off-by: John Pennycook --- docs/configuration.md | 78 ------------------ docs/example-ast.png | Bin 15816 -> 0 bytes docs/example-dendrogram.png | Bin 15452 -> 0 bytes examples/README.md | 16 ---- examples/disjoint-source/README.md | 26 ------ examples/disjoint-source/cpu/main.cpp | 49 ----------- .../disjoint-source-dendrogram.png | Bin 11675 -> 0 bytes examples/disjoint-source/disjoint-source.yaml | 14 ---- examples/disjoint-source/gpu/main.cpp | 49 ----------- examples/disjoint-source/makefile | 10 --- examples/divergent-source/README.md | 28 ------- .../divergent-source-dendrogram.png | Bin 11259 -> 0 bytes .../divergent-source/divergent-source.yaml | 15 ---- examples/divergent-source/histogram.h | 8 -- examples/divergent-source/main.cpp | 47 ----------- examples/divergent-source/makefile | 10 --- .../divergent-source/private_histogram.cpp | 22 ----- .../divergent-source/shared_histogram.cpp | 18 ---- examples/single-source/README.md | 25 ------ examples/single-source/main.cpp | 56 ------------- examples/single-source/makefile | 7 -- .../single-source-dendrogram.png | Bin 10902 -> 0 bytes examples/single-source/single-source.yaml | 14 ---- 23 files changed, 492 deletions(-) delete mode 100644 docs/configuration.md delete mode 100755 docs/example-ast.png delete mode 100755 docs/example-dendrogram.png delete mode 100644 examples/README.md delete mode 100644 examples/disjoint-source/README.md delete mode 100644 examples/disjoint-source/cpu/main.cpp delete mode 100644 examples/disjoint-source/disjoint-source-dendrogram.png delete mode 100644 examples/disjoint-source/disjoint-source.yaml delete mode 100644 examples/disjoint-source/gpu/main.cpp delete mode 100644 examples/disjoint-source/makefile delete mode 100644 examples/divergent-source/README.md delete mode 100644 examples/divergent-source/divergent-source-dendrogram.png delete mode 100644 examples/divergent-source/divergent-source.yaml delete mode 100644 examples/divergent-source/histogram.h delete mode 100644 examples/divergent-source/main.cpp delete mode 100644 examples/divergent-source/makefile delete mode 100644 examples/divergent-source/private_histogram.cpp delete mode 100644 examples/divergent-source/shared_histogram.cpp delete mode 100644 examples/single-source/README.md delete mode 100644 examples/single-source/main.cpp delete mode 100644 examples/single-source/makefile delete mode 100644 examples/single-source/single-source-dendrogram.png delete mode 100644 examples/single-source/single-source.yaml diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index c320bb5..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,78 +0,0 @@ -Code Base Investigator Configuration File Format -================================================ - -Information about the type of analysis to be performed on a code base is communicated to Code Base Investigator through a configuration file expressed in YAML. This file contains information about what files should be analyzed, what platforms should be considered, and at least partial information about how the code is built on for each platform. What follows is a description of the configuration file format; users are also encouraged to consult the example configurations in the `examples/` directory. - -## YAML - -YAML is a markup language with similarities to JSON that is intended to be expressive and human readable/writable. The full details of the format are quite complex and can be found at [yaml.org](https://yaml.org/); only a subset of the full expressiveness of the format is required for Code Base Investigator. Here are the basics: - -- The format is plain text; in most cases, UTF-8 will be sufficient -- The line comment character is '#' -- YAML supports multiple 'documents' in a single stream (file), but Code Base Investigator will only load the first such document in any file. -- YAML has two main compound types: _sequences_, which express ordered relationships between values, and _mappings_, which express unordered key-value pairs. There are also numerous scalar types that YAML understands natively, including real numbers and strings. -- There are two main ways to express compound types: block-style, which rely on newlines and indentation, and 'inline', which relies on special delimiters and largely ignores whitespace. - Block-style sequences are indicated using `-` characters: - - - Item 1 - - Item 2 - - Item 3 - - Inline-style sequences are indicated using bracket delimiters `[`, `]` and comma separators: - - [ Item 1, Item 2, Item 3 ] - - Block-style mappings use the colon `:` to separate keys and values: - - key 1: item 1 - key 2: item 2 - key 3: item 3 - - Inline-style mapping use curly braces `{`, `}` and commas to enclose key-value pairs: - - { key 1: item 1, key 2: item 2, key 3: item 3 } - -## Code Base Investigator Configuration - -The configuration file is structured as a mapping at the top level. A single `codebase` key with associated mapping is required, and a key for each platform along with platform mappings should be provided. - -### Codebase Mapping - -A `codebase` key is required, which should contain a mapping containing: the key `files`, which is a sequence of file specifiers, and `platforms`, which is a sequence of user-defined names for platforms to be considered. - - codebase: - files: [ ,* ] - platforms: [ ,+ ] - exclude_files: [ ,* ] - -The `` is a string that specifies a (relative) path to files in the source tree. It can be a literal path to a file, or globs are supported (for Python 3.5 and later). The files are expanded with respect to the `--rootdir` specified on the commandline at invocation, or the default, which is the working directory where Code Base Investigator was invoked. If `files` is an empty list, CBI will determine the contents of the codebase automatically based on the files in the platform definition(s). - -`` can be any string; they are referred to by later platform definitions in the configuration file. - -The `exclude_files` entry is optional. If given, the contents (a list of `` file globs) will be excluded from all consideration by Code Base Investigator during processing. This is useful if the globs in `files` end up being overly inclusive in large projects. - -### Platform Mappings - -There should be a key for each platform that appears in the codebase platform sequence discussed above, and each such key should be accompanied by a mapping that describes the 'configuration': how the code base fed to a compiler for said platform. There are two supported methods: manual specification and compilation databases. - -#### Manual Platform Specification - -With manual specification, the mapping for a platform should contain a `files` key with a sequences of ``s, just as with the `codebase` mapping. The distinction is that the `files` for a platform may well be a subset of the whole set specified for the `codebase`. - -Additionally, the user may specify one each of the keys `defines` and `include_paths`, each with a sequence. `defines` is a sequence of C preprocessor symbols that should be applied when interpreting the `files` for this platform. They may be specified in the form `[-D][=]`; the optional `-D` prefix is permitted to emulate the command-line option setting of preprocessor directives found in gcc and other compilers. - -`include_paths` is used to specify (absolute) directory paths that should be included when processing `#include` directives in the source code. - -#### Compilation Database Platform Specification - -Compilation databases are simple markup files that contain information about how a compiler was invoked. They are typically named `compilation_commands.json` and are located in the build directories of projects. There are tools for generating compilation databases for most build systems: - -- CMake: add `-DCMAKE_EXPORT_COMPILE_COMMANDS` to the `cmake` invocation. -- Ninja: invoke `ninja` with `-t compdb`. -- Others: [Build EAR](https://github.com/rizsotto/Bear) - -To use a compilation database, specify the relative path in the value associated with a `commands` key under the platform mapping. Code Base Investigator will then load that compilation database and use its contents to define the configuration for that platform. - -#### Combining Manual Platform Specifications with Compilation Databases - -It is possible to combine the manual platform specification and the compilation database platform specification by specifying both the `commands` key along with some or all of the `files`/`defines`/`include_paths` used in manual specification; if either set of rules indicates that a source line belongs to the platform, the line will be associated with said platform. This is useful when the user wishes to expand the scope of what is associated with a platform beyond what a single compilation database contains. diff --git a/docs/example-ast.png b/docs/example-ast.png deleted file mode 100755 index ab6cdf02440f4b307bc0c969ef7e7247e602d87e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 15816 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�Qcp479` zoP0uHJz$M=h6c3TUOByBeRPbnWkC9diC*OGlRq(mk^JJ4u?fUYpnZ?CcJe@Cz%zfW z^ClL0A7~sBF5Z4aE#}(;)cYZpRB7Ph4fg;QUh70ujbEvt_5;NbeRQh-$s+ogS*^;s z1dL}jTU2^ASs1u_s?eX!`>{C!d3V|!8LaC=Ri08?((vg1wNRji4-2&LnJ^`})62XL z%_7-VHeF|jV<}W5EAsv6iJ_M{Q~V?8K{ouAqcdhqxuyI6kTrY5BG>}UHq7Ej-oqSt zH}!pu^>}wf4T_kLv^H3?yrNp3vj~~7-t-aw)-%g_b^EvB1?szzgXXwp6N{11o4dB( z-pS{s3%h#vu}*cXYYo%*TqSb?y@2>+?UOoR(6hC{z$Mkiv6+Dy_4|lYi5m|d3xogW z8-V&UU`qv3`KQf53yJ-5pI=B5ryNN=Gx3Rcw3|#07VWbNN>;cTKZpg=9UENMh<|=_ zGw%IhgN1+659x2#F=pF(<>vh-d8ch|JkqvWGo2$_U`x?KgXAAAsnE^EEBu&|(G$TP zsiM;^mJxf1@>=DIInb>ar0s<5=?^3YT>~1NZJrW(n4_C0)5V2E?E68T=(n*#UHB6) ZtXW!>^{81C=+FjfsO#JXAB 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 b`-dF!Zg?_3yPFRx4T6!neIxUl{^S1#x*J=Z diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 0ccd357..0000000 --- a/examples/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# Code Base Investigator Examples - -The examples in this directory consist of small, synthetic codebases constructed specifically to demonstrate the functionality of Code Base Investigator (CBI). - -Each example demonstrates how to configure CBI using YAML input files and compilation databases, and how to interpret the resulting code divergence metrics. - -## Links to Examples - -1. [single-source](single-source/README.md) - An example codebase using exactly the same code on multiple platforms. - -2. [divergent-source](divergent-source/README.md) - An example codebase specializing some small regions of code for individual platforms. - -3. [disjoint-source](disjoint-source/README.md) - An example codebase sharing no code across multiple platforms. diff --git a/examples/disjoint-source/README.md b/examples/disjoint-source/README.md deleted file mode 100644 index 816c895..0000000 --- a/examples/disjoint-source/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Disjoint Source Example - -An example codebase sharing no code across multiple platforms. - -## Output -``` ------------------------ -Platform Set LOC % LOC ------------------------ - {GPU} 37 48.68 - {CPU} 39 51.32 ------------------------ -Code Divergence: 1.00 -Unused Code (%): 0.00 -Total SLOC: 76 - -Distance Matrix --------------- - CPU GPU --------------- -CPU 0.00 1.00 -GPU 1.00 0.00 --------------- -``` - -![dendrogram](./disjoint-source-dendrogram.png) diff --git a/examples/disjoint-source/cpu/main.cpp b/examples/disjoint-source/cpu/main.cpp deleted file mode 100644 index 463532d..0000000 --- a/examples/disjoint-source/cpu/main.cpp +++ /dev/null @@ -1,49 +0,0 @@ -// Copyright (C) 2019 Intel Corporation -// SPDX-License-Identifier: BSD-3-Clause -#include -#include - -#include "histogram.h" - -int main(int argc, char* argv[]) -{ - int N = 1024; - int B = 16; - printf("Computing histogram of %d inputs and %d bins\n", N, B); - - int* input = (int*) malloc(N * sizeof(int)); - for (int i = 0; i < N; ++i) - { - input[i] = rand() % N; - } - - int* histogram = (int*) malloc(B * sizeof(int)); - for (int j = 0; j < B; ++j) - { - histogram[j] = 0; - } - - #pragma omp parallel for reduction(+:histogram[0:B]) - for (int i = 0; i < N; i += 16) - { - #pragma omp simd simdlen(16) - for (int v = 0; v < 16; ++v) - { - int b = (i + v) % B; - #pragma omp ordered simd overlap(b) - { - histogram[b]++; - } - } - } - - for (int j = 0; j < B; ++j) - { - printf("histogram[%d] = %d\n", j, histogram[j]); - } - - free(histogram); - free(input); - - return 0; -} diff --git a/examples/disjoint-source/disjoint-source-dendrogram.png b/examples/disjoint-source/disjoint-source-dendrogram.png deleted file mode 100644 index 6d03c8953864f4ebf1dd726bd0f52de0734e0c74..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11675 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 If}#Ka0R^OCy#N3J diff --git a/examples/disjoint-source/disjoint-source.yaml b/examples/disjoint-source/disjoint-source.yaml deleted file mode 100644 index 8596a00..0000000 --- a/examples/disjoint-source/disjoint-source.yaml +++ /dev/null @@ -1,14 +0,0 @@ -# Copyright (C) 2019 Intel Corporation -# SPDX-License-Identifier: BSD-3-Clause - -# Example configuration file for a disjoint codebase - -codebase: - files: [ "cpu/*.cpp", "gpu/*.cpp" ] - platforms: [ "CPU", "GPU" ] - -CPU: - files: [ "cpu/*.cpp" ] - -GPU: - files: [ "gpu/*.cpp" ] diff --git a/examples/disjoint-source/gpu/main.cpp b/examples/disjoint-source/gpu/main.cpp deleted file mode 100644 index e642d04..0000000 --- a/examples/disjoint-source/gpu/main.cpp +++ /dev/null @@ -1,49 +0,0 @@ -// Copyright (C) 2019 Intel Corporation -// SPDX-License-Identifier: BSD-3-Clause -#include -#include - -#include "histogram.h" - -int main(int argc, char* argv[]) -{ - int N = 1024; - int B = 16; - printf("Computing histogram of %d inputs and %d bins\n", N, B); - - int* input = (int*) malloc(N * sizeof(int)); - for (int i = 0; i < N; ++i) - { - input[i] = rand() % N; - } - - int* histogram = (int*) malloc(B * sizeof(int)); - for (int j = 0; j < B; ++j) - { - histogram[j] = 0; - } - - #pragma omp target enter data map(alloc:input[0:N], histogram[0:B]) - #pragma omp target update to(input[0:N], histogram[0:B]) - - #pragma omp target teams distribute parallel for simd - for (int i = 0; i < N; ++i) - { - int b = i % B; - #pragma omp atomic - histogram[b]++; - } - - #pragma omp target update from(histogram[0:B]) - #pragma omp target exit data map(delete:input[0:N], histogram[0:B]) - - for (int j = 0; j < B; ++j) - { - printf("histogram[%d] = %d\n", j, histogram[j]); - } - - free(histogram); - free(input); - - return 0; -} diff --git a/examples/disjoint-source/makefile b/examples/disjoint-source/makefile deleted file mode 100644 index ee4846d..0000000 --- a/examples/disjoint-source/makefile +++ /dev/null @@ -1,10 +0,0 @@ -all: histogram_cpu histogram_gpu - -histogram_cpu: makefile main.cpp - icpc -O3 -xHost -qopenmp -o histogram_cpu main.cpp private_histogram.cpp -qopenmp-offload=host -g - -histogram_gpu: makefile main.cpp - icpc -O3 -xHost -qopenmp -o histogram_gpu main.cpp shared_histogram.cpp -qopenmp-offload=host -g - -clean: - rm *.o histogram_cpu histogram_gpu diff --git a/examples/divergent-source/README.md b/examples/divergent-source/README.md deleted file mode 100644 index 816c846..0000000 --- a/examples/divergent-source/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Divergent Source Example - -An example codebase specializing some small regions of code for individual platforms. - -## Output -``` ------------------------ -Platform Set LOC % LOC ------------------------ - {} 1 1.39 - {GPU} 18 25.00 - {CPU} 18 25.00 - {CPU, GPU} 35 48.61 ------------------------ -Code Divergence: 0.51 -Unused Code (%): 1.39 -Total SLOC: 72 - -Distance Matrix --------------- - CPU GPU --------------- -CPU 0.00 0.51 -GPU 0.51 0.00 --------------- -``` - -![dendrogram](./divergent-source-dendrogram.png) diff --git a/examples/divergent-source/divergent-source-dendrogram.png b/examples/divergent-source/divergent-source-dendrogram.png deleted file mode 100644 index cbff1dc92f525a7e558dbe9aef7f21e39d0ebdc5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11259 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 -#include - -#include "histogram.h" - -int main(int argc, char* argv[]) -{ - int N = 1024; - int B = 16; - printf("Computing histogram of %d inputs and %d bins\n", N, B); - - int* input = (int*) malloc(N * sizeof(int)); - for (int i = 0; i < N; ++i) - { - input[i] = rand() % N; - } - - int* histogram = (int*) malloc(B * sizeof(int)); - for (int j = 0; j < B; ++j) - { - histogram[j] = 0; - } - -#ifdef USE_OFFLOAD - #pragma omp target enter data map(alloc:input[0:N], histogram[0:B]) - #pragma omp target update to(input[0:N], histogram[0:B]) -#endif - - compute_histogram(N, input, B, histogram); - -#ifdef USE_OFFLOAD - #pragma omp target update from(histogram[0:B]) - #pragma omp target exit data map(delete:input[0:N], histogram[0:B]) -#endif - - for (int j = 0; j < B; ++j) - { - printf("histogram[%d] = %d\n", j, histogram[j]); - } - - free(histogram); - free(input); - - return 0; -} diff --git a/examples/divergent-source/makefile b/examples/divergent-source/makefile deleted file mode 100644 index ee4846d..0000000 --- a/examples/divergent-source/makefile +++ /dev/null @@ -1,10 +0,0 @@ -all: histogram_cpu histogram_gpu - -histogram_cpu: makefile main.cpp - icpc -O3 -xHost -qopenmp -o histogram_cpu main.cpp private_histogram.cpp -qopenmp-offload=host -g - -histogram_gpu: makefile main.cpp - icpc -O3 -xHost -qopenmp -o histogram_gpu main.cpp shared_histogram.cpp -qopenmp-offload=host -g - -clean: - rm *.o histogram_cpu histogram_gpu diff --git a/examples/divergent-source/private_histogram.cpp b/examples/divergent-source/private_histogram.cpp deleted file mode 100644 index cc948d1..0000000 --- a/examples/divergent-source/private_histogram.cpp +++ /dev/null @@ -1,22 +0,0 @@ -// Copyright (C) 2019 Intel Corporation -// SPDX-License-Identifier: BSD-3-Clause -#include - -#include "histogram.h" - -void compute_histogram(int N, int* input, int B, int* histogram) -{ - #pragma omp parallel for reduction(+:histogram[0:B]) - for (int i = 0; i < N; i += 16) - { - #pragma omp simd simdlen(16) - for (int v = 0; v < 16; ++v) - { - int b = (i + v) % B; - #pragma omp ordered simd overlap(b) - { - histogram[b]++; - } - } - } -} diff --git a/examples/divergent-source/shared_histogram.cpp b/examples/divergent-source/shared_histogram.cpp deleted file mode 100644 index 741d5e4..0000000 --- a/examples/divergent-source/shared_histogram.cpp +++ /dev/null @@ -1,18 +0,0 @@ -// Copyright (C) 2019 Intel Corporation -// SPDX-License-Identifier: BSD-3-Clause -#include "histogram.h" - -void compute_histogram(int N, int* input, int B, int* histogram) -{ -#ifdef USE_OFFLOAD - #pragma omp target teams distribute parallel for simd -#else - #pragma omp parallel for simd -#endif - for (int i = 0; i < N; ++i) - { - int b = i % B; - #pragma omp atomic - histogram[b]++; - } -} diff --git a/examples/single-source/README.md b/examples/single-source/README.md deleted file mode 100644 index 50044cd..0000000 --- a/examples/single-source/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Single-Source Example - -An example codebase using exactly the same code on multiple platforms. - -## Output -``` ------------------------- -Platform Set LOC % LOC ------------------------- - {GPU, CPU} 43 100.00 ------------------------- -Code Divergence: 0.00 -Unused Code (%): 0.00 -Total SLOC: 43 - -Distance Matrix --------------- - GPU CPU --------------- -GPU 0.00 0.00 -CPU 0.00 0.00 --------------- -``` - -![dendrogram](./single-source-dendrogram.png) diff --git a/examples/single-source/main.cpp b/examples/single-source/main.cpp deleted file mode 100644 index ddde644..0000000 --- a/examples/single-source/main.cpp +++ /dev/null @@ -1,56 +0,0 @@ -// Copyright (C) 2019 Intel Corporation -// SPDX-License-Identifier: BSD-3-Clause -#include -#include - -int main(int argc, char* argv[]) -{ - if (argc != 2) - { - printf("Usage: histogram [use_offload]\n"); - return -1; - } - int use_offload = atoi(argv[1]); - - int N = 1024; - int B = 16; - printf("Computing histogram of %d inputs and %d bins\n", N, B); - printf("use_offload = %s\n", use_offload ? "true" : "false"); - - int* input = (int*) malloc(N * sizeof(int)); - for (int i = 0; i < N; ++i) - { - input[i] = rand() % N; - } - - int* histogram = (int*) malloc(B * sizeof(int)); - for (int j = 0; j < B; ++j) - { - histogram[j] = 0; - } - - #pragma omp target enter data map(alloc:input[0:N], histogram[0:B]) if (use_offload > 0) - #pragma omp target update to(input[0:N], histogram[0:B]) if (use_offload > 0) - - #pragma omp target teams distribute parallel for simd if (target: use_offload > 0) - for (int i = 0; i < N; ++i) - { - int b = i % B; - #pragma omp atomic - histogram[b]++; - } - - #pragma omp target update from(histogram[0:B]) if (use_offload > 0) - - #pragma omp target exit data map(delete:input[0:N], histogram[0:B]) if (use_offload > 0) - - for (int j = 0; j < B; ++j) - { - printf("histogram[%d] = %d\n", j, histogram[j]); - } - - free(histogram); - free(input); - - return 0; -} diff --git a/examples/single-source/makefile b/examples/single-source/makefile deleted file mode 100644 index 16c4bba..0000000 --- a/examples/single-source/makefile +++ /dev/null @@ -1,7 +0,0 @@ -all: histogram - -histogram: makefile main.cpp - icpc -O3 -xHost -qopenmp -o histogram main.cpp -qopenmp-offload=host -g - -clean: - rm *.o histogram diff --git a/examples/single-source/single-source-dendrogram.png b/examples/single-source/single-source-dendrogram.png deleted file mode 100644 index 4267166ee83862a88086e91ce95471fee640efda..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 10902 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 MtZ)f;QSbi$0KK58&j0`b diff --git a/examples/single-source/single-source.yaml b/examples/single-source/single-source.yaml deleted file mode 100644 index bc4a3f9..0000000 --- a/examples/single-source/single-source.yaml +++ /dev/null @@ -1,14 +0,0 @@ -# Copyright (C) 2019 Intel Corporation -# SPDX-License-Identifier: BSD-3-Clause - -# Example configuration file for a single-source codebase - -codebase: - files: [ "*.cpp" ] - platforms: [ "CPU", "GPU" ] - -CPU: - files: [ "*.cpp" ] - -GPU: - files: [ "*.cpp" ] From 6b1541fae76af4d503f60327add999c47d698f30 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Tue, 19 Mar 2024 14:13:00 -0700 Subject: [PATCH 2/7] Add Sphinx documentation The new documentation includes: - An introduction to Code Base Investigator - A worked tutorial with a sample code base - A reference page for codebasin Signed-off-by: John Pennycook --- docs/Makefile | 20 +++ docs/make.bat | 35 +++++ docs/sample-code-base/src/CMakeLists.txt | 18 +++ docs/sample-code-base/src/cpu/foo.cpp | 10 ++ docs/sample-code-base/src/gpu/foo.cpp | 10 ++ docs/sample-code-base/src/main.cpp | 16 +++ .../src/third-party/library.cpp | 8 ++ .../src/third-party/library.h | 3 + docs/source/analysis.rst | 110 +++++++++++++++ docs/source/cmd.rst | 42 ++++++ docs/source/compilation-databases.rst | 126 ++++++++++++++++++ docs/source/conf.py | 32 +++++ docs/source/emulating-compiler-behavior.rst | 125 +++++++++++++++++ docs/source/example-dendrogram.png | Bin 0 -> 15452 bytes docs/source/excluding-files.rst | 84 ++++++++++++ docs/source/features.rst | 77 +++++++++++ docs/source/index.rst | 120 +++++++++++++++++ docs/source/notices-and-disclaimers.rst | 17 +++ docs/source/sample-code-base.rst | 97 ++++++++++++++ docs/source/sample-code-base.zip | Bin 0 -> 3106 bytes docs/source/specialization-tree.png | Bin 0 -> 15816 bytes docs/source/specialization.rst | 83 ++++++++++++ 22 files changed, 1033 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/sample-code-base/src/CMakeLists.txt create mode 100644 docs/sample-code-base/src/cpu/foo.cpp create mode 100644 docs/sample-code-base/src/gpu/foo.cpp create mode 100644 docs/sample-code-base/src/main.cpp create mode 100644 docs/sample-code-base/src/third-party/library.cpp create mode 100644 docs/sample-code-base/src/third-party/library.h create mode 100644 docs/source/analysis.rst create mode 100644 docs/source/cmd.rst create mode 100644 docs/source/compilation-databases.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/emulating-compiler-behavior.rst create mode 100755 docs/source/example-dendrogram.png create mode 100644 docs/source/excluding-files.rst create mode 100644 docs/source/features.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/notices-and-disclaimers.rst create mode 100644 docs/source/sample-code-base.rst create mode 100644 docs/source/sample-code-base.zip create mode 100755 docs/source/specialization-tree.png create mode 100644 docs/source/specialization.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/sample-code-base/src/CMakeLists.txt b/docs/sample-code-base/src/CMakeLists.txt new file mode 100644 index 0000000..5218b12 --- /dev/null +++ b/docs/sample-code-base/src/CMakeLists.txt @@ -0,0 +1,18 @@ +# Copyright (c) 2024 Intel Corporation +# SPDX-License-Identifier: 0BSD +cmake_minimum_required(VERSION 3.5) +project(tutorial) + +set(SOURCES main.cpp third-party/library.cpp) + +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) + +option(GPU_OFFLOAD "Enable GPU offload." OFF) +if (GPU_OFFLOAD) + add_definitions("-D GPU_OFFLOAD=1") + list(APPEND SOURCES gpu/foo.cpp) +else() + list(APPEND SOURCES cpu/foo.cpp) +endif() + +add_executable(tutorial ${SOURCES}) diff --git a/docs/sample-code-base/src/cpu/foo.cpp b/docs/sample-code-base/src/cpu/foo.cpp new file mode 100644 index 0000000..3ba6f5a --- /dev/null +++ b/docs/sample-code-base/src/cpu/foo.cpp @@ -0,0 +1,10 @@ +// Copyright (c) 2024 Intel Corporation +// SPDX-License-Identifier: 0BSD +#include + +void foo() { +#if __GNUC__ >= 13 + printf("Using a feature that is only available in GCC 13 and later.\n"); +#endif + printf("Running the rest of foo() on the CPU.\n"); +} diff --git a/docs/sample-code-base/src/gpu/foo.cpp b/docs/sample-code-base/src/gpu/foo.cpp new file mode 100644 index 0000000..2b1538c --- /dev/null +++ b/docs/sample-code-base/src/gpu/foo.cpp @@ -0,0 +1,10 @@ +// Copyright (c) 2024 Intel Corporation +// SPDX-License-Identifier: 0BSD +#include + +void foo() { +#if __GNUC__ >= 13 + printf("Using a feature that is only available in GCC 13 and later.\n"); +#endif + printf("Running the rest of foo() on the GPU.\n"); +} diff --git a/docs/sample-code-base/src/main.cpp b/docs/sample-code-base/src/main.cpp new file mode 100644 index 0000000..891ccf0 --- /dev/null +++ b/docs/sample-code-base/src/main.cpp @@ -0,0 +1,16 @@ +// Copyright (c) 2024 Intel Corporation +// SPDX-License-Identifier: 0BSD +#include +#include "third-party/library.h" +void foo(); + +int main(int argc, char* argv[]) +{ +#if !defined(GPU_OFFLOAD) + printf("Running on the CPU.\n"); +#else + printf("Running on the GPU.\n"); +#endif + foo(); + bar(); +} diff --git a/docs/sample-code-base/src/third-party/library.cpp b/docs/sample-code-base/src/third-party/library.cpp new file mode 100644 index 0000000..7d2cb9b --- /dev/null +++ b/docs/sample-code-base/src/third-party/library.cpp @@ -0,0 +1,8 @@ +// Copyright (c) 2024 Intel Corporation +// SPDX-License-Identifier: 0BSD +#include + +void bar() +{ + printf("Running third-party library code.\n"); +} diff --git a/docs/sample-code-base/src/third-party/library.h b/docs/sample-code-base/src/third-party/library.h new file mode 100644 index 0000000..7671637 --- /dev/null +++ b/docs/sample-code-base/src/third-party/library.h @@ -0,0 +1,3 @@ +// Copyright (c) 2024 Intel Corporation +// SPDX-License-Identifier: 0BSD +void bar(); diff --git a/docs/source/analysis.rst b/docs/source/analysis.rst new file mode 100644 index 0000000..4ee15fe --- /dev/null +++ b/docs/source/analysis.rst @@ -0,0 +1,110 @@ +Performing Analysis +=================== + +The main interface of CBI is the ``codebasin`` script, which can be invoked to +analyze a code base and produce various reports. Although CBI ships with other +interfaces specialized for certain use-cases, ``codebasin`` supports an +end-to-end workflow that should be preferred for general usage. + +The simplest way to invoke ``codebasin`` is as shown below:: + + $ codebasin analysis.toml + +...but what is ``analysis.toml``? We need to use this file to tell CBI which +files are part of the code base, and where it should look to find the +compilation databases defining our platforms. + +.. note:: + + The TOML file can have any name, but we'll use "analysis.toml" throughout + this tutorial. + + +Defining Platforms +################## + +Each platform definition is a TOML `table`_, of the form shown below: + +.. _`table`: https://toml.io/en/v1.0.0#table + +.. code-block:: toml + + [platform.name] + commands = "/path/to/compile_commands.json" + +The table's name is the name of the platform, and we can use any meaningful +string. The ``commands`` key tells CBI where to find the compilation database +for this platform. + +In our example, we have two platforms that we're calling "cpu" and "gpu", +and our build directories are called ``build-cpu`` and ``build-gpu``, so +our platform definitions should look like this: + +.. code-block:: toml + + [platform.cpu] + commands = "build-cpu/compile_commands.json" + + [platform.gpu] + commands = "build-gpu/compile_commands.json" + +.. warning:: + Platform names are case sensitive! The names "cpu" and "CPU" would refer to + two different platforms. + + +Running ``codebasin`` +##################### + +Running ``codebasin`` with this analysis file gives the following output: + +.. code-block:: text + :emphasize-lines: 4,5,6,7,9 + + ----------------------- + Platform Set LOC % LOC + ----------------------- + {} 2 6.06 + {cpu} 7 21.21 + {gpu} 7 21.21 + {cpu, gpu} 17 51.52 + ----------------------- + Code Divergence: 0.45 + Unused Code (%): 6.06 + Total SLOC: 33 + + Distance Matrix + -------------- + cpu gpu + -------------- + cpu 0.00 0.45 + gpu 0.45 0.00 + +The results show that there are 2 lines of code that are unused by any +platform, 7 lines of code used only by the CPU compilation, 7 lines of code +used only by the GPU compilation, and 17 lines of code shared by both +platforms. Plugging these numbers into the equation for code divergence gives +0.45. + + +Filtering Platforms +################### + +When working with an application that supports lots of platforms, we may want +to limit the analysis to a subset of the platforms defined in the analysis +file. + +Rather than require a separate analysis file for each possible subset, we can +use the :code:`--platform` flag (or :code:`-p` flag) to specify the subset of +interest on the command line: + +.. code:: sh + + $ codebasin -p [PLATFORM 1] -p [PLATFORM 2] analysis.toml + +For example, we can limit the analysis of our sample code base to the cpu +platform as follows: + +.. code:: sh + + $ codebasin -p cpu analysis.toml diff --git a/docs/source/cmd.rst b/docs/source/cmd.rst new file mode 100644 index 0000000..8e92bee --- /dev/null +++ b/docs/source/cmd.rst @@ -0,0 +1,42 @@ +Command Line Interface +====================== + +.. code-block:: text + + codebasin [-h] [--version] [-v] [-q] [-R ] [-x ] [-p ] [] + +**positional arguments:** + +``analysis-file`` + TOML file describing the analysis to be performed, + including the codebase and platform descriptions. + +**options:** + +``-h, --help`` + Show help message and exit. + +``--version`` + Display version information and exit. + +``-v, --verbose`` + Increase verbosity level. + +``-q, --quiet`` + Decrease verbosity level. + +``-R `` + Generate a report of the specified type. + + - ``summary``: output only code divergence information. + - ``clustering``: output only distance matrix and dendrogram. + - ``all``: generate both summary and clustering reports. + +``-x , --exclude `` + Exclude files matching this pattern from the code base. + May be specified multiple times. + +``-p , --platform `` + Include the specified platform in the analysis. + May be specified multiple times. + If not specified, all platforms will be included. diff --git a/docs/source/compilation-databases.rst b/docs/source/compilation-databases.rst new file mode 100644 index 0000000..08b1fca --- /dev/null +++ b/docs/source/compilation-databases.rst @@ -0,0 +1,126 @@ +Compilation Databases +===================== + +Before it can analyze a code base, CBI needs to know how each source file is +compiled. Just like a compiler, CBI requires a full list of include paths, +macro definitions and other options in order to identify which code is used +by each platform. Rather than require all of this information to be specified +manually, CBI reads it from a `compilation database`_. + + +Generating a Compilation Database +################################# + +Since our sample code base is already set up with a ``CMakeLists.txt`` file, we +can ask CMake to generate the compilation database for us with the +:code:`CMAKE_EXPORT_COMPILE_COMMANDS` option: + +.. code-block:: cmake + :emphasize-lines: 4 + + cmake_minimum_required(VERSION 3.5) + project(tutorial) + + set(CMAKE_EXPORT_COMPILE_COMMANDS ON) + + set(SOURCES main.cpp third-party/library.cpp) + + option(GPU_OFFLOAD "Enable GPU offload." OFF) + if (GPU_OFFLOAD) + add_definitions("-D GPU_OFFLOAD=1") + list(APPEND SOURCES gpu/foo.cpp) + else() + list(APPEND SOURCES cpu/foo.cpp) + endif() + + add_executable(tutorial ${SOURCES}) + +.. important:: + For projects that don't use CMake, we can use `Bear`_ to intercept the + commands generated by other build systems (such as GNU makefiles). Other + build systems and tools that produce compilation databases should also be + compatible. + +.. _`compilation database`: https://clang.llvm.org/docs/JSONCompilationDatabase.html +.. _`Bear`: https://github.com/rizsotto/Bear + + +CPU Compilation Commands +------------------------ + +Let's start by running CMake without the :code:`GPU_OFFLOAD` option enabled, to +obtain a compilation database for the CPU: + +.. code :: sh + + $ mkdir build-cpu + $ cmake ../ + $ ls + + CMakeCache.txt CMakeFiles Makefile cmake_install.cmake compile_commands.json + +This :code:`compile_commands.json` file includes all the commands required to +build the code, corresponding to the commands that would be executed if we were +to actually run :code:`make`. + +.. attention:: + CMake generates compilation databases when the ``cmake`` command is + executed, allowing us to generate compilation databases without also + building the application. Other tools (like Bear) may require a build. + +In this case, it contains:: + + [ + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/main.cpp.o -c /home/username/src/main.cpp", + "file": "/home/username/src/main.cpp" + }, + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/third-party/library.cpp.o -c /home/username/src/third-party/library.cpp", + "file": "/home/username/src/third-party/library.cpp" + }, + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/cpu/foo.cpp.o -c /home/username/src/cpu/foo.cpp", + "file": "/home/username/src/cpu/foo.cpp" + } + ] + + +GPU Compilation Commands +------------------------ + +Repeating the exercise with :code:`GPU_OFFLOAD` enabled gives us a different +compilation database for the GPU. + +.. warning:: + The ``GPU_OFFLOAD`` option is specific to this ``CMakeLists.txt`` file, and + isn't something provided by CMake. Understanding how to build an application + for a specific target platform is beyond the scope of this tutorial. + +As expected, we can see that the compilation database refers to ``gpu.cpp`` +instead of ``cpu.cpp``, and that the ``GPU_OFFLOAD`` macro is defined as part +of each compilation command:: + + [ + { + "directory": "/home/username/src/build-gpu", + "command": "/usr/bin/c++ -D GPU_OFFLOAD=1 -o CMakeFiles/tutorial.dir/main.cpp.o -c /home/username/src/main.cpp", + "file": "/home/username/src/main.cpp" + }, + { + "directory": "/home/username/src/build-gpu", + "command": "/usr/bin/c++ -D GPU_OFFLOAD=1 -o CMakeFiles/tutorial.dir/third-party/library.cpp.o -c /home/username/src/third-party/library.cpp", + "file": "/home/username/src/third-party/library.cpp" + }, + { + "directory": "/home/username/src/build-gpu", + "command": "/usr/bin/c++ -D GPU_OFFLOAD=1 -o CMakeFiles/tutorial.dir/gpu/foo.cpp.o -c /home/username/src/gpu/foo.cpp", + "file": "/home/username/src/gpu/foo.cpp" + } + ] + +These differences are the result of code divergence. We'll explore how to use +``codebasin`` to measure the *amount* of code divergence in a later tutorial. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..65dd978 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,32 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "Code Base Investigator" +copyright = ( + " Intel Corporation. Intel, the Intel logo, and other Intel marks are " + + "trademarks of Intel Corporation or its subsidiaries. Other names and " + + "brands may be claimed as the property of others." +) +author = "Intel Corporation" +version = "1.2.0" +release = "1.2.0" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.mathjax"] + +templates_path = ["_templates"] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] +html_title = "Code Base Investigator" diff --git a/docs/source/emulating-compiler-behavior.rst b/docs/source/emulating-compiler-behavior.rst new file mode 100644 index 0000000..24e81c7 --- /dev/null +++ b/docs/source/emulating-compiler-behavior.rst @@ -0,0 +1,125 @@ +Emulating Compiler Behavior +=========================== + +When CBI processes a file, it tries to obey all of the arguments that it can +see in the compilation database. Unfortunately, compilers often have behaviors +that are not reflected on the command line (such as their default include +paths, or compiler version macros). + +If we believe (or already know!) that these behaviors will impact the +divergence calculation for a code base, we can use a configuration file to +instruct CBI to append additional options when emulating certain compilers. + +.. attention:: + + If you encounter a situation that is not supported by CBI and which cannot + be described by our existing configuration files, please `open an issue`_. + +.. _`open an issue`: https://github.com/intel/code-base-investigator/issues/new/choose + + +Motivating Example +------------------ + +The ``foo.cpp`` files in our sample code base include specialization that we +have ignored so far, which selects a line based on the value of the +:code:`__GNUC__` preprocessor macro: + +.. code-block:: cpp + :linenos: + :emphasize-lines: 6 + + // Copyright (c) 2024 Intel Corporation + // SPDX-License-Identifier: 0BSD + #include + + void foo() { + #if __GNUC__ >= 13 + printf("Using a feature that is only available in GCC 13 and later.\n"); + #else + printf("Running the rest of foo() on the CPU.\n"); + #endif + } + +This macro is defined automatically by all GNU compilers and is set based on +the compiler's major version. For example, ``gcc`` version 13.0.0 would set +:code:`__GNUC__` to 13. Checking the values of macros like this one can be +useful when specializing code paths to workaround bugs in specific compilers, +or when specializing code paths to make use of functionality that is only +available in newer compiler versions. + +Let's take another look at the compilation database entry for this file: + +.. code-block:: json + :emphasize-lines: 14 + + [ + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/main.cpp.o -c /home/username/src/main.cpp", + "file": "/home/username/src/main.cpp" + }, + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/third-party/library.cpp.o -c /home/username/src/third-party/library.cpp", + "file": "/home/username/src/third-party/library.cpp" + }, + { + "directory": "/home/username/src/build-cpu", + "command": "/usr/bin/c++ -o CMakeFiles/tutorial.dir/cpu/foo.cpp.o -c /home/username/src/cpu/foo.cpp", + "file": "/home/username/src/cpu/foo.cpp" + } + ] + +CBI can see that the compiler used for ``foo.cpp`` is called ``/usr/bin/c++``, +but there is not enough information to decide what the value of +:code:`__GNUC__` should be. + + +Defining Behaviors +------------------ + +``codebasin`` searches for a file called ``.cbi/config``, and uses the +information found in that file to determine implicit compiler behavior. Each +compiler definition is a TOML `table`_, of the form shown below: + +.. _`table`: https://toml.io/en/v1.0.0#table + +.. code:: toml + + [compiler.name] + options = [ + "option", + "option" + ] + +In our example, we would like to define :code:`__GNUC__` for the ``c++`` +compiler, so we can add the following compiler definition: + +.. code:: toml + + [compiler."c++"] + options = [ + "-D__GNUC__=13", + ] + +.. important:: + The quotes around "c++" are necessary because of the + symbols. The quotes + would not be necessary for other compilers. + +With the :code:`__GNUC__` macro set, the two lines of code that were previously +considered "unused" are assigned to platforms, and the output of ``codebasin`` +becomes: + +.. code:: text + + ----------------------- + Platform Set LOC % LOC + ----------------------- + {cpu} 8 29.63 + {gpu} 8 29.63 + {cpu, gpu} 11 40.74 + ----------------------- + Code Divergence: 0.59 + Unused Code (%): 0.00 + Total SLOC: 27 diff --git a/docs/source/example-dendrogram.png b/docs/source/example-dendrogram.png new file mode 100755 index 0000000000000000000000000000000000000000..0ea3c2333586dc439c0741ac36a85ec2c42ea188 GIT binary patch literal 15452 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 b`-dF!Zg?_3yPFRx4T6!neIxUl{^S1#x*J=Z literal 0 HcmV?d00001 diff --git a/docs/source/excluding-files.rst b/docs/source/excluding-files.rst new file mode 100644 index 0000000..d84775a --- /dev/null +++ b/docs/source/excluding-files.rst @@ -0,0 +1,84 @@ +Excluding Files +=============== + +By default, CBI will process any file that it encounters in a compilation +database (including :code:`#include` files). The lines of code in these files +will be included in the code divergence calculation unless: + +- The file exists outside of the directory where ``codebasin`` is run. +- The file is explicitly excluded from the analysis. + + +Using the Analysis File +####################### + +Files can be explicitly excluded from an analysis by adding an :code:`exclude` +key to the :code:`codebase` section of the TOML file. Each entry in the exclude +list is a pattern to match files against: + +.. code-block:: toml + + [codebase] + exclude = [ + "pattern", + "pattern" + ] + +.. note:: + + Each pattern is a "pathspec", matching the format used by git. For more + information, see the `git glossary`_. + +.. _`git glossary`: https://git-scm.com/docs/gitglossary + + +For example, we can use this section to instruct CBI to ignore all files in the +``third-party/`` subdirectory, allowing us to focus on our own code: + +.. code-block:: toml + + [codebase] + exclude = [ + "third-party/" + ] + +Using this new analysis file, the output of ``codebasin`` shows fewer lines +shared between the cpu and gpu platforms: + + +.. code-block:: text + :emphasize-lines: 7 + + ----------------------- + Platform Set LOC % LOC + ----------------------- + {} 2 7.41 + {cpu} 7 25.93 + {gpu} 7 25.93 + {cpu, gpu} 11 40.74 + ----------------------- + Code Divergence: 0.56 + Unused Code (%): 7.41 + Total SLOC: 27 + + +Using the Command Line +###################### + +It is also possible to exclude files directly from the command line, using the +:code:`--exclude` flag (or :code:`-x` flag). + +The flag expects exclude patterns to be specified the same way as the TOML +file. To ignore all files in the ``third-party/`` subdirectory as we did +before, we can simply run: + +.. code:: sh + + $ codebasin -x "third-party/" analysis.toml + +.. tip:: + + If a file should *always* be excluded, it's better to specify that in the + analysis file. The command line approach is best suited to evaluate "what + if" scenarios, like "what if I excluded all files with a specific + extension?" (e.g., ``-x "*.cu"``). diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..8945c47 --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,77 @@ +Key Features +============ + +Identifying Specialization +########################## + +CBI is currently limited to identifying two forms of specialization: + +1) Different source files are compiled for different platforms; +2) Lines of code within source files are guarded by C preprocessor macros. + +Although limited, this functionality is sufficient to support analysis of many +HPC codes, and CBI has been tested on C, C++, CUDA and some Fortran code bases. + + +Computing Code Divergence +######################### + +CBI computes code divergence by building a *specialization tree*, like the one +shown below: + +.. image:: specialization-tree.png + :alt: An example of a specialization tree. + +CBI can then walk and evaluate this tree for different platform definitions, to +produce a divergence report providing a breakdown of how many lines of code +are shared between different platform sets. + +.. code:: text + + --------------------------------------------- + Platform Set LOC % LOC + --------------------------------------------- + {} 2 4.88 + {GPU 1} 1 2.44 + {GPU 2} 1 2.44 + {CPU 2} 1 2.44 + {CPU 1} 1 2.44 + {FPGA} 14 34.15 + {GPU 2, GPU 1} 6 14.63 + {CPU 1, CPU 2} 6 14.63 + {FPGA, CPU 1, GPU 2, GPU 1, CPU 2} 9 21.95 + --------------------------------------------- + Code Divergence: 0.55 + Unused Code (%): 4.88 + Total SLOC: 41 + +Future releases of CBI will provide additional ways to visualize the results of +this analysis, in order to highlight exactly *which* lines of code correspond +to different platform sets. + + +Hierarchical Clustering +####################### + +Since code divergence is constructed from pair-wise distances, CBI can also +produce a pair-wise distance matrix, showing the ratio of platform-specific +code to code used by both platforms. + +.. code:: text + + Distance Matrix + ----------------------------------- + FPGA CPU 1 GPU 2 GPU 1 CPU 2 + ----------------------------------- + FPGA 0.00 0.70 0.70 0.70 0.70 + CPU 1 0.70 0.00 0.61 0.61 0.12 + GPU 2 0.70 0.61 0.00 0.12 0.61 + GPU 1 0.70 0.61 0.12 0.00 0.61 + CPU 2 0.70 0.12 0.61 0.61 0.00 + ----------------------------------- + +These distances can also be used to produce a dendrogram, showing the result of +hierarchical clustering by platform similarity. + +.. image:: example-dendrogram.png + :alt: A dendrogram representing the distance between platforms. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..e791b18 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,120 @@ +Code Base Investigator +====================== + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Introduction + + Getting Started + specialization + features + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Tutorial + + sample-code-base + compilation-databases + analysis + excluding-files + emulating-compiler-behavior + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Reference + + cmd + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Contributing + + How to Contribute + GitHub + notices-and-disclaimers + + +Code Base Investigator (CBI) is an analysis tool that provides insight into the +portability and maintainability of an application's source code. + +- Measure ":doc:`code divergence `" to understand how much code + is *specialized* for different compilers, operating systems, hardware + micro-architectures and more. + +- Visualize the distance between the code paths used to support different + compilation targets. + +- Identify stale, legacy, code paths that are unused by any compilation target. + +- Export metrics and code path information required for P3 analysis using + `other tools`_. + +.. _other tools: https://intel.github.io/p3-analysis-library/index.html + + +Installation +############ + +The latest release of CBI is version 1.2.0. To download and install this +release, run the following:: + + $ git clone --branch 1.2.0 https://github.com/intel/code-base-investigator.git + $ cd code-base-investigator + $ pip install . + +We strongly recommend installing CBI within a `virtual environment`_. + +.. _`virtual environment`: https://docs.python.org/3/library/venv.html + + +Getting Started +############### + +Using CBI to analyze a code base is a three step process. For more detailed +information on any of these steps, we recommend that you work through the +tutorial using the :doc:`sample code base`. + + +1. **Generate a compilation database for each platform** + + You can use the |CMAKE_EXPORT_COMPILE_COMMANDS option|_ with `CMake`_, + intercept the compilation of an application using `Bear`_, or write a + database manually. + + .. _`CMake`: https://cmake.org/ + .. _`Bear`: https://github.com/rizsotto/Bear + +.. |CMAKE_EXPORT_COMPILE_COMMANDS option| replace:: :code:`CMAKE_EXPORT_COMPILE_COMMANDS` option +.. _CMAKE_EXPORT_COMPILE_COMMANDS option: https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html + + +2. **Create a TOML file describing the analysis** + + CBI reads platform definitions from a `TOML`_ file, like the one shown + below: + + .. code:: toml + + [platform.cpu] + commands = "cpu/compile_commands.json" + + [platform.gpu] + commands = "gpu/compile_commands.json" + + .. _`TOML`: https://toml.io/en/ + + +3. **Launch CBI** + + To perform a full analysis, launch ``codebasin`` with no arguments except + the input TOML file: + + .. code:: text + + $ codebasin analysis.toml + + To see the other options that are available, run ``codebasin -h``. diff --git a/docs/source/notices-and-disclaimers.rst b/docs/source/notices-and-disclaimers.rst new file mode 100644 index 0000000..867c66f --- /dev/null +++ b/docs/source/notices-and-disclaimers.rst @@ -0,0 +1,17 @@ +Notices and Disclaimers +####################### + +© Intel Corporation. Intel, the Intel logo, and other Intel marks are +trademarks of Intel Corporation or its subsidiaries. Other names and brands may +be claimed as the property of others. + +No license (express or implied, by estoppel or otherwise) to any intellectual +property rights is granted by this document, with the sole exception that code +included in this document is licensed subject to the Zero-Clause BSD open +source license (OBSD), http://opensource.org/licenses/0BSD. + +License +======= + +Code Base Investigator (CBI) is licensed under the BSD-3-Clause License, and +made available at http://github.com/intel/code-base-investigator/. diff --git a/docs/source/sample-code-base.rst b/docs/source/sample-code-base.rst new file mode 100644 index 0000000..f53acbc --- /dev/null +++ b/docs/source/sample-code-base.rst @@ -0,0 +1,97 @@ +Sample Code Base +================ + +This tutorial uses a sample code base designed to showcase the features of CBI. + +.. attention:: + + To follow along with the tutorial, we first need a copy of the sample code + base. + + It can be downloaded from :download:`here` or copied + from the ``docs/source/sample-code-base`` directory `on GitHub`_. + +.. _on GitHub: https://github.com/intel/code-base-investigator/tree/main/docs/sample-code-base/ + + +Directory Structure +------------------- + +The sample code base consists of just a few source files, arranged as shown +below:: + + src/ + ├── CMakeLists.txt + ├── cpu + │   └── foo.cpp + ├── gpu + │   └── foo.cpp + ├── main.cpp + └── third-party + ├── library.cpp + └── library.h + + +Although simple, this structure is representative of many applications that +target multiple platforms. The code base contains: + +- A directory (``src``) containing all of the source files required to build + the application. + +- Two subdirectories (``cpu`` and ``gpu``) containing source files that are + only used when building the application to target specific platforms. + +- Some shared source files (``main.cpp``) that are always used when building + the application to target any platform. + +- Some third-party source files (``third-party/library.h`` and + ``third-party/library.cpp``). + +.. tip:: + Generally speaking, "third party source files" just means "source files + maintained by somebody else". Even if we're working with a code base + without any external dependencies, treating code written by other + developers or other teams as "third party source files" will allow us to + limit our analysis to source files that we care about. + + +File Structure +-------------- + +Let's take a look at one of the files in the code base, ``main.cpp``: + +.. code-block:: cpp + :linenos: + :emphasize-lines: 10,12 + + // Copyright (c) 2024 Intel Corporation + // SPDX-License-Identifier: 0BSD + #include + #include "third-party/library.h" + void foo(); + + int main(int argc, char* argv[]) + { + #if !defined(GPU_OFFLOAD) + printf("Running on the CPU.\n"); + #else + printf("Running on the GPU.\n"); + #endif + foo(); + bar(); + } + +The preprocessor directives on Lines 9, 11 and 12 (:code:`#if`, :code:`#else` +and :code:`#endif`) define a specialization point, allowing Lines 10 and 12 +to be specialized based on the value of a preprocessor macro +(:code:`GPU_OFFLOAD`). This approach is common in many C, C++ and Fortran +applications. + +Lines 3, 4 and 5 also define potential specialization points, because the +compilation commands targeting different platforms may search different +include paths and/or link against different libraries. + +.. note:: + + Although this file contains 16 lines of *text*, CBI will count only 13 + lines of *code*. Comments and whitespace do not count. diff --git a/docs/source/sample-code-base.zip b/docs/source/sample-code-base.zip new file mode 100644 index 0000000000000000000000000000000000000000..d1c9cee97fe6d5a44d44acd4b8e1284bfb9f4535 GIT binary patch literal 3106 zcmWIWW@h1H0D%=*IT2t6ln`Z*VJJ?_EyzjLP0mkA)lEt)PSr0iO4bhz;bdU8-uWTb z28c^5xEUB(UNAE-fQbO0aUwtiI2Zzf#+5wFpQXphz_1gDm2ny8?3XTVqQmj`} zQ35u6=8g}kpMV(6@X`qf{hA#F+TQ;b5q_0udEweBabbRrD+199M`ztTF-`VX=#ALv zsv8Y!%N5rylbdr|<#WC9=kq-Z0lyNCt?lb9Bejqr1d=!rCGisz^G{Yn9Gd z^qQhuW$2#is(Rth;V*{#o;Np?>qsfOUN&t#*zYIt7*)sV;H#{#>$`YmtnU+LIkuq~63yyvs~`lNi*!Hu0IkmGc!FzRX{&bSvfMtEC*5 zQpNNaDeC`KIiu)X<@55OaqX#Vu2%E)gX~$^{pm$2E%TkrcFhj)nroAMSLyG3-TxaVb+2ka zxk1)`8rM7i$sD}w$zi$6wz#aICxI(HVBeN()w;-{oq!JMcY}g|K z5wC|#)&_+FBLRf9h%q`RGpQ)Cs8TNj9vxWh(AQUR&M&Ae%1qBFQP4=%R4_6yGEwl% zD@n}(N)#337bTWt=I3z%)ddH*MCkftCa2~Vr|Np9q~?`mre&rUSt%Ge1-o#Ss`vZ_>Vs=rhdskc-yNWQ#v=R^`a8r6-FM)!qfN z3(fZrD>*tbYU8Fw-F9#8&q-1LaZn!B&(n(kzkLAouPHFc$l~&IZenI0N_P2ySrXRv z1$rNL;5mN(eejWYOGS70J)GRNKwG-`U{|ujiW6`3u5(|B@yu^lsw%sJ{|9(ZsEIHgBp@--m^rmj$<6dB)Xq zy~y&@%cr`*^A9_+i;Kw`-YN-wdw=`sr)j?f(zx2PQg4)Gekw^(Tc>E?(!XKFx69#v zZQ{Z?R)73s{|4Ti^t-VBb8p23qes(!vEj}>ILoedymBl%LKTTjtYGU;K=@#`#GUf+DyMy>0kNc zFOOu>f7mV42srj{){i@yo6L@9?W{TyH|3DY5<9ikGDk&N``Ygwe>63EQlnV4`=U29 zF9}b({rKFO$XfXyHh}~%&_F=7k|3ADfFuL5A8rBd!|De}U5L+kgg;PgLS%pF zGT|{Ep0@DWg548}D4qxhHovfX0<}&d&KlGj1=%y3h_ME#e!*uSBJfZv0%ZHLS%~l! z%sz0nK%9-J#W1ps@vJy(L=?*StiT>us0nTw8xAWV1sFc#5n+Z}d?EYbB|hT`COB50 RZUzP}Ap8Z4YatF04*;et7Lot} literal 0 HcmV?d00001 diff --git a/docs/source/specialization-tree.png b/docs/source/specialization-tree.png new file mode 100755 index 0000000000000000000000000000000000000000..ab6cdf02440f4b307bc0c969ef7e7247e602d87e GIT binary patch literal 15816 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�Qcp479` zoP0uHJz$M=h6c3TUOByBeRPbnWkC9diC*OGlRq(mk^JJ4u?fUYpnZ?CcJe@Cz%zfW z^ClL0A7~sBF5Z4aE#}(;)cYZpRB7Ph4fg;QUh70ujbEvt_5;NbeRQh-$s+ogS*^;s z1dL}jTU2^ASs1u_s?eX!`>{C!d3V|!8LaC=Ri08?((vg1wNRji4-2&LnJ^`})62XL z%_7-VHeF|jV<}W5EAsv6iJ_M{Q~V?8K{ouAqcdhqxuyI6kTrY5BG>}UHq7Ej-oqSt zH}!pu^>}wf4T_kLv^H3?yrNp3vj~~7-t-aw)-%g_b^EvB1?szzgXXwp6N{11o4dB( z-pS{s3%h#vu}*cXYYo%*TqSb?y@2>+?UOoR(6hC{z$Mkiv6+Dy_4|lYi5m|d3xogW z8-V&UU`qv3`KQf53yJ-5pI=B5ryNN=Gx3Rcw3|#07VWbNN>;cTKZpg=9UENMh<|=_ zGw%IhgN1+659x2#F=pF(<>vh-d8ch|JkqvWGo2$_U`x?KgXAAAsnE^EEBu&|(G$TP zsiM;^mJxf1@>=DIInb>ar0s<5=?^3YT>~1NZJrW(n4_C0)5V2E?E68T=(n*#UHB6) ZtXW!>^{81C=+FjfsO#J Date: Tue, 19 Mar 2024 14:14:12 -0700 Subject: [PATCH 3/7] Update README and Code of Conduct Signed-off-by: John Pennycook --- CODE_OF_CONDUCT.md | 131 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 132 ++++++++++++++++++++++++--------------------- 2 files changed, 202 insertions(+), 61 deletions(-) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..58dba18 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,131 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +CommunityCodeOfConduct AT intel DOT com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq diff --git a/README.md b/README.md index 3ccd301..2f0fb66 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,38 @@ # Code Base Investigator -Code Base Investigator (CBI) is a tool designed to help developers reason about the use of _specialization_ (i.e. code written specifically to provide support for or improve performance on some set of platforms) in a code base. Specialization is often necessary, but how a developer chooses to express it may impact code portability and future maintenance costs. -The [definition of platform](https://doi.org/10.1016/j.future.2017.08.007) used by CBI is deliberately very flexible and completely user-defined; a platform can represent any execution environment for which code may be specialized. A platform could be a compiler, an operating system, a micro-architecture or some combination of these options. +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5018974.svg)](https://doi.org/10.5281/zenodo.5018974) +[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8679/badge)](https://www.bestpractices.dev/projects/8679) -## Code Divergence -CBI measures the amount of specialization in a code base using [code divergence](http://doi.org/10.1109/P3HPC.2018.00006), which is defined as the arithmetic mean pair-wise distance between the code-paths used by each platform. +Code Base Investigator (CBI) is an analysis tool that provides insight into the +portability and maintainability of an application's source code. -At the two extremes, a code divergence of 0 means that all of the platforms use exactly the same code, while a code divergence of 1 means that there is no code shared between any of the platforms. The code divergence of real codes will fall somewhere in between. +- Measure [code divergence](http://doi.org/10.1109/P3HPC.2018.00006) to + understand how much code is specialized for different compilers, operating + systems, hardware micro-architectures and more. -## How it Works -![Abstract Syntax Tree](./docs/example-ast.png) +- Visualize the distance between the code paths used to support different + compilation targets. -CBI tracks specialization in two forms: source files that are not compiled for all platforms; and regions of source files that are guarded by C preprocessor directives (e.g. `#ifdef`). A typical run of CBI consists of a three step process: -1) Extract source files and compilation commands from a configuration file or compilation database. -2) Build an AST representing which source lines of code (LOC) are associated with each specialization. -3) Record which specializations are used by each platform. +- Identify stale, legacy, code paths that are unused by any compilation target. -## Usage +- Export metrics and code path information required for P3 analysis using [other + tools](https://intel.github.io/p3-analysis-library/). -The `codebasin` script analyzes a code base described in a YAML configuration file and produces one or more output reports. Example configuration files can be found in the [examples](./examples) directory, and see the [configuration file documentation](docs/configuration.md) for a detailed description of the configuration file format. -To see a complete list of `codebasin` options, run `codebasin -h`. +## Table of Contents -> [!IMPORTANT] -> In previous releases of Code Base Investigator, the main script was called `codebasin.py`. The old naming was a bug that needed to be fixed, and we made the difficult decision to rename the script ahead of the next major release. +- [Dependencies](#dependencies) +- [Installation](#installation) +- [Getting Started](#getting-started) +- [Contribute](#contribute) +- [License](#license) +- [Security](#security) +- [Code of Conduct](#code-of-conduct) +- [Citations](#citations) -### Summary Report -The summary report (`-R summary`) gives a high-level summary of a code base, as shown below: -``` ---------------------------------------------- - Platform Set LOC % LOC ---------------------------------------------- - {} 2 4.88 - {GPU 1} 1 2.44 - {GPU 2} 1 2.44 - {CPU 2} 1 2.44 - {CPU 1} 1 2.44 - {FPGA} 14 34.15 - {GPU 2, GPU 1} 6 14.63 - {CPU 1, CPU 2} 6 14.63 -{FPGA, CPU 1, GPU 2, GPU 1, CPU 2} 9 21.95 ---------------------------------------------- -Code Divergence: 0.55 -Unused Code (%): 4.88 -Total SLOC: 41 -``` -Each row in the table shows the amount of code that is unique to a given set of platforms. Listed below the table are the computed code divergence, the amount of code in the code base that was not compiled for any platform, and the total size of the code base. - -### Clustering Report -The clustering report (`-R clustering`) consists of a pair-wise distance matrix, showing the ratio of platform-specific code to code used by both platforms. These distances are the same as those used to compute code divergence. -``` -Distance Matrix ------------------------------------ - FPGA CPU 1 GPU 2 GPU 1 CPU 2 ------------------------------------ - FPGA 0.00 0.70 0.70 0.70 0.70 -CPU 1 0.70 0.00 0.61 0.61 0.12 -GPU 2 0.70 0.61 0.00 0.12 0.61 -GPU 1 0.70 0.61 0.12 0.00 0.61 -CPU 2 0.70 0.12 0.61 0.61 0.00 ------------------------------------ -``` - -The distances can also be used to produce a dendrogram, showing the result of hierarchical clustering by platform similarity: - -![Dendrogram](./docs/example-dendrogram.png) ## Dependencies + - jsonschema - Matplotlib - NumPy @@ -75,15 +41,59 @@ The distances can also be used to produce a dendrogram, showing the result of hi - PyYAML - SciPy -CBI and its dependencies can be installed using `setup.py`: + +## Installation + +The latest release of CBI is version 1.2.0. To download and install this +release, run the following: + ``` -python3 setup.py install +git clone --branch 1.2.0 https://github.com/intel/code-base-investigator.git +cd code-base-investigator +pip install . ``` -The master branch of CBI is the development branch, and should not be used in production. Tagged releases are available [here](https://github.com/intel/code-base-investigator/releases). +We strongly recommend installing CBI within a [virtual +environment](https://docs.python.org/3/library/venv.html). + +## Getting Started + +After installation, run `codebasin -h` to see a complete list of options. + +A full tutorial can be found in the [online +documentation](https://intel.github.io/code-base-investigator/). + + +## Contribute + +Contributions to CBI are welcome in the form of issues and pull requests. + +See [CONTRIBUTING](CONTRIBUTING.md) for more information. + ## License + [BSD 3-Clause](./LICENSE) -## Contributing -See the [contribution guidelines](./CONTRIBUTING.md) for details. + +## Security + +See [SECURITY](SECURITY.md) for more information. + +The main branch of CBI is the development branch, and should not be used in +production. Tagged releases are available +[here](https://github.com/intel/code-base-investigator/releases). + + +## Code of Conduct + +Intel has adopted the Contributor Covenant as the Code of Conduct for all of +its open source projects. See [CODE OF CONDUCT](CODE_OF_CONDUCT.md) for more +information. + + +## Citations + +If your use of CBI results in a research publication, please consider citing +the software and/or the papers that inspired its functionality (as +appropriate). See [CITATION](CITATION.cff) for more information. From 17f924be3be18e97befe3254275029baed814f3e Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 21 Mar 2024 08:24:30 -0700 Subject: [PATCH 4/7] Add note to etc/ directory explaining its purpose Signed-off-by: John Pennycook --- etc/README.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 etc/README.md diff --git a/etc/README.md b/etc/README.md new file mode 100644 index 0000000..7824777 --- /dev/null +++ b/etc/README.md @@ -0,0 +1,2 @@ +The scripts in this directory should be considered *experimental*, and may be +removed in future versions of Code Base Investigator. From 5fdc696aaddb90476fc74b72a6e8ca0a4e66bd0b Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Fri, 22 Mar 2024 10:35:14 -0700 Subject: [PATCH 5/7] Align -h output with online documentation - Start all descriptions with a capital letter. - Rewrite some messages for clarity. - Consistently use <> syntax for metavars. Signed-off-by: John Pennycook --- bin/codebasin | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/bin/codebasin b/bin/codebasin index 23559c3..292a620 100755 --- a/bin/codebasin +++ b/bin/codebasin @@ -42,6 +42,13 @@ def main(): # Read command-line arguments parser = argparse.ArgumentParser( description="Code Base Investigator " + str(version), + add_help=False, + ) + parser.add_argument( + "-h", + "--help", + action="help", + help="Display help message and exit.", ) parser.add_argument( "--version", @@ -54,9 +61,10 @@ def main(): "-r", "--rootdir", dest="rootdir", - metavar="DIR", + metavar="", default=None, - help="Set working root directory (default .)", + help="Set working root directory. " + + "Defaults to current working directory.", ) deprecated_args.add_argument( "-c", @@ -64,7 +72,7 @@ def main(): dest="config_file", metavar="", action="store", - help="Configuration YAML file. " + "Defaults to config.yaml", + help="Configuration YAML file. " + "Defaults to config.yaml.", ) parser.add_argument( "-v", @@ -72,7 +80,7 @@ def main(): dest="verbose", action="count", default=0, - help="increase verbosity level", + help="Increase verbosity level.", ) parser.add_argument( "-q", @@ -80,17 +88,17 @@ def main(): dest="quiet", action="count", default=0, - help="decrease verbosity level", + help="Decrease verbosity level.", ) parser.add_argument( "-R", "--report", dest="reports", - metavar="REPORT", + metavar="", default=["all"], choices=["all", "summary", "clustering"], nargs="+", - help="desired output reports (default: all)", + help="Generate a report of the specified type.", ) deprecated_args.add_argument( "-d", @@ -98,14 +106,14 @@ def main(): dest="dump", metavar="", action="store", - help="dump out annotated platform/parsing tree to ", + help="Dump out annotated platform/parsing tree to .", ) deprecated_args.add_argument( "--batchmode", dest="batchmode", action="store_true", default=False, - help="Set batch mode (additional output for bulk operation.)", + help="Enable additional output for bulk operation.", ) parser.add_argument( "-x", @@ -133,7 +141,7 @@ def main(): "analysis_file", metavar="", nargs="?", - help="TOML file describing the analysis to be performed," + help="TOML file describing the analysis to be performed, " + "including the codebase and platform descriptions.", ) From 123d24efd632d2f5155281c2b8c6a4715e3c12ad Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Fri, 22 Mar 2024 11:37:49 -0700 Subject: [PATCH 6/7] Use JSON code blocks for compilation databases Signed-off-by: John Pennycook --- docs/source/compilation-databases.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/compilation-databases.rst b/docs/source/compilation-databases.rst index 08b1fca..badffda 100644 --- a/docs/source/compilation-databases.rst +++ b/docs/source/compilation-databases.rst @@ -68,7 +68,9 @@ to actually run :code:`make`. executed, allowing us to generate compilation databases without also building the application. Other tools (like Bear) may require a build. -In this case, it contains:: +In this case, it contains: + +.. code :: json [ { @@ -102,7 +104,9 @@ compilation database for the GPU. As expected, we can see that the compilation database refers to ``gpu.cpp`` instead of ``cpu.cpp``, and that the ``GPU_OFFLOAD`` macro is defined as part -of each compilation command:: +of each compilation command: + +.. code :: json [ { From ae283fea7cfe6cc419378049da86b290db7a8a76 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Mon, 25 Mar 2024 06:59:48 -0700 Subject: [PATCH 7/7] Add README to docs/ Signed-off-by: John Pennycook --- docs/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c3697e5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +The HTML documentation is built with Sphinx, which can be installed by +following [these +instructions](https://www.sphinx-doc.org/en/master/usage/installation.html). + +We use the [furo](https://github.com/pradyunsg/furo) theme, which must be +installed separately. + +Other configuration options are documented in source/conf.py.