.. _Precompilation Support:

Precompilation Support
======================

.. rst-class:: lead

    To speed up the full build of your project you can load a precompiled section of code (also referred to as a precompiled library, precompiled database fragment or simply precompiled db).

First you need to figure out which section of the project should be precompiled, usually libraries or IPs which rarely get modified, and refactor the project’s original build configuration in two files:

- a **precompiled_save.build** config file to save the database, usually comprising of one or more :ref:`+dvt_init <Emulating compiler invocations>` sections
- a **precompiled_load.build** config file to load the database and compile other files on top of it

For clarity it is recommended to use suggestive filenames, however there is no hard constraint.

Next you need to perform a build using the **precompiled_save.build** config, either from the IDE or in batch mode using **dvt_build.sh**. 

Once the precompiled database is saved, switch to the **precompiled_load.build** config and rebuild.
You will get the same compilation result as with the original build config, however with a significantly faster full build.

The **precompiled_save.build** config file must specify the **+dvt_precompiled_db_save+<path>** directive and the database location:

.. code-block:: 

 +dvt_precompiled_db_save+/path/to/precompiled/database/location
 ... build configuration directives ...

The **precompiled_load.build** config file must start with a **+dvt_init_precompiled_db_load** directive and specify the database location:
 
.. code-block:: 
 
 +dvt_init_precompiled_db_load
 +dvt_precompiled_db_location+/path/to/precompiled/database/location
 
The **+dvt_init_precompiled_db_load** is a special kind of :ref:`invocation <Emulating compiler invocations>` and **only precompile-related** configuration directives are allowed inside it.
Files compiled on top of the precompiled database must be specified in subsequent **+dvt_init** sections.

You must rebuild the precompiled database when:

-  DVT version changes
-  Precompiled source files change
-  Database files get corrupted

Note that DVT triggers a notification when changes are detected in precompiled source code, based on MD5 checksums. To turn off this change detection mechanism, use **+dvt_precompiled_db_disable_md5_change_detection** when loading a precompiled database:

.. code-block::

 +dvt_init_precompiled_db_load
 +dvt_precompiled_db_location+/path/to/precompiled/database/location
 +dvt_precompiled_db_disable_md5_change_detection


When the precompiled database needs to be rebuilt, you can either do it from the GUI or in batch mode using **dvt_build.sh**.
The batch mode command can be specified inside the **+dvt_init_precompiled_db_load** section, and will be automatically called in case load fails, for example:
 
.. code-block:: 
 
 +dvt_init_precompiled_db_load
 +dvt_precompiled_db_location+/path/to/precompiled/database/location
 +dvt_precompiled_db_build_cmd+"$DVT_HOME/bin/dvt_build.sh -lang vlog -cmd /path/to/precompile_save.build"

.. tip:: 

 When precompiled databases need to be rebuilt, multiple +dvt_precompiled_db_build_cmd+<cmd> can be run in parallel. You can configure the maximum number of precompiled database rebuild commands that can run simultaneously using **+dvt_precompiled_db_build_cmd_max_jobs**.

Precompiled databases created using +dvt_precompiled_db_save **can be shared** across the team. Simply point the **+dvt_precompiled_db_location** to the precompiled database location.
Precompiled source files might be located in a user-specific path. For DVT to properly display precompiled sources, define the save to load path re-mapping using **dvt_precompiled_db_src_map**.
When loading multiple shared precompiled databases, **+dvt_precompiled_db_src_map** will be applied to all **+dvt_init_precompiled_db_load** sections.
 
.. code-block:: 

 +dvt_precompiled_db_src_map+/save/src/path=/load/src/path/

 +dvt_init_precompiled_db_load
 +dvt_precompiled_db_location+/path/to/precompiled/database/location_1

 +dvt_init_precompiled_db_load
 +dvt_precompiled_db_location+/path/to/precompiled/database/location_2

You can load precompiled libraries even when source files are not available. All DVT features will work as expected, the only downside being that you cannot open the precompiled source files.

Auto precompiled databases
--------------------------

You can instruct DVT to automatically manage precompiled databases. The build configuration is partitioned into multiple compilation fragments under the hood, one for each +dvt_init section. Each fragment gets saved in a separate precompiled database. During the build process, DVT identifies which fragments need to be rebuilt and automatically keeps them up-to-date.

To enable auto precompiled databases use +dvt_precompiled_db_auto followed by the database location:

.. code-block:: 

 +dvt_precompiled_db_auto+/path/to/precompiled/database/location
 ... +dvt_init sections ...

There might be invocations which you do not want to auto-precompile, for example those containing frequently modified files. Use one of the following directives:

- **+dvt_precompiled_db_auto_exclude_library+<libname1>[+<libname2>+...]**: this is a global directive which disables the precompilation for all invocations under a particular **-work** library
- **+dvt_precompiled_db_auto_exclude_path+<simple_pattern>**: this is a global directive which disables the precompilation for all invocations that contain files whose absolute path **matches** the specified <simple_pattern>
- **+dvt_precompiled_db_auto_exclude**: this directive excludes the invocation under which it resides from being precompiled

For simple patterns, wildcards like ``*`` (to match any sequence of characters) and ``?`` (to match a single character) are available. The provided patterns are matched against file absolute paths.

.. tip:: 

 All precompiled files are marked with a decorator in Compile Order View.

.. figure:: ../../images/common/precompiled_compile_order.png

.. tip:: 
 When loading multiple precompiled databases, DVT uses a pool of parallel threads. You can configure the maximum number of parallel threads used for loading precompiled databases by using the **+dvt_precompiled_db_max_nof_threads** directive. The default value is 8.

.. rubric:: This table can help you decide which approach better suits your needs

.. list-table::

   * - **+dvt_init_precompiled_db_load**
     - **+dvt_precompiled_db_auto**
   * - Build configuration refactoring into save and load configurations is required.
     - Build configuration can be used as-is (as long as it has multiple +dvt_init sections).
   * - Precompiled files cannot be edited.
     - Precompiled files can be edited. 
   * - You must handle precompiled database updates, for example when source code changes / across tool versions.
     - DVT automatically detects changes in the precompiled files and updates the precompiled databases.
   * - Precompiled databases can be shared across the team.
     - Precompiled databases cannot be shared across the team.

To get the best speed-up, it is recommended to:

- explicitly configure precompilation for sections of code that never change
- use automatic precompilation for +dvt_init sections which rarely get changed
- exclude the invocations you are actively working on from being precompiled

.. code-block:: 

 +dvt_precompiled_db_auto+/path/to/auto/precompiled/database/location
 +dvt_precompiled_db_auto_exclude_library+auto_precompiled_database1
 +dvt_precompiled_db_auto_exclude_path_add+*/subdirectory/*

 +dvt_init_precompiled_db_load
 // This precompiled database is not automatically managed
 +dvt_precompiled_db_location+/path/to/precompiled/database/location1

 +dvt_init_precompiled_db_load
 // This precompiled database is not automatically managed
 +dvt_precompiled_db_location+/path/to/precompiled/database/location2

 +dvt_init
 // This invocation is excluded from auto precompilation
 -work auto_precompiled_database1
 ... build configuration directives …

 +dvt_init
 // This invocation is excluded from auto precompilation
 -work auto_precompiled_database1
 ... build configuration directives ...

 +dvt_init
 -work auto_precompiled_database2
 ... build configuration directives ...

 +dvt_init
 // This invocation is excluded from auto precompilation
 -work auto_precompiled_database2
 +dvt_precompiled_db_auto_exclude
 ... build configuration directives ...

 +dvt_init
 -work auto_precompiled_database3
 ... build configuration directives ...

 +dvt_init
 -work auto_precompiled_database4
 // This invocation is excluded from auto precompilation because of +dvt_precompiled_db_auto_exclude_path_add
 subdirectory/file1.sv
 another_subdirectory/file2.sv
