		Search-engine friendly clone of the ACL2 documentation.

Preprocessor

Preprocessor-include-minutia

Subtle notes about `include handling.

The Verilog spec is very vague about how include directives are to be processed.

It does nicely explain that we are to simply replace the `include "foo.v" directive with the entire contents of foo.b, and explains some things related to the syntax of the directive. It also says that the included file can itself contain include directives, which of course seems perfectly reasonable.

The spec explicitly says the filename can be an absolute or relative pathname. In the case of an absolute pathname, the intention seems pretty clear.

Unfortunately, the spec does not explain anything about what a relative path is relative to. Upon reading the spec, I thought, "well, obviously it means relative to whatever file is currently being processed." But it turns out that this is not at all how Verilog-XL and NCVerilog handle things.

Instead, both of these tools include a notion of include directories. These directories are similar to, but distinct from, the library directories which are used to load "missing" modules. These directories are configured with command-line options like:

+incdir+/home/jared/dir1 +incdir+/home/jared/dir2 ...

When these tools see `include "foo.v", they seem to search for foo.v in these include directories, and include the first file that is found.

Because of this, it does not work to just try to write includes relative to whatever file is being loaded, you just always write them relative to whatever the include path is going to be.