Path resolution docs (current state only) #11263
Conversation
docs/layout-of-source-files.rst
Outdated
|
|
||
| import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping; | ||
| Unlike in case of a direct import, the compiler does assume that the import path is actually a path. |
There was a problem hiding this comment.
Isn't this complicating the isuse a little? Whta does it mean to assume it is a path? Isn't the rule just "if it starts with ./ or ../, append it to the path and simplify"?
There was a problem hiding this comment.
It assumes it's structured like a path, e.g. expects path separators or squashes ../ segments. It's even processed internally using boost::filesystem.
docs/path-resolution.rst
Outdated
| The import path is translated into a source unit name and then the compiler uses the name | ||
| to look up the file in its virtual filesystem. | ||
| The are two types of imports, each with different rules for this translation: | ||
| :ref:`direct imports <direct-imports>` let you specify the full source unit name while in |
There was a problem hiding this comment.
Because when I see absolute imports, I think about absolute paths in the real filesystem and I really want to avoid that connotation. Thinking about absolute imports was really giving me the wrong idea about how this works when I was trying to understand this initially. I think we should have a different word to refer to them.
| .. note:: | ||
|
|
||
| Do not confuse relative imports with relative paths. | ||
| Both ``util.sol`` and ``./util.sol`` specify relative paths on disk but these paths are treated |
There was a problem hiding this comment.
But this depends on the compiler binary. This section is rather confusing - maybe we should clarify it as early as possible and talk about "filesystem paths relative to the current working directory"
There was a problem hiding this comment.
I'm leaving it here for now but I'll probably rewrite it for the blog post anyway. In #11442 I removed it almost completely and just added a short note.
|
|
||
| - All the ``./`` segments are removed. | ||
| - Every ``../`` segment backtracks one level up in the hierarchy. | ||
| - Multiple slashes are squashed into a single one. |
There was a problem hiding this comment.
Is this done to the full path? Maybe we should change that and only modify the initial segment.
There was a problem hiding this comment.
Only the part that's in the import statement. The parent path it's combined with is not normalized. This is explained in a note later in the text.
Generally in this rewrite I tried to keep it simple in the initial explanations and only went into detail later in the text or in note/warning boxes.
|
|
||
| .. warning:: | ||
|
|
||
| The root of the virtual filesystem is an empty path, not ``/``. |
There was a problem hiding this comment.
Maybe rephrase: An initial / is not required (and also not recommended) for specifying absolute paths in the virtual filesystem.
There was a problem hiding this comment.
But this would sound like it's optional and the two are equivalent. The empty path does work like the root for us. See for example what happens when you go beyond the root - you get to "" not /.
There was a problem hiding this comment.
I have rewritten this section completely in #11442.
…ppings, base path and standard input
…ng remappings, base path and standard input
…ng remappings, base path and standard input
… source layout docs
cameel
force-pushed
the
path-resolution-docs-current-state
branch
from
7999aaa to
702e026
Compare
…ng remappings, base path and standard input
… source layout docs
…ng remappings, base path and standard input
cameel
force-pushed
the
path-resolution-docs-current-state
branch
from
702e026 to
81e7ae4
Compare
|
I have just pushed a new version with all the points above addressed. All the changes are in fixups. I'm going to close it now and split in two parts. One will go into a separate PR with the excessive examples and explanations removed. The other will become a blog post. |
|
Closing in favor of #11442. |
Replaces #11105.
Related to #11138, #11036 and #9353.
This is a reworked version of #11105 that only describes the current state, without any proposed modifications. The goal is to get it merged and included in a release before we start changing how this stuff works.
To implement #11105 (review), I have created a separate section called "Path Resolution" in the side menu. The "Layout of a Solidity Source File" now only contains a short summary of the part needed to understand import paths.
The biggest change compared to the original docs is that any mention of absolute imports has been removed and now I only distinguish between "direct" and "relative" imports. I have also moved a lot of the extra details to notes/warnings to separate them from the main flow of the text and simplified them slightly where I could.