Why paths specified on the CLI are not relative to `--base-path`?

i am unclear on what ‘root of source tree’ means when using the base-path flag

$(npm bin)/solcjs --bin --output-dir build --base-path ./contracts Test.sol returns : Error reading Test.sol: Error: ENOENT: no such file or directory, open 'Test.sol'

$(npm bin)/solcjs --bin --output-dir build --base-path . contracts/Test.sol works and compiles contract

[cameel]

You can find detailed docs about how path resolution works in Import Path Resolution.

In short, the main purpose of base path is to be the location that direct imports are resolved against. I.e. if the base path is /some/path/, and you have import "a/b/c.sol" in your contract, the compiler will look for the file in /some/path/a/b/c.sol on disk.

Base path is not the same thing as your working directory even though by default they have the same value. When they’re different, on the command-line it’s the working directory that counts:

cd /some/other/path
solc --base-path /some/path/ a/b/c.sol

In the above a/b/c.sol refers to /some/other/path/a/b/c.sol because that’s how everyone expects relative paths to work on the CLI. It does not magically become /some/path/a/b/c.sol

[cameel]

Why not. Feel free to submit a PR to adjust that. We could add a sentence or two on that and maybe link to specific bits in the import path resolution docs. Like, the --base-path option could be a link to the section on base path and we could also link to https://docs.soliditylang.org/en/latest/path-resolution.html#cli-path-normalization-and-stripping.