Adding module hierarchy for library creation and explicit imports

[rbkettlewell]

This is a language feature proposal.

Incorporating the ability to publish projects and add dependencies similar in spirit to Rust is a great addition to Veryl. However, one current limitation, it seems to me, is that there isn't a way to organize modules in a hierarchical fashion. I realize that this is likely to align with System Verilog's flat global namespace for modules and what is expected from EDA tools. However, I believe the pros outweigh the cons of organizing modules hierarchically into sharable libraries and that this promotes code reuse.

Lets imagine we are building a core library which contains useful building blocks for digital design:

core
    src
        register
            reg_a.vl
            reg_b.vl
        fifo
            fifo_d.vl
            fifo_s.vl
        ...
    Veryl.toml
    Veryl.pub

If one then adds this core library as a dependency for a project it would be nice to be able to use its modules explicitly as such:

module foo
use core::register::reg_a;
(...){
    // some user logic
    inst a_foo : reg_a(...) 

Or alternatively:

module foo
use core;
(...){
    // some user logic
    inst a_foo : core::register::reg_a(...) 

This would be preferable over implicit importing once the dependency is defined, where something like this would be allowed:

module foo(...){
    // some user logic
    inst a_foo : core::register::reg_a(...) 

Perhaps a mod.vl could be added to the core library taking Rust's older approach to organizing modules in a crate. This file mod.vl for the register subdirectory could have the following contents:

mod reg_a;
mod reg_b;

A similar mod.vl would thus be added for each logical grouping of Veryl modules like fifo and so on.

Finally the core library would be updated to look like the following:

core
    src
        register
            reg_a.vl
            reg_b.vl
            mod.vl
        fifo
            fifo_d.vl
            fifo_s.vl
            mod.vl
        ...
    Veryl.toml
    Veryl.pub

[dalance]

I agree that hierarchical structure is useful. I think there are some points which should be considerd.

Explicit file structure

Currently, Veryl gather "*.vl" files recursively from the directory where Veryl.toml is placed at. mod.vl based approach specify is more explicit, but maybe bother.

I think there are some advantages of mod.vl style.

• file selection through ifdef

like below:

#[ifdef(AAA)]
mod for_aaa;
#[ifndef(AAA)]
mod for_not_aaa;

• entry point of project

Currently, there is no entry point of project. So doc comment about the whole project can't be placed. If there is entry point (ex. src/mod.vl), the doc comment can be placed at it.

There are a concern too.

• mod.vl vs [dirname].vl

In Rust, there are mod.vl style and [dirname].vl style. [dirname].vl style was added because many mod.vl tabs are appeared in tabbed editor and can't be identified. I prefer mod.vl style, but someone will not.

Syntax

mod and use may be confusable with module and import of SystemVerilog. I wonder whether the keyword should be kept or changed.

[rbkettlewell]

You bring up some great points. Firstly, to the question about adding mod.vl files being a potential nuisance, I agree some designers may view it this way and prefer a flat namespace based on what they are used to. Others, like myself, would want to adopt a newer style.

Explicit file structure

• What do you think about enabling two behaviors in Very after recursively searching the directory structure for all "*.vl" files:

  1. If no mod.vl, lib.vl found => default flat namespace
  2. If mod.vl and lib.vl found => enable module hierarchy

• Entry point of project This is a good point, in the core example I should have added src/lib.vl. I think this is preferable over mod.vl at the highest level in the hierarchy. It both informs intent and borrows from Rust's implementation.

• mod.vl vs [dirname].vl I see the tabbed editor concern. My recommendation would be to add the mod.vl implementation first and then if requested add the other [dirname].vl style if the effort is not considerable.

Syntax

• mod I could be convinced either way, but here are some potential reasons why the mod keyword is preferable in the mod.vl and lib.vl:

1. Its not overloaded with module and thus clearly separates a logical grouping of modules from a design module which could be instantiated.
2. It is recognizable to anyone who has Rust exposure.

If its preferred to use module throughout I would suggest updating mod.vl to module.vl

• use Reflecting about this, I think import should be maintained instead of use. This requires less mental burden for the developer, however the transpilation will have to be aware to erase these explicit module imports which would be invalid in System Verilog.