
To generate a custom compilation report in a text-based format starting from a template use the ``-gen_custom_report``.
You must provide the path to a FreeMarker template file (see `FreeMarker <http://freemarker.org/docs/ref.html>`_).
By default the custom report is generated in the current working directory. Specify a different location using ``-custom_report_location``.

Inside the template file, information about the compilation results can be obtained using the API available on the **${builder}** variable.

**Main API**

-  **getAllProblems()**: returns a list of all the compile problems
-  **getAllWaivers()**: returns a list of all the compile waivers
-  **getAllFiles()**: returns a list of all the compiled files in compilation order; a file may be compiled multiples times
-  **getTotalCompilationTimeFormatted()**: returns the total compilation time
-  **getTotalCompilationTimeMilliseconds()**: returns the total compilation time in milliseconds
-  **getNofCompiledLines()**: returns the total number of compiled lines

**Problems API**

-  **getId()**
-  **getSeverity()**
-  **getMessage()**
-  **getLine()**
-  **getFile()**

**Waivers API**

-  **getDescription()**
-  **getName()**
-  **getSeverity()**
-  **getFile()**
-  **getLine()**
-  **getHitCount()**: how many problems a waiver has matched
-  **getMatches()**: returns the waiver's "match" clauses

**Match Clause API**

-  **getPath()**
-  **getMessage()**

**File API**

-  **getPath()**
-  **getCompileSyntax()**: returns the language and language version that was used to compile a file (e.g. Verilog_2001)
-  **getNofLines()**
-  **getCompileIndex()**
-  **getCompileTime()**

Custom Report Examples
^^^^^^^^^^^^^^^^^^^^^^

**Example 1 - XML Report Template**

.. code-block::

 <report>
 <#list builder.getAllProblems() as problem>
        <problem
        id="${problem.getId()}"
        severity="${problem.getSeverity()}"
        line="${problem.getLine()}"
        message=<#if (problem.getMessage())?has_content>"${problem.getMessage()}"<#else>"*"</#if>
        file="${problem.getFile()}"
        />
 </#list>
 </report>

The resulting XML file will look like this:

.. code-block::

 <report>
     <problem
     id="MISSING_PORT_CONNECTION"
     severity="WARNING"
     line="5"
     message="MISSING_PORT_CONNECTION: Missing port connection to input port(s) 'bist_req_i'"
     file="mx_1/top.v"
     />
 <problem
     id="IMPLICIT_LIBRARY_ACCESS"
     severity="WARNING"
     line="31"
     message="IMPLICIT_LIBRARY_ACCESS: Access to 'work' library is implicit; the library clause can be removed"
     file="mx_1/jop/ext/gaisler/srctrl.vhd"
     />
 </report>

**Example 2 - JSON Report Template**

.. code-block::

 {
 "nofCompiledLines":"${builder.getNofCompiledLines()}",
 "compilationTime":"${builder.getTotalCompilationTimeFormatted()}"
 "files": [
     <#list builder.getAllFiles() as file>
     {
     "filePath":"${file.getPath()}",
     "compilationTime":"${file.getCompilationTime()}",
     "fileNofLine":"${file.getNofLines()}",
     "fileSyntax":"${file.getSyntax()}",
     "fileCompilationIndex":"${file.getCompilationIndex()}",
     },
     </#list>
     ],
 "waivers": [
     <#list builder.getAllWaivers() as waiver>
     {
     "waiverName":"${waiver.getName()}",
     "waiverSeverity":"${waiver.getSeverity()}",
     "waiverDefLine":"${waiver.getLine()}",
     "waiverDescription":<#if (waiver.getDescription())?has_content>"${waiver.getDescription()}"<#else>"*"</#if>,
     "waiverFile":"${waiver.getFile()}",
     "waiverHitCount":"${waiver.getHitCount()}",
     "waiverMatches": [
     <#list waiver.getMatches() as match>
     {
         "matchPath":<#if (match.getPath())?has_content>"${match.getPath()}"<#else>"*"</#if>,
         "matchMessage": <#if (match.getMessage())?has_content>"${match.getMessage()}"<#else>"*"</#if>,
     },
     </#list>
     ]
     },
     </#list>
 ] ,
 "problems": [
     <#list builder.getAllProblems() as problem>
     {
     "problemId":"${problem.getId()}",
     "problemSeverity":"${problem.getSeverity()}",
     "problemLine":"${problem.getLine()}",
     "problemMessage":<#if (problem.getMessage())?has_content>"${problem.getMessage()}"<#else>"*"</#if>,
     "problemFile":"${problem.getFile()}",
     },
     </#list>
 ]
 }

The resulting JSON file will look like this

.. code-block::

 {
 "nofCompiledLines":"22,602",
 "compilationTime":"5s.531ms"
 "files": [
     {
     "filePath":"mx_1/top.v",
     "compilationTime":"305",
     "fileNofLine":"190",
     "fileSyntax":"Verilog_2001",
     "fileCompilationIndex":"1",
     },
     {
     "filePath":"mx_1/i2c_master_slave_core/verilog/rtl/controller_interface.v",
     "compilationTime":"71",
     "fileNofLine":"547",
     "fileSyntax":"Verilog_2001",
     "fileCompilationIndex":"2",
     },
 "waivers": [
 {
     "waiverName":"SIGNAL_NEVER_USED",
     "waiverSeverity":"DISABLED",
     "waiverDefLine":"21",
     "waiverDescription":"*This waiver disables all problems that contain 'SIGNAL_NEVER_USED' inside their message AND were reported under 'mx_1/jop/vhdl/top/'.",
     "waiverFile":"mx_1/.dvt/waivers.xml",
     "waiverHitCount":"146",
     "waiverMatches": [
     {
         "matchPath":"mx_1/jop/vhdl/top/",
         "matchMessage": "SIGNAL_NEVER_USED: Signal is never used",
     },
     {
         "matchPath":"*",
         "matchMessage": "*SIGNAL_NEVER_USED*",
     },
     ]
 },
     {
     "waiverName":"",
     "waiverSeverity":"ERROR",
     "waiverDefLine":"25",
     "waiverDescription":"*",
     "waiverFile":"mx_1/.dvt/waivers.xml",
     "waiverHitCount":"6",
     "waiverMatches": [
     {
         "matchPath":"mx_1/jop/vhdl/simulation/tb_jop_iic.vhd",
         "matchMessage": "NON_STANDARD_API: Unexpected method/",
     },
     {
         "matchPath":"''",
         "matchMessage": "*SIGNAL_NEVER_WRITTEN*",
     },
     ]
 },
 ],
 "problems": [
     {
     "problemId":"MISSING_PORT_CONNECTION",
     "problemSeverity":"WARNING",
     "problemLine":"5",
     "problemMessage":"MISSING_PORT_CONNECTION: Missing port connection to input port(s) 'bist_req_i'",
     "problemFile":"mx_1/top.v",
     },
     {
     "problemId":"MISSING_PORT_CONNECTION",
     "problemSeverity":"WARNING",
     "problemLine":"5",
     "problemMessage":"MISSING_PORT_CONNECTION: Missing port connection to output port(s) 'bist_ack_o, bist_err_o'",
     "problemFile":"mx_1/top.v",
     }
 ]
 }
