Add imports with namespacing, pub/use, and C3 linearization

[KyrylR]

Project

compiler

Describe the feature

Reasoning

The main reasoning is to enable an analogue of the OpenZeppelin library to exist in the SimplicityHL ecosystem.

The idea is that the code will be distributed via crates.io and will allow developers to speed up the development of applications.

Primarily, it will significantly increase code reusability. If a project is heavily focused on security, it will be able to “flatten” the code and use all the functions without external dependencies.

Semantics

• Visibility:
  • pub fn makes a function importable from other files; fn is file-private.
  • pub use re-exports imported symbols; use only brings them into the local scope.
  • pub type exports a type alias (optional but included for consistency).
• use forms:
  • use m::name;, use m::name as alias;, use m::{a, b as c};, use m::*;
  • pub use m::{a, b as c};, pub use m::*; (re-export)
• Merging with C3 linearization when resolving pub use ...::* across a graph of re-exports. First wins according to the MRO; conflicts require explicit aliasing.
• Conflicts:
  • A local use * that causes a collision → error unless explicitly aliased.
  • Re-export collisions are resolved by C3 order; later entries are ignored unless aliased.
• Path resolution: relative to the importing file’s directory, then search -I directories in CLI order; append .simf if missing.
• Running: Only files defining a zero-arg unit fn main are runnable. Libraries (no main) are accepted under --check; attempting to run them results in an error.

Overall, this feature can be delivered in milestones, so we can gradually add support.

Even though the StarkWare team introduced macros, in the long term it is much more beneficial to have official compiler support for imports. It can already be seen that their compiler version is outdated.

[KyrylR]

@schoen I believe it’s the same as for infix ops (in terms of need), we want to have the ability to import other .simf files/types

I’d like to have your opinion on this

The core motivation is to start building std and sharing some helpful tools with other devs

[schoen]

In general I think imports are very desirable. I don't know if this approach is more complicated than people will need. Perhaps it depends on how complex we imagine that SimplicityHL contracts are likely to get (with some of these features being most useful in highly complex contracts with significant numbers of source files and significant amount of code reuse between projects).

My understanding is that the StarkWare people (in https://github.com/starkware-bitcoin/simply) were apparently literally reusing cpp, the classic C language preprocessor, and repurposing C's #include and #define as implemented in cpp (as it doesn't really check the syntax of the rest of your programming language). I believe even that would be an improvement over what we currently have for simc, but it takes the syntax in a different direction than you suggest and is a bit more limited.

I agree that your more complete feature set is more useful if we have reasonably large-scale code reuse, so I'd also be interested to hear other people's predictions about that.

[apoelstra]

I think @KyrylR's proposal is directionally the right approach. We want namespacing and modules to help with good code hygeine, which is important almost regardless of scale.

It's true that we probably won't be dealing with 100000-line codebases where the awful scalability of cpp would hurt us, but even for small codebases we'll run into problems caused by text-substitution being a terrible way to do symbol importing (name collisions, poorly-targeted compiler error messages, weird dependencies on the order of inclusions, near-impossibility of linting unused imports, etc).

Separately we may want some sort of macro/codegen system, and I prefer cpp to Rust's approach there, where Rust managed to make a (substantially) even less readable syntax while failing to match even basic functionality like string concatenation, let alone including loops or anything more useful that cpp lacks.