Listing HEADER files

[Risto97]

Currently, there is no way to retrigger targets if the verilog header files change.
This is a similar problem to how C++ header files are tracked with depend.make in Makefiles.

Currently, easiest solution to implement is to list the header files manually, something like:

ip_sources(${IP} SYSTEMVERILOG
    HEADERS 
     file1.sv
....

[Risto97]

This is implemented in 0318507.

I would appreciate feedback on this feature, or maybe alternative ideas on how to solve it @mksoc @benoitdenkinger @nookfoo

To add more context.
In SystemVerilog-UVM components are implemented as SV classes.
Classes are usually written in Header files, not in source SystemVerilog files.

Simulators expect only source files to be passed as CLI arguments, while header files are expected to be found through include directories, passed as (+incdir+).
Since in SoCMake so far we only have the include directories of header files set with ip_include_directories(${IP} SYSTEMVERILOG ...) there is no way to track the changes of said header files and retrigger builds.
As a consequence, in a UVM projects, if you modify a e.g. apb_driver.svh, this will not retrigger recompilation of the environment.

The solution found in CMake and C++ (gcc depend files) is not available in SystemVerilog tools, so at the moment I opted for the option of explicitly listing header files.

There are some advantages to this solution:

• Having them explicitly listed would allow us to do more easily tasks such as installing, linting, or any other custom step as the file list is available at configure time.
• Simplicity, not having to rely on a commercial or a custom tool to extract dependencies will make it less error-prone.

A disadvantage is:

• Once the header file changes a whole IP block would be recompiled, even IP blocks that depend on it, as opposed to C++ where only the depending source file gets recompiled. This might not be a big issue, as it is anyways difficult to do per-source file compilation with available simulators.

With this implementation header files can be added as follows:

ip_sources(${IP} SYSTEMVERILOG
      source1.sv
      source2.sv
    HEADERS
      header1.sv
      header2.sv
    )

get_ip_sources(sources ${IP} SYSTEMVERILOG}
Would still return only source1.sv and source2.sv

To get the header files only (without sources) call:
get_ip_sources(sources ${IP} SYSTEMVERILOG HEADERS)

P.S. There was an alternative implementation of this, to be more consistent with CMake.

CMake you can list header files (optional) in the target_sources() function like this:

target_sources(test PUBLIC
   main.cpp
   hello.cc
   hello.h
   hello.hh
  )

There are no delimiter HEADERS, but instead CMake detects the file extensions.
I decided not to go this way because:

1. This requires a predefined set of extensions for languages, right now SoCMake is pretty flexible on adding new languages, and this would require more work when adding a new one.
2. What if users use some weird extension for SystemVerilog?

[benoitdenkinger]

Tracking header files is definitely helpful. We faced the problem when "exporting" the sources from a target but only having the header files include directories. What we implemented was copying all the files inside the include directories, which is not ideal.

Regarding the implementation, I don't have a strong opinion. Supporting the non-explicit solution (without the HEADERS parameter) requires defining standard extensions, but I guess it is the same for the target_sources() built-in function. At some point, we cannot support any input from users and I've never seen SystemVerilog files with an extension different that 'sv' or 'svh' (but maybe for other languages it is not so standard). I think this also imposes some minimum rules, I wouldn't like (and provide support) to a project that defines SystemVerilog files with meaningless extensions.

[Risto97]

I agree that not everything should be allowed as file extensions.
However, there are weird use cases, e.g. in Verilator .vlt file extension is used for things like waivers, etc...
From what I understand that is just a SystemVerilog file, that is passed to CLI like other files.

A more important reason why I kept it explicit is that in case of adding a "new" language, the user would have to define the file extensions as well for the language.
Right now any language is accepted, there will only be a warning given by SoCMake if the language is not "supported".
It is enough to append language to SOCMAKE_ADDITIONAL_LANGUAGES variable, same could be done for extensions maybe, a list variables like this: SOCMAKE_${LANG}_SOURCE_EXTENSIONS, SOCMAKE_${LANG}_HEADERS_EXTENSIONS can exist for each language

---

Header installation

Something to consider when copying header files.
If the header file is included like this:

`include "some_dir/some_header.svh"

In that case the include directory should be set like this:

ip_include_directories(${IP} SYSTEMVERILOG
    <path-to-some_dir>
    )

It is important that at the destination the directory structure stays some_dir/some_header.svh, otherwise it will not work.
So the install function needs to be smarter, to only copy the listed headers, but to respect the include directories structure given by ip_include_directories().
Copying the whole directory as you did, probably resolves the problem also, but the risk of copying something you dont want stays.

[benoitdenkinger]

Simulator/tool specific files

Files like the vlt ones are simulator specific and each simulator have its own set of input files it can defined. For verilator, this .vlt files are configuration files. The extension .vlt is the default proposed one but what makes it a verilator configuration file is only the `verilator_config directive in the file. These files are not RTL sources and they must be differentiated from them.

For this kind of files (simulator/tool specific), we either need to support them with an additional language (which is already what we have for these vlt files I believe) or we need to give the possibility to the user to add the extra language (that we have) and also put an extra generic argument when calling the different simulators (and tools in general) to be able to pass extra commands/files. If the files are commonly used (e.g., these vlt files), I would support them natively, for more custom features I would let the users do the work.

Header installation

When calling the target_source() function, one format is (source):

target_sources(
    file_loader
    PRIVATE
        src/file_loader.cpp

    PUBLIC
    FILE_SET HEADERS
    BASE_DIRS src/include
    FILES
        src/include/lib_file_loader/file_loader.h
)

In src/file_loader.cpp you do #include "lib_file_loader/file_loader.h"

We could also request the BASE_DIRS with the HEADERS (I'm not proposing to use the other syntax format with the FILE_SET, this is just an example I found).