Skip to content

Commit 6b1541f

Browse files
PennycookPennycook
committed
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 <john.pennycook@intel.com>
1 parent b7af834 commit 6b1541f

22 files changed

+1033
-0
lines changed

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/sample-code-base/src/CMakeLists.txt

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Copyright (c) 2024 Intel Corporation
2+
# SPDX-License-Identifier: 0BSD
3+
cmake_minimum_required(VERSION 3.5)
4+
project(tutorial)
5+
6+
set(SOURCES main.cpp third-party/library.cpp)
7+
8+
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
9+
10+
option(GPU_OFFLOAD "Enable GPU offload." OFF)
11+
if (GPU_OFFLOAD)
12+
add_definitions("-D GPU_OFFLOAD=1")
13+
list(APPEND SOURCES gpu/foo.cpp)
14+
else()
15+
list(APPEND SOURCES cpu/foo.cpp)
16+
endif()
17+
18+
add_executable(tutorial ${SOURCES})

‎docs/sample-code-base/src/cpu/foo.cpp

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// Copyright (c) 2024 Intel Corporation
2+
// SPDX-License-Identifier: 0BSD
3+
#include <cstdio>
4+
5+
void foo() {
6+
#if __GNUC__ >= 13
7+
printf("Using a feature that is only available in GCC 13 and later.\n");
8+
#endif
9+
printf("Running the rest of foo() on the CPU.\n");
10+
}

‎docs/sample-code-base/src/gpu/foo.cpp

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// Copyright (c) 2024 Intel Corporation
2+
// SPDX-License-Identifier: 0BSD
3+
#include <cstdio>
4+
5+
void foo() {
6+
#if __GNUC__ >= 13
7+
printf("Using a feature that is only available in GCC 13 and later.\n");
8+
#endif
9+
printf("Running the rest of foo() on the GPU.\n");
10+
}

‎docs/sample-code-base/src/main.cpp

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Copyright (c) 2024 Intel Corporation
2+
// SPDX-License-Identifier: 0BSD
3+
#include <cstdio>
4+
#include "third-party/library.h"
5+
void foo();
6+
7+
int main(int argc, char* argv[])
8+
{
9+
#if !defined(GPU_OFFLOAD)
10+
printf("Running on the CPU.\n");
11+
#else
12+
printf("Running on the GPU.\n");
13+
#endif
14+
foo();
15+
bar();
16+
}

‎docs/sample-code-base/src/third-party/library.cpp

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// Copyright (c) 2024 Intel Corporation
2+
// SPDX-License-Identifier: 0BSD
3+
#include <cstdio>
4+
5+
void bar()
6+
{
7+
printf("Running third-party library code.\n");
8+
}

‎docs/sample-code-base/src/third-party/library.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
// Copyright (c) 2024 Intel Corporation
2+
// SPDX-License-Identifier: 0BSD
3+
void bar();

