From d8892a0814d6c3c32f83926ebddc4802528cb7b0 Mon Sep 17 00:00:00 2001
From: Peter Donovan <peter@xronos.com>
Date: Thu, 29 Feb 2024 16:00:53 -0800
Subject: [PATCH] Initial commit for user-facing-include-path RFC

---
 0000-user-facing-include-path.md | 56 ++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 0000-user-facing-include-path.md

diff --git a/0000-user-facing-include-path.md b/0000-user-facing-include-path.md
new file mode 100644
index 0000000..442cf32
--- /dev/null
+++ b/0000-user-facing-include-path.md
@@ -0,0 +1,56 @@
+- Start Date: 2024-02-29
+- RFC PR: [lf-lang/rfcs#7](https://github.com/lf-lang/rfcs/pull/7)
+- Tracking Issue(s): [lf-lang/lingua-franca#2203](https://github.com/lf-lang/lingua-franca/issues/2203)
+
+# Abstract
+[abstract]: #abstract
+
+Do not put generated headers in the project root. Instead, put them in the src-gen directory, where all the other generated files are.
+
+# Motivation
+[motivation]: #motivation
+
+Generating files outside of the src-gen directory is a surprising behavior because users may expect that files generated by the LF code generator will all be placed in the `src-gen` and `bin` directories. In particular, if the user is already maintaining a directory called `include` that contains source files, then the current behavior will cause that directory to be overwritten or even deleted, which in the worst case can result in lost work.
+
+# Proposed Implementation
+[proposed-implementation]: #proposed-implementation
+
+The proposed solution is to generate the headers in `src-gen/include` only. Because user-provided C files will be included directly in `${LF_MAIN_TARGET}`, this directory will be on the include path for user-provided C files. Here is an example of how an `#include` directive might look in a user-provided C file given the proposed new behavior:
+
+```c
+#include "Count/Count.h"
+```
+
+For completeness, this is for a C file that is included in the LF project using the following target specification:
+
+```
+target C {
+  cmake-include: ["../../c/count.cmake"],
+  files: ["../../c"]
+}
+```
+
+And the following contents of `count.cmake`:
+
+```cmake
+target_sources(${LF_MAIN_TARGET} PRIVATE c/count.c)
+```
+
+Note the lack of any `target_include_directories` statements in `count.cmake`. This shows how the generated CMakeLists.txt takes care of putting the generated headers on the include path.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+One potential drawback of this proposal is that users may not be fully aware of the user-facing include directory, or it may not be as clear that the interfaces defined there are considered stable and safe to depend on. Putting both user-facing and non-user-facing files in `src-gen` could blur the lines between the two kinds of files. This can be addressed by carefully documenting which files are safe to depend on.
+
+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+One alternative is to put these headers in a sibling directory of the `src-gen` directory called `include-gen`, and to either add that directory to the include path or copy it into src-gen and put the copied directory on the include path. The disadvantage of this alternative is that it violates the principle that generated files will go in src-gen; this principle is simple and easy to explain, so it is worth keeping.
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
+
+# Future possibilities
+[future-possibilities]: #future-possibilities
+