diff --git a/docs/source/pages/output_files.rst b/docs/source/pages/output_files.rst index bb9aa6779..6dd1a26c2 100644 --- a/docs/source/pages/output_files.rst +++ b/docs/source/pages/output_files.rst @@ -7,4 +7,142 @@ Output Files Guide ================== -TBD +.. note:: Please see :ref:`pages/cli_usage/index:common options` for the instructions on how to set the output directory of Macaron. + +------------------- +Top level structure +------------------- + +.. code-block:: + + output/ + ├── .gradle/ + ├── .m2/ + ├── build_log/ + ├── git_repos/ + ├── reports/ + ├── debug.log + ├── macaron.db + └── sbom_debug.json + +------- +Reports +------- + +The report files of Macaron (from using the :ref:`analyze action `) are generated into the ``reports`` directory. + +.. code-block:: + + output/ + └── reports/ + └── ... + +'''''''''''''''''' +Unique result path +'''''''''''''''''' + +For each target repository, Macaron creates a directory under ``reports`` to store the report files. This directory +path is formed from the git host name (e.g ``github.com``), the owner and the name of that +repository. The final path is created using the following template: + +.. code-block:: + + /reports/// + +.. note:: The git host name has all occurrence of ``.`` in the URL replaced by ``_``. + +For example, the reports for ``_ repository will be stored under +``/reports/github_com/micronaut-projects/micronaut-core``. + +'''''''''''' +Report types +'''''''''''' + +Macaron creates three types of reports: + +#. JSON reports (``*.json`` files): contain the analysis result. +#. HTML reports (``*.html`` files): display the analysis result in HTML pages. +#. Dependencies report (``dependencies.json``): contain the list of dependencies that Macaron found for the target repository. + +.. note:: The JSON and HTML reports for dependencies (if any) are stored in the same directory as the target repository. + +For example, for ``_ the report directory can have the following structure: + +.. code-block:: + + output/ + └── reports/ + └── github_com/ + └── micronaut-projects + └── micronaut-core + ├── dependencies.json + ├── micronaut-core.html + ├── micronaut-core.json + ├── dependency_1.html + ├── dependency_1.json + ├── dependency_2.html + ├── dependency_2.json + └── ... + +------------------- +Cloned repositories +------------------- + +The ``git_repos`` directory is used to clone repositories into during the analysis. Each remote repository is cloned to a unique path +within ``git_repos`` following the same strategy as `Unique result path`_. + +For example, ``_ will be cloned into: + +.. code-block:: + + output/ + └── git_repos + └── micronaut-projects + └── micronaut-core + +By default, if a local path is provided to the :ref:`analyze action `, this path will be treated as a relative path +to the directory: + +.. code-block:: + + output/ + └── git_repos + └── local_repos + +.. note:: Please see :ref:`pages/using:analyzing a locally cloned repository` to know how to set the directory for analyzing local repositories. + +------ +Others +------ + +'''''''''' +macaron.db +'''''''''' + +The file is the SQLite database used by Macaron for storing analysis results. + +''''''''' +debug.log +''''''''' + +This file stores the log messages from the latest run of Macaron. + +''''''''' +build_log +''''''''' + +This is the directory for storing the log from running external components such as `CycloneDx SBOM Maven plugin `_, `CycloneDx SBOM Gradle plugin `_ or the `slsa-verifier `_. + +''''''''''''''' +sbom_debug.json +''''''''''''''' + +This file contain the debug information for running the SBOM generator to obtain dependencies of a repository. + +''''''''''''''' +.m2 and .gradle +''''''''''''''' + +These two directories cache the content of ``~/.m2`` and ``~/.gradle`` in the Docker container between different runs (which are +mainly updated by the CycloneDX SBOM plugins). +This will helps subsequent runs on the same target repository faster. diff --git a/docs/source/pages/using.rst b/docs/source/pages/using.rst index 2592819ad..c2b27dd15 100644 --- a/docs/source/pages/using.rst +++ b/docs/source/pages/using.rst @@ -43,7 +43,7 @@ Take the same example as above, to disable analyzing `micronaut-core `. +.. 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 `. With the example above, the generated output reports can be seen here: