Skip to content

Commit f3f9ecf

Browse files
tromaitromai
authored
docs: update the Output Files Guide page in the Sphinx documentation (#281)
Signed-off-by: Trong Nhan Mai <trong.nhan.mai@oracle.com>
1 parent 6047b12 commit f3f9ecf

File tree

2 files changed

+140
-2
lines changed

2 files changed

+140
-2
lines changed

‎docs/source/pages/output_files.rst

Lines changed: 139 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,142 @@
77
Output Files Guide
88
==================
99

10-
TBD
10+
.. note:: Please see :ref:`pages/cli_usage/index:common options` for the instructions on how to set the output directory of Macaron.
11+
12+
-------------------
13+
Top level structure
14+
-------------------
15+
16+
.. code-block::
17+
18+
output/
19+
├── .gradle/
20+
├── .m2/
21+
├── build_log/
22+
├── git_repos/
23+
├── reports/
24+
├── debug.log
25+
├── macaron.db
26+
└── sbom_debug.json
27+
28+
-------
29+
Reports
30+
-------
31+
32+
The report files of Macaron (from using the :ref:`analyze action <analyze-action-cli>`) are generated into the ``reports`` directory.
33+
34+
.. code-block::
35+
36+
output/
37+
└── reports/
38+
└── ...
39+
40+
''''''''''''''''''
41+
Unique result path
42+
''''''''''''''''''
43+
44+
For each target repository, Macaron creates a directory under ``reports`` to store the report files. This directory
45+
path is formed from the git host name (e.g ``github.com``), the owner and the name of that
46+
repository. The final path is created using the following template:
47+
48+
.. code-block::
49+
50+
<path_to_output>/reports/<git_service_name>/<owner>/<repo_name>
51+
52+
.. note:: The git host name has all occurrence of ``.`` in the URL replaced by ``_``.
53+
54+
For example, the reports for `<https://github.com/micronaut-projects/micronaut-core>`_ repository will be stored under
55+
``<path_to_output>/reports/github_com/micronaut-projects/micronaut-core``.
56+
57+
''''''''''''
58+
Report types
59+
''''''''''''
60+
61+
Macaron creates three types of reports:
62+
63+
#. JSON reports (``*.json`` files): contain the analysis result.
64+
#. HTML reports (``*.html`` files): display the analysis result in HTML pages.
65+
#. Dependencies report (``dependencies.json``): contain the list of dependencies that Macaron found for the target repository.
66+
67+
.. note:: The JSON and HTML reports for dependencies (if any) are stored in the same directory as the target repository.
68+
69+
For example, for `<https://github.com/micronaut-projects/micronaut-core>`_ the report directory can have the following structure:
70+
71+
.. code-block::
72+
73+
output/
74+
└── reports/
75+
└── github_com/
76+
└── micronaut-projects
77+
└── micronaut-core
78+
├── dependencies.json
79+
├── micronaut-core.html
80+
├── micronaut-core.json
81+
├── dependency_1.html
82+
├── dependency_1.json
83+
├── dependency_2.html
84+
├── dependency_2.json
85+
└── ...
86+
87+
-------------------
88+
Cloned repositories
89+
-------------------
90+
91+
The ``git_repos`` directory is used to clone repositories into during the analysis. Each remote repository is cloned to a unique path
92+
within ``git_repos`` following the same strategy as `Unique result path`_.
93+
94+
For example, `<https://github.com/micronaut-projects/micronaut-core>`_ will be cloned into:
95+
96+
.. code-block::
97+
98+
output/
99+
└── git_repos
100+
└── micronaut-projects
101+
└── micronaut-core
102+
103+
By default, if a local path is provided to the :ref:`analyze action <analyze-action-cli>`, this path will be treated as a relative path
104+
to the directory:
105+
106+
.. code-block::
107+
108+
output/
109+
└── git_repos
110+
└── local_repos
111+
112+
.. note:: Please see :ref:`pages/using:analyzing a locally cloned repository` to know how to set the directory for analyzing local repositories.
113+
114+
------
115+
Others
116+
------
117+
118+
''''''''''
119+
macaron.db
120+
''''''''''
121+
122+
The file is the SQLite database used by Macaron for storing analysis results.
123+
124+
'''''''''
125+
debug.log
126+
'''''''''
127+
128+
This file stores the log messages from the latest run of Macaron.
129+
130+
'''''''''
131+
build_log
132+
'''''''''
133+
134+
This is the directory for storing the log from running external components such as `CycloneDx SBOM Maven plugin <https://github.com/CycloneDX/cyclonedx-maven-plugin>`_, `CycloneDx SBOM Gradle plugin <https://github.com/CycloneDX/cyclonedx-gradle-plugin>`_ or the `slsa-verifier <https://github.com/slsa-framework/slsa-verifier>`_.
135+
136+
'''''''''''''''
137+
sbom_debug.json
138+
'''''''''''''''
139+
140+
This file contain the debug information for running the SBOM generator to obtain dependencies of a repository.
141+
142+
'''''''''''''''
143+
.m2 and .gradle
144+
'''''''''''''''
145+
146+
These two directories cache the content of ``~/.m2`` and ``~/.gradle`` in the Docker container between different runs (which are
147+
mainly updated by the CycloneDX SBOM plugins).
148+
This will helps subsequent runs on the same target repository faster.

‎docs/source/pages/using.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Take the same example as above, to disable analyzing `micronaut-core <https://gi
4343
4444
./run_macaron.sh analyze -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 --skip-deps
4545
46-
.. note:: During the analysis, Macaron would generate report files into the output directory in the current workspace. To understand the structure of this directory please see :ref:`Output Files Guide <output_files_guide>`.
46+
.. note:: By default, Macaron would generate report files into the ``output`` directory in the current workspace. To understand the structure of this directory please see :ref:`Output Files Guide <output_files_guide>`.
4747

4848
With the example above, the generated output reports can be seen here:
4949

0 commit comments

Comments
 (0)