Should `import Cpp inline` be part of the declaration list rather than the preamble?

[zygoloid]

Summary of issue:

The toolchain currently allows import Cpp inline .... While the leads have informally agreed that we like this functionality and there's not been a lot of pushback on the syntax, it's not gone through the proposal process yet. We currently treat it as an import directive, so it goes at the start of the file with other imports (in any order), not in the declaration list of the file.

I think we should reconsider that: instead of inline C++ being part of the import sequence, it should be a declaration, it should appear after all imports, and it should be allowed to be interleaved with Carbon declarations.

Details:

We generally want our imports to be order-independent. For Carbon imports, they essentially are already. C++ imports are not -- later imported headers can see earlier ones -- but we don't necessarily intend for that to be the case, and I think we should be open to modeling C++ imports as instead building and importing a C++ header unit. But inline C++ code isn't like that -- we want it to be order-dependent, and to be able to name both C++ and Carbon entities introduced by earlier imports.

Also, inline C++ has turned out to be extremely useful for invoking C++ file-scope macros, such as ABSL_FLAG. When these can be expanded at the start of the file, this works great, but some of these macros are doing things like registering classes with some kind of global registry, and those macros would ideally be expanded either at the end of the file or immediately after the class definition.

I think we should answer three questions before proceeding with a proposal here:

• Do we want an inline C++ facility? [Suggested answer: yes]
• Where should it be usable? [Suggested answer: as a top-level declaration]
• What syntax should we use? [If it doesn't live with the other import directives, perhaps import is the wrong choice?]

Any other information that you want to share?

Possible alternative syntaxes:

Today's syntax

import Cpp inline '''
// your c++ code here
''';

Using inline as a member of Cpp (note that this would be a top-level declaration with no introducer!)

Cpp.inline '''
// your c++ code here
''';

Using inline as a keyword

inline Cpp '''
// your c++ code here
''';

Same but with package as well

inline package Cpp '''
// your c++ code here
''';

Using extern (note this would be extern not followed by an introducer!)

extern Cpp '''
// your c++ code here
''';

Using extern with package

extern package Cpp '''
// your c++ code here
''';

It might also be worth considering how to support file-scope inline asm at the same time, as it may be reasonable to use a similar syntax there.

[jonmeow]

In your example:

Today's syntax

package Cpp inline '''

Is this supposed to be import Cpp inline?

Also, noting the three questions you list, is it intentional that things questions like "how does this affect name poisoning" are out-of-scope?

[zygoloid]

Is this supposed to be import Cpp inline?

Fixed, thanks.

Also, noting the three questions you list, is it intentional that things questions like "how does this affect name poisoning" are out-of-scope?

If there's a leads question there that would be useful to answer as input to a proposal, I think that's in scope. I can think of a couple of ways that poisoning might come up.

One is that a C++ name could change meaning after a use in Carbon:

import Cpp inline '''
namespace A {
  namespace {
    int f();
  }
}
int g(...);
''';
// OK, calls A::B::f.
fn F1() { Cpp.A.f(); }
fn G1() { Cpp.g(0); }
import Cpp inline '''
namespace A {
  // Error here? We already assumed `A::f` does not exist.
  int f();
}
// Error here? We already assumed `g(0)` would call `g(...)`.
int g(int);
''';
// Error here? Does this now find `A::f`? Does it still find `A::B::f`?
fn F2() { Cpp.A.f(); }
// Error here? Does this now call `g(int)`? Does it still call `g(...)`?
fn G2() { Cpp.g(0); }

The other is that a Carbon name could change meaning after a use from C++. (Can that happen?)

In either case, I think that it's desirable to diagnose, but we should look at what the implementation can reasonably support (without making invasive changes to Clang) and that should be a factor in the decision.

[jonmeow]

The other is that a Carbon name could change meaning after a use from C++. (Can that happen?)

The overload example you give is where my mind was. To extend your example of overloads to affect a Carbon name, it kind of depends on what you consider alias G = Cpp.g;; in other words, a name reference from C++ could be aliased or be a parameter to a generic, so the way that name reference is treated can affect the meaning of the Carbon entity. But I think that's likely the closest that's supported, at least right now.

(caveat: in the future you could allow metaprogramming constructs that build entities and are also callable from C++)

[zygoloid]

I think maybe the simplest rule might be: you can't add C++ overloads to a name after Carbon "sees" the overload set. In practice we take a snapshot of the overload set on first name lookup, and then we use that cached value and don't check again later. In order to enforce the poisoning rule, we'd need to redo all the C++ lookups a second time at the end of the file and make sure we find the same things (at least, in the case where there have been more inline C++ fragments after the first lookup, which we can track by tracking the index of the last CppOverloadSetId that was created before the last inline C++ fragment was parsed).

[zygoloid]

We discussed some more possible alternative syntaxes.

Just a string literal (with or without a terminating ;):

'''c++
int n;
'''

In this syntax, the filetype marker in the block string literal might be taken into account.

Using markdown syntax instead of a string literal:

```c++
int n;
```

This is probably the most direct and concise notation we could use. It also might extend to an inline syntax such as Cpp.`LOG(INFO)` << "foo" << "bar"; if we wanted to explore that.

Downside of these: unless we use Cpp as the filetype marker, these would be introducing names in the scope Cpp (and potentially declaring the scope Cpp itself) without mentioning that name. And they potentially seem a bit too implicit / magical.

The leading syntax at the moment seems to be extern Cpp <string-literal>;.

[chandlerc]

I agree to the suggested answers to the first two questions.

FWIW, I'm currently leaning toward both extern Cpp and inline Cpp above the alternatives.

Markdown fences are quite tempting -- especially to eventually allow inline usage. But I worry it's too clever / subtle. The Cpp name doesn't worry me as much -- I think we could reasonably expect that to be provided by the prelude similarly to Core.

Between extern and inline, I'm super torn. Very different arguments point in fairly opposite ways....

• extern is how analogous things are done in C++, why deviate?
• inline much more closely matches the expected semantics -- this is C++ code that is part of the current Carbon file / translation unit, not some other one.
• Both seem to work well for inline assembly, etc.

Maybe worth considering with the syntax choice here: we're going to need a way to export C++ names from a Carbon API file. I could imagine using export as a keyword for that, or extern. But even if using export, having the pair of export and extern with two very different meanings seems somewhat concerning.

[zygoloid]

One consideration around inline is that this would be the only current use of the inline keyword in the Carbon syntax. Given how that keyword is used in C and in C++, this seems like a potentially surprising sole meaning for the keyword to have in Carbon. That said, I think I'd want to reserve inline as a keyword even if we had no current uses of it in the grammar, since I think it's somewhat likely we'll want it as a keyword eventually. (It's also very low cost to take as a keyword since it's a C++ keyword.) But this is also the status quo -- the only use of inline at the moment is in package Cpp inline ... directives.

It's also not clear whether this use of inline would be consistent or compatible with any other future usage we might want to make for this keyword for function inlining. But I think that, at worst, inline Cpp versus inline fn F is no worse than extern Cpp versus extern fn F, so this doesn't really argue for extern over inline.

Despite the above, I think I've become convinced that inline is a better choice than extern. These code blocks really are much more "inline" than "extern[al]", and this functionality really is analogous to "inline assembly". I expect we will describe this functionality to programmers as "inline C++", so using that terminology in the source syntax makes sense to me.

Another word that's synonymous with "inline" might also work -- nested, embedded, inset, builtin, encapsulated, aggregated, component, ... -- but all the options I could find either have pretty strong incompatible meaning or don't seem to work well. Unfortunately "a thing within another thing" is a common pattern :)

[chandlerc]

Let's call this decided with the rationale from the prior comment, and landing on:

inline Cpp '''
...
'''

[zygoloid]

Reopening: it seems that we didn't reach alignment on whether this syntax should have a trailing semicolon or not.