Fill in Problem and Background sections

Author: ivanaivanovska

proposals/p6382.md

@@ -15,6 +15,11 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 -   [Abstract](#abstract)
 -   [Problem](#problem)
 -   [Background](#background)
+    -   [Macros in C++](#macros-in-c)
+        -   [Object-like macros](#object-like-macros)
+        -   [Function-like macros](#function-like-macros)
+        -   [Predefined macros](#predefined-macros)
+    -   [Swift / C interop [GitHub][documentation]](#swift--c-interop-githubdocumentation)
 -   [Proposal](#proposal)
 -   [Details](#details)
 -   [Rationale](#rationale)
@@ -24,18 +29,86 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Abstract
 
-TODO: Describe, in a succinct paragraph, the gist of this document. This
-paragraph should be reproduced verbatim in the PR summary.
+This proposal addresses importing object-like C/C++ macros into Carbon.
 
 ## Problem
 
-TODO: What problem are you trying to solve? How important is that problem? Who
-is impacted by it?
+C/C++ object-like macros are used to define constants, conditional compilation,
+header guards, etc. and are common for low-level, cross-platform libraries, with
+C like APIs. Despite the recommendations for replacing them in C++ with safer
+techniques (for example `constexpr`), they remain to be present in C++ code
+bases. Of particular interest for the interoperability are cases such as macros
+present in the APIs of the standard C++ library (for example error codes in
+`<errno.h>`), which can't be easily changed, but remain to be widely used in
+low-level C++ libraries. A mechanism for properly importing and handling these
+macros is necessary for a seamless interoperability.
 
 ## Background
 
-TODO: Is there any background that readers should consider to fully understand
-this problem and your approach to solving it?
+### Macros in C++
+
+Macros are defined with the `#define` directive and processed by the
+preprocessor, which replaces the occurrences of the defined identifier with a
+replacement-list. There are two types of macros: _object-like_ and
+_function-like_ macros. The directive `#undef` undefines a defined macro.
+
+#### Object-like macros
+
+```
+#define identifier replacement-list (optional)
+```
+
+Replacement-lists can have elements that are:
+
+-   Literals: integer, floating-point, string, char, bool etc.
+-   Non-literal types: structs, classes etc.
+-   Identifiers: pointing to other macros, variables, types, keywords etc.
+-   Operators: `+, -, <<, >>, |` etc. to one or more elements.
+
+#### Function-like macros
+
+```
+#define identifier(parameters) replacement-list (optional)
+#define identifier(parameters, ...) replacement-list (optional)
+#define identifier(...) replacement-list (optional)
+```
+
+The syntax of function-like macros is similar to the syntax of a function call.
+They accept a list of arguments and replace their occurrence in the
+replacement-list.
+
+As this is only a text replacement, it can lead to unexpected behaviour if the
+arguments are not properly separated with brackets.
+
+In function-like macros, the operators `#` and `##` enable:
+
+-   `#operator (stringification)` - the arguments of the macro are converted to
+    a string literal without expanding the argument. When `#` is used in front
+    of a parameter in a macro definition (`#param`), the preprocessor replaces
+    `#param` with the argument tokens as a string literal.
+
+-   `##operator (concatenation or token pasting)` - two tokens are merged in a
+    single token during a macro expansion. For example, when `a##b` is used as
+    part of the macro definition, the preprocessor merges `a` and `b`, removing
+    any white spaces in between to form a single token. When some of the tokens
+    on either side of the `##` operator are parameter names, they are replaced
+    by the actual argument before the execution of `##`. This is used for
+    example to create new identifiers like variables, function names etc. and in
+    general to avoid creating repeated boilerplate code.
+
+#### Predefined macros
+
+There are also predefined macros available in every translation unit. Examples
+include: `__cplusplus`, `__FILE__`, `__LINE__`, `__DATE__`, `__TIME__` etc.
+
+### Swift / C interop [[GitHub](https://github.com/swiftlang/swift/blob/main/lib/ClangImporter/ImportMacro.cpp)][[documentation](https://developer.apple.com/documentation/swift/using-imported-c-macros-in-swift)]
+
+Swift supports importing object-like C macros as global constants. Macros that
+use integer, floating-point and string literals are supported. Also simple
+operators like `+, -, <<, >>` etc. between literals or macros are supported.
+
+Function-like macros are not supported. Instead, using Swift functions and
+generics is recommended.
 
 ## Proposal