From 994915dbb90271b5a96a3cf947784d6633b2d5d3 Mon Sep 17 00:00:00 2001
From: tattwamasi <rob@loci.net>
Date: Sun, 27 Jul 2025 02:39:46 -0700
Subject: [PATCH] Add ftxui convenience/umbrella module to cmake rules to fix
 #1083 (#1085)

* Add the umbrella module ftxui to the cmake module build.

* Update cpp20 modules documentation.
---
 cmake/ftxui_modules.cmake |  1 +
 doc/cpp20-modules.md      | 47 +++++++++++++++++++++++++++++----------
 2 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/cmake/ftxui_modules.cmake b/cmake/ftxui_modules.cmake
index 6c784a97..3cc0f04a 100644
--- a/cmake/ftxui_modules.cmake
+++ b/cmake/ftxui_modules.cmake
@@ -6,6 +6,7 @@ add_library(ftxui-modules)
 
 target_sources(ftxui-modules
   PUBLIC FILE_SET CXX_MODULES FILES
+  src/ftxui/ftxui.cppm
   src/ftxui/component.cppm
   src/ftxui/component/animation.cppm
   src/ftxui/component/captured_mouse.cppm
diff --git a/doc/cpp20-modules.md b/doc/cpp20-modules.md
index 6af80552..74d1aeaa 100644
--- a/doc/cpp20-modules.md
+++ b/doc/cpp20-modules.md
@@ -12,8 +12,24 @@ FTXUI experimentally supports
 compilation times and improve code organization. Each header has a
 corresponding module.
 
-**Example with CMake and Ninja**
+Use the FTXUI_BUILD_MODULES option to build the FTXUI project itself to provide C++ 20 modules,
+for example with CMake and Ninja:
 
+```sh
+cmake \
+    -DCMAKE_GENERATOR=Ninja \
+    -DFTXUI_BUILD_MODULES=ON \
+    ..
+
+ninja
+```
+
+> [!NOTE]
+> To use modules, you need a C++20 compatible compiler, CMake version 3.20 or
+> higher, and use a compatible generator like Ninja. Note that Makefile
+> generators **do not support modules**.
+
+Then, in your own code you can consume the modules and code as normal:
 
 ```cpp
 import ftxui;
@@ -26,23 +42,30 @@ int main() {
 }
 ```
 
-```sh
-cmake \
-    -DCMAKE_GENERATOR=Ninja \
-    -DFTXUI_BUILD_MODULES=ON \
-    ..
+Note, the `ftxui` convenience module which simply pulls together all the modules:
 
-ninja
+```cpp
+export import ftxui.component;
+export import ftxui.dom;
+export import ftxui.screen;
+export import ftxui.util;
+```
+You can instead import only the module(s) you need if desired.
+
+To properly find and link the modules with CMake, use `target_link_libraries` to get the right
+compiler, linker, etc. flags.
+
+```cmake
+target_link_libraries(my_executable
+    #...whatever...
+    PRIVATE ftxui::modules
+)
 ```
-> [!NOTE]
-> To use modules, you need a C++20 compatible compiler, CMake version 3.20 or
-> higher, and use a compatible generator like Ninja. Note that Makefile
-> generators **do not support modules**.
 
 ### Module list
 
 The modules directly reference the corresponding header, or a group of related
-headers to provide a more convenient interface. The following modules 
+headers to provide a more convenient interface. The following modules
 are available:
 
 - `ftxui`