‎docs/source/analysis.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
Performing Analysis
2+
===================
3+
4+
The main interface of CBI is the ``codebasin`` script, which can be invoked to
5+
analyze a code base and produce various reports. Although CBI ships with other
6+
interfaces specialized for certain use-cases, ``codebasin`` supports an
7+
end-to-end workflow that should be preferred for general usage.
8+
9+
The simplest way to invoke ``codebasin`` is as shown below::
10+
11+
$ codebasin analysis.toml
12+
13+
...but what is ``analysis.toml``? We need to use this file to tell CBI which
14+
files are part of the code base, and where it should look to find the
15+
compilation databases defining our platforms.
16+
17+
.. note::
18+
19+
The TOML file can have any name, but we'll use "analysis.toml" throughout
20+
this tutorial.
21+
22+
23+
Defining Platforms
24+
##################
25+
26+
Each platform definition is a TOML `table`_, of the form shown below:
27+
28+
.. _`table`: https://toml.io/en/v1.0.0#table
29+
30+
.. code-block:: toml
31+
32+
[platform.name]
33+
commands = "/path/to/compile_commands.json"
34+
35+
The table's name is the name of the platform, and we can use any meaningful
36+
string. The ``commands`` key tells CBI where to find the compilation database
37+
for this platform.
38+
39+
In our example, we have two platforms that we're calling "cpu" and "gpu",
40+
and our build directories are called ``build-cpu`` and ``build-gpu``, so
41+
our platform definitions should look like this:
42+
43+
.. code-block:: toml
44+
45+
[platform.cpu]
46+
commands = "build-cpu/compile_commands.json"
47+
48+
[platform.gpu]
49+
commands = "build-gpu/compile_commands.json"
50+
51+
.. warning::
52+
Platform names are case sensitive! The names "cpu" and "CPU" would refer to
53+
two different platforms.
54+
55+
56+
Running ``codebasin``
57+
#####################
58+
59+
Running ``codebasin`` with this analysis file gives the following output:
60+
61+
.. code-block:: text
62+
:emphasize-lines: 4,5,6,7,9
63+
64+
-----------------------
65+
Platform Set LOC % LOC
66+
-----------------------
67+
{} 2 6.06
68+
{cpu} 7 21.21
69+
{gpu} 7 21.21
70+
{cpu, gpu} 17 51.52
71+
-----------------------
72+
Code Divergence: 0.45
73+
Unused Code (%): 6.06
74+
Total SLOC: 33
75+
76+
Distance Matrix
77+
--------------
78+
cpu gpu
79+
--------------
80+
cpu 0.00 0.45
81+
gpu 0.45 0.00
82+
83+
The results show that there are 2 lines of code that are unused by any
84+
platform, 7 lines of code used only by the CPU compilation, 7 lines of code
85+
used only by the GPU compilation, and 17 lines of code shared by both
86+
platforms. Plugging these numbers into the equation for code divergence gives
87+
0.45.
88+
89+
90+
Filtering Platforms
91+
###################
92+
93+
When working with an application that supports lots of platforms, we may want
94+
to limit the analysis to a subset of the platforms defined in the analysis
95+
file.
96+
97+
Rather than require a separate analysis file for each possible subset, we can
98+
use the :code:`--platform` flag (or :code:`-p` flag) to specify the subset of
99+
interest on the command line:
100+
101+
.. code:: sh
102+
103+
$ codebasin -p [PLATFORM 1] -p [PLATFORM 2] analysis.toml
104+
105+
For example, we can limit the analysis of our sample code base to the cpu
106+
platform as follows:
107+
108+
.. code:: sh
109+
110+
$ codebasin -p cpu analysis.toml

‎docs/source/cmd.rst

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Command Line Interface
2+
======================
3+
4+
.. code-block:: text
5+
6+
codebasin [-h] [--version] [-v] [-q] [-R <report>] [-x <pattern>] [-p <platform>] [<analysis-file>]
7+
8+
**positional arguments:**
9+
10+
``analysis-file``
11+
TOML file describing the analysis to be performed,
12+
including the codebase and platform descriptions.
13+
14+
**options:**
15+
16+
``-h, --help``
17+
Show help message and exit.
18+
19+
``--version``
20+
Display version information and exit.
21+
22+
``-v, --verbose``
23+
Increase verbosity level.
24+
25+
``-q, --quiet``
26+
Decrease verbosity level.
27+
28+
``-R <report>``
29+
Generate a report of the specified type.
30+
31+
- ``summary``: output only code divergence information.
32+
- ``clustering``: output only distance matrix and dendrogram.
33+
- ``all``: generate both summary and clustering reports.
34+
35+
``-x <pattern>, --exclude <pattern>``
36+
Exclude files matching this pattern from the code base.
37+
May be specified multiple times.
38+
39+
``-p <platform>, --platform <platform>``
40+
Include the specified platform in the analysis.
41+
May be specified multiple times.
42+
If not specified, all platforms will be included.

0 commit comments

Comments
 (0)