diff --git a/proposals/p6331.md b/proposals/p6331.md new file mode 100644 index 0000000000000..21106f5d103b9 --- /dev/null +++ b/proposals/p6331.md @@ -0,0 +1,112 @@ +# Add `import Cpp;` for C++ built-in entities + + + +[Pull request](https://github.com/carbon-language/carbon-lang/pull/6331) + + + +## Table of contents + +- [Abstract](#abstract) +- [Problem](#problem) +- [Background](#background) +- [Proposal](#proposal) +- [Details](#details) + - [Activated Entities](#activated-entities) + - [Interaction with Other Imports](#interaction-with-other-imports) +- [Rationale](#rationale) +- [Alternatives Considered](#alternatives-considered) + + + +## Abstract + +This proposal introduces an `import Cpp;` directive. This directive makes C++ +built-in types, such as `long`, available in Carbon through a clear and explicit +mechanism. + +## Problem + +Carbon's C++ interoperability requires seamless, bidirectional access. The +primary mechanism for this is `import Cpp library "header.h";`, which parses a +C++ header file and maps its AST into Carbon's `Cpp` namespace. + +However, this mechanism falls short when a developer only needs C++ built-in +types (for example, `long`, `long long`, `unsigned long`), as these are not +defined in any header file. + +Furthermore, some C++ types are **nominally distinct**. For example, on many +64-bit systems, `long` and `long long` share the same 64-bit representation, but +C++ treats them as distinct types - a critical feature for function overloading. +If Carbon were to map both types to its canonical `i64`, this semantic +distinction would be lost, breaking interoperability. + +To address this, Carbon must provide its own distinct mirror types, such as +`Cpp.long` and `Cpp.long_long`. The language currently lacks a clear and direct +way to "activate" or import only these compiler-provided, built-in C++ entities. +While `import Cpp inline "";` can achieve this, it is an unintuitive and +indirect solution. + +## Background + +Currently, C++ built-in types can be brought into the `Cpp` namespace using +`import Cpp inline "";`. This works because the `inline` import implicitly makes +the built-in types available. However, this is a side effect of the `inline` +import's behavior, not an obvious or intentional feature. + +## Proposal + +We propose a new import directive: + +```carbon +import Cpp; +``` + +This file-level statement instructs the Carbon compiler to populate the `Cpp` +namespace with all C++ built-in entities required for interoperability. This +acts as a compiler-level activation and does not involve reading any files. + +## Details + +### Activated Entities + +The set of entities activated by `import Cpp;` is determined by the compiler's +interoperability model. This will include C++ primitive types, including those +necessary to preserve nominal distinction (for example, `Cpp.long`, +`Cpp.unsigned_long`, `Cpp.long_long`). + +### Interaction with Other Imports + +The `import Cpp;` directive is **not** mutually exclusive with +`import Cpp library "..."` or `import Cpp inline "..."`. + +Both `import Cpp library "..."` and `import Cpp inline "..."` will implicitly +trigger the effects of `import Cpp;`. Since any C++ code is likely to use +built-in types, making them available by default enhances the user experience. + +## Rationale + +**Explicitness over Magic:** This directive provides a clear, non-magical +opt-in. It prevents the `Cpp` namespace from being automatically available to +users who have not explicitly declared their intent to use C++ interoperability, +aligning with Carbon's "principle of least surprise", which is part of Carbon's +goal to have +[Code that is easy to read, understand, and write](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write). + +## Alternatives Considered + +1. **Use `import Cpp inline "";`:** Rejected. This approach is not obvious and + relies on a side effect of the `inline` import implementation, rather than + being a clear, intentional feature. +2. **Implicit Activation:** Rejected. Automatically making `Cpp.long` available + in all files would be unexpected and doesn't follow "principle of least + surprise", which is part of Carbon's goal to have + [Code that is easy to read, understand, and write](https://github.com/carbon-language/carbon-lang/blob/trunk/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write). +3. **Magic Header (`import Cpp library "";`)**: Rejected. This is + a confusing anti-pattern. The `library` keyword implies that a file is being + parsed, which is not the case here, breaking the user's mental model.