Code and name organization

[jonmeow]

• RFC
• Decision request
• Examples doc
• Approval announcement

Files, packages, libraries, and imports for Carbon.

Contributors: chandlerc, fowles, tkoeppe, zygoloid

[jonmeow]

Quick reminder all! This proposal is a WIP, and I have not posted it to ideas. I was simply copying a legacy doc for visibility. As noted in the PR description, I have not had time to edit it, and that may take a bit. I hope a rewrite will address your comments, @josh11b @tkoeppe !

[jsiek]

The goals/philosophy should include something that might be called "the library user's bill of rights".
Some of the following is perhaps stated elsewhere, but here is a great place for it, and furthermore, there
is a long and rich history of programming language designs getting this wrong! (e.g. C++ and Haskell.)

The person importing a library should have complete control over which names come into scope
and the ability to rename the imported entities. The crucial scenario to think about is that the
person is importing from two libraries and those two libraries were developed by people that don't know or care about each other, or perhaps even dislike each other! So the two libraries may have lots of name conflicts. But nevertheless, it should be possible for someone to import both libraries and apply the appropriate renamings to resolve the conflicts they care about.

[jonmeow]

Name conflicts are noted in the actual proposal file (p0107.md) as out of scope for this proposal; either the aliasing or name lookup proposal should address it more directly. While it's an important issue, they are nuanced discussions that require a more complex discussion, this proposal is already quite large, and there's dissent around whether renaming imports would be necessary. I want to keep the proposal's scope at a level where it's straightforward to review, and so it is not a goal addressed by this feature design, at least at present.

I'm wary too of the meaning of "complete control". I think this overlaps with the idea of renaming, as responded to above.

Note, I think the goal on line 96 captures what you're trying to address, as far as it affects this design:

-   We should support libraries adding new structs, functions or other
    identifiers without those new identifiers being able to shadow or break
    existing users that already have identifiers with conflicting names.

Please make suggestions on phrasing if this isn't direct enough for you, although I'm trying to keep possible implementations of this goal to the rest of the design.

Please also note the "Broader imports, either all names or arbitrary code" alternative, which dives into the related tradeoffs a little more.

[jsiek]

If there's a better place to address this concern, that's fine.

Regarding the goal on line 96, that doesn't quite cover this concern
because it only talks about the consequences to existing users of adding new identifiers.
But this concern also applies to new users.

[jonmeow]

Responding to comments

[jonmeow]

Name conflicts are noted in the actual proposal file (p0107.md) as out of scope for this proposal; either the aliasing or name lookup proposal should address it more directly. While it's an important issue, they are nuanced discussions that require a more complex discussion, this proposal is already quite large, and there's dissent around whether renaming imports would be necessary. I want to keep the proposal's scope at a level where it's straightforward to review, and so it is not a goal addressed by this feature design, at least at present.

I'm wary too of the meaning of "complete control". I think this overlaps with the idea of renaming, as responded to above.

Note, I think the goal on line 96 captures what you're trying to address, as far as it affects this design:

-   We should support libraries adding new structs, functions or other
    identifiers without those new identifiers being able to shadow or break
    existing users that already have identifiers with conflicting names.

Please make suggestions on phrasing if this isn't direct enough for you, although I'm trying to keep possible implementations of this goal to the rest of the design.

Please also note the "Broader imports, either all names or arbitrary code" alternative, which dives into the related tradeoffs a little more.

[josh11b]

Suggested change

	names in the current file: Name lookup is likely to address this better,
	names in the current file: A separate name lookup proposal will address this directly,

[jonmeow]

I prefer "is likely to" because "will ... directly" sounds like a really firm statement about the future, one which I don't think I'm going to be responsible for enforcing.

[josh11b]

The most important word I wanted to include was "proposal" after "name lookup". Otherwise this sentence doesn't make sense.

[jonmeow]

Ah, clarified "name lookup design".

[jonmeow]

Updated around the decision:
https://github.com/carbon-language/carbon-lang/pull/107/files/e9f4404c7af1eb0493263ca1a0acbf4c2fff71e1..fe4c7d25f92948940ef27a0fab4d14895bce8472

[chandlerc]

I had thought we would want to use the exact API file's path? That is, include the .carbon? But maybe not.

(I don't feel strongly about this either way, and don't think this is super important, mostly want us to be intentional in the choice)

[jonmeow]

I think we should omit it -- however, that can always change in another, more targeted proposal. I do admit an assumption that we wouldn't want to repeat file extensions, if possible. This is particularly notable if we expect all impl files to be prefixed with the library name, e.g. "Math/Algebra.impl.carbon", "Math/Algebra.impl.MyDetail.carbon", at which point adding the ".carbon" to the library will end up obfuscating the path.

[josh11b]

I agree it should be omitted, as it is just boilerplate noise. Including it will make it harder to support filesystems that use . as a directory separator.

[chandlerc]

Should we mention that the API file path above is relative to some package-specific root? or not at all?

[jonmeow]

I'd argue for leaving that to be resolved later. I think "package-specific" could imply that each package has its own root, and I believe the discussion so far had been:

1. A package may have multiple roots, such as one for human-authored files and one for auto-generated files. This could also be multiplied by separating public and package-internal APIs.

2. A given root could arguably contain multiple packages, as was suggested for the Google use-case.

Thus the idea of making a quick remark about a package-specific root seems pretty limiting, and one that should be delayed for further proposals. I can particularly see how #2 may get arguments.

[sidney13]

Approved on 2020-10-06. Approval announcement

Per discussion, chandlerc said he doesn't see a need to review again