Add import Cpp; for C++ built-in entities

proposals/p6331.md

@@ -0,0 +1,112 @@
+# Add `import Cpp;` for C++ built-in entities
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+[Pull request](https://github.com/carbon-language/carbon-lang/pull/6331)
+
+<!-- toc -->
+
+## 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)
+
+<!-- tocstop -->
+
+## 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 "<cpp_builtins>";`)**: 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.