Add `-file_list` compiler option for flexible multi-file compilation

[kbkpbot]

Describe the feature

Currently, the V compiler supports two main compilation modes:

• v dir - compiles all .v files in a directory

• v a.v- compiles a single file

I propose adding a new -file_list option to provide more flexible control over which files are included in compilation, particularly useful for projects with multiple entry points or specific file combinations.

v a.v -file_list "b.v,c.v,dir"

Where:

a.v is the entry point/main file

-file_list accepts a comma-separated list containing:

• Individual .v files (e.g., b.v, c.v)

• Directories (e.g., dir) - all .v files within the directory will be included

Use Case

1. Multiple entry points: Compile different main files with shared modules without including unrelated files
2. Selective compilation: Include specific files from different directories
3. Build flexibility: Better control over compilation scope for complex projects
4. IDE/tool integration: Enable language servers to compile exact file subsets

# Compile main1.v with specific helpers and a utils directory
v main1.v -file_list "helper.v,utils/"

# Compile test runner with test files from multiple directories  
v test_runner.v -file_list "tests/unit/,tests/integration/,test_helpers.v"

# Complex project with modules from different locations
v app.v -file_list "lib/core/,lib/ui/,config.v,third_party/"

Some discussion at #25703

Proposed Solution

No response

Other Information

Alternatives Considered

-files (shorter but less descriptive)
-extra_files (misleading since first file is the main entry point)

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

Version used

V 0.4.12 af62364.982681c

Environment details (OS name and version, etc.)

V full version	V 0.4.12 af62364.982681c
OS	linux, Ubuntu 24.04.3 LTS
Processor	8 cpus, 64bit, little endian, Intel(R) Core(TM) i7-9700 CPU @ 3.00GHz
Memory	12.26GB/15.51GB
V executable	/media/HD/github/kbkpbot/v/v
V last modified time	2025-11-09 10:47:54
V home dir	OK, value: /media/HD/github/kbkpbot/v
VMODULES	OK, value: /home/mars/.vmodules
VTMP	OK, value: /tmp/v_1000
Current working dir	OK, value: /media/HD/github/kbkpbot/v
Git version	git version 2.43.0
V git status	weekly.2025.45-35-g33e129b1
.git/config present	true
cc version	cc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
gcc version	gcc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0
clang version	Ubuntu clang version 18.1.3 (1ubuntu1)
tcc version	tcc version 0.9.28rc 2025-02-13 HEAD@f8bd136d (x86_64 Linux)
tcc git status	thirdparty-linux-amd64 696c1d84
emcc version	N/A
glibc version	ldd (Ubuntu GLIBC 2.39-0ubuntu8.6) 2.39

Note

You can use the 👍 reaction to increase the issue's priority for developers.

Please note that only the 👍 reaction to the issue itself counts as a vote.
Other reactions and those to comments will not be taken into account.

[spytheman]

The listed use cases and their benefits are not clear to me:

1. Multiple entry points

That is already covered by v /full/path/to/entry.v

2. Selective compilation: Include specific files from different directories

That may be valuable in some cases, but is already covered by -path imho.

3. Build flexibility: Better control over compilation scope for complex projects
4. IDE/tool integration: Enable language servers to compile exact file subsets

I want V to remain directly usable from the command line, without requiring a full IDE/separate build system. What is the additional control and integration that you need, that is not provided by v folder/ or v file.v ?

[spytheman]

Can you please provide a more concrete example, where the fine grained control would have been useful, and where the already existing -path or v folder/ were not enough?

[kbkpbot]

$ tree x
x
├── main1.v
├── main2.v
├── mod
│   └── mod.v
├── part_a.v
└── part_b.v

2 directories, 5 files

A sample project, it can be compiled with "main1.v + part_a.v + part_b.v + mod" or "main2.v +part_a.v + part_b.v + mod".

main1.v and main2.v

module main
import mod

fn main() {
        x := mod.Mod{}
        dump(x)


        part_a := AS{}
        dump(part_a)

        part_b := BS{}
        dump(part_b)
}

part_a.v:

module main

pub struct AS{}

part_b.v:

module main

pub struct BS{}

mod.v:

module mod

pub struct Mod {}

[kbkpbot]

Even worse, vls will copy main1.v to /tmp/main1.v and then call v /tmp/main1.v for checking. In this case, it has no idea where part_a.v and part_b.v are located.

v /tmp/main1.v -path "/path/to/src"

will find the mod, but not part_a.v and part_b.v.

$ v main1.v -path "/home/mars/v/x|@vlib"
main1.v:9:12: error: unknown type `AS`
    7 |
    8 |
    9 |     part_a := AS{}
      |               ~~~~
   10 |     dump(part_a)
   11 |
main1.v:9:12: error: unknown struct: AS
    7 |
    8 |
    9 |     part_a := AS{}
      |               ~~~~
   10 |     dump(part_a)
   11 |
main1.v:10:7: error: dump expression can not be void
    8 |
    9 |     part_a := AS{}
   10 |     dump(part_a)
      |          ~~~~~~
   11 |
   12 |     part_b := BS{}
main1.v:12:12: error: unknown type `BS`
   10 |     dump(part_a)
   11 |
   12 |     part_b := BS{}
      |               ~~~~
   13 |     dump(part_b)
   14 | }
main1.v:12:12: error: unknown struct: BS
   10 |     dump(part_a)
   11 |
   12 |     part_b := BS{}
      |               ~~~~
   13 |     dump(part_b)
   14 | }
main1.v:13:7: error: dump expression can not be void
   11 |
   12 |     part_b := BS{}
   13 |     dump(part_b)
      |          ~~~~~~
   14 | }
If the code of your project is in a folder with multiple .v files, try `v .` instead of `v main1.v`

[spytheman]

What will provide the information about what permutation/explicit selection of files in that project, is the correct one for each top level program in it?

How would VLS (or another language server) know that too?

[kbkpbot]

The correct file selection for each top-level program in a project can be determined through several mechanisms:

1. Explicit Configuration

• Project Configuration Files: Use existing project files (v.mod, package.json, Cargo.toml, etc.) that already define project structure and dependencies
• Dedicated LSP Configuration: Create language server-specific config files (e.g., .vlsconfig) that explicitly map entry points to their required files

Example VLS configuration approach:

{
  "programs": {
    "program1": {
      "entry": "main1.v",
      "includes": ["part_a.v", "part_b.v", "mod/"],
      "excludes": ["main2.v"]
    },
    "program2": {
      "entry": "main2.v", 
      "includes": ["part_a.v", "part_b.v", "mod/"],
      "excludes": ["main1.v"]
    }
  }
}

2. Implicit Discovery Methods

• Import/Dependency Analysis: Automatically trace import statements to build dependency graphs.

I haven't found a robust solution for handling cases where a single module main is split across multiple files (part_a.v, part_b.v) that reside in the same directory.

[kbkpbot]

Because currently vls copy main1.v to /tmp/main1.v, it need to compile following files:

/tmp/main1.v                        # not /path/to/src/main1.v , and this must exclude from compilation
/path/to/src/part_a.v
/path/to/src/part_b.v
/path/to/src/mod/mod.v

Even we can create a main1.vls.v at the src dir, it also need to compile following files:

/path/to/src/main1.vls.v                        # not /path/to/src/main1.v , and this must exclude from compilation
/path/to/src/part_a.v
/path/to/src/part_b.v
/path/to/src/mod/mod.v