From d92af9fcbca29681bb731d91d6fe1f2acfdb9230 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 19 Sep 2025 13:01:44 +0000 Subject: [PATCH] Final: Add copilot-instructions.md and clean build artifacts from git Co-authored-by: ArthurSonzogni <4759106+ArthurSonzogni@users.noreply.github.com> --- .github/copilot-instructions.md | 212 ++++++++++++++++++ .gitignore | 2 + build/_deps/googlebenchmark-src | 1 - .../googlebenchmark-subbuild/CMakeLists.txt | 42 ---- build/_deps/googletest-src | 1 - .../_deps/googletest-subbuild/CMakeLists.txt | 42 ---- 6 files changed, 214 insertions(+), 86 deletions(-) create mode 100644 .github/copilot-instructions.md delete mode 160000 build/_deps/googlebenchmark-src delete mode 100644 build/_deps/googlebenchmark-subbuild/CMakeLists.txt delete mode 160000 build/_deps/googletest-src delete mode 100644 build/_deps/googletest-subbuild/CMakeLists.txt diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..8228e033 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,212 @@ +# FTXUI - Functional Terminal (X) User Interface + +FTXUI is a cross-platform C++ library for terminal-based user interfaces with a functional programming approach, inspired by React. + +**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the information here.** + +## Working Effectively + +### Build System Setup and Commands +- Bootstrap and build the repository: + ```bash + # Basic build (library only) - fast + cmake -S . -B build -DCMAKE_BUILD_TYPE=Release + cmake --build build --parallel $(nproc) + # Build time: ~30 seconds. NEVER CANCEL. Set timeout to 120+ seconds. + + # Build with examples + cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON + cmake --build build --parallel $(nproc) + # Build time: ~70 seconds. NEVER CANCEL. Set timeout to 180+ seconds. + + # Build with examples and tests + cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON -DFTXUI_BUILD_TESTS=ON + cmake --build build --parallel $(nproc) + # Build time: ~113 seconds (includes GoogleTest download). NEVER CANCEL. Set timeout to 300+ seconds. + ``` + +- Alternative build with Ninja (faster): + ```bash + cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON + ninja -C build + # Build time: ~62 seconds. NEVER CANCEL. Set timeout to 180+ seconds. + ``` + +- Run unit tests: + ```bash + # Configure with tests enabled first, then: + cd build && ctest --output-on-failure + # Test time: ~4 seconds (302 tests). NEVER CANCEL. Set timeout to 60+ seconds. + ``` + +### Bazel Support +- FTXUI also supports Bazel build system +- **WARNING**: Bazel may fail due to network connectivity issues in sandboxed environments +- If Bazel is available: + ```bash + bazel build //... # Build everything + bazel test //... # Run tests + ``` + +## Validation + +### Manual Testing After Changes +- **ALWAYS manually validate changes by building and running examples after making code modifications** +- Run example applications to verify functionality: + ```bash + # Build an example first + cmake --build build --target ftxui_example_border + + # Run examples (they are interactive, use timeout to terminate) + timeout 2s build/examples/dom/ftxui_example_border + timeout 2s build/examples/dom/ftxui_example_color_gallery + timeout 2s build/examples/component/ftxui_example_button + ``` +- Examples should produce visual terminal output with borders, colors, and UI components +- **CRITICAL**: Always run at least one DOM example and one Component example to verify both modules work + +### Code Quality and Formatting +- Always run formatting before committing: + ```bash + ./tools/format.sh + # Format time: ~7 seconds. NEVER CANCEL. Set timeout to 60+ seconds. + ``` +- The format script adds license headers and runs clang-format on all source files +- **Required**: Run formatting or the CI (.github/workflows/build.yaml) will fail + +### Build Validation Requirements +- ALWAYS build with both `-DFTXUI_BUILD_EXAMPLES=ON` and `-DFTXUI_BUILD_TESTS=ON` when making changes +- Run the complete test suite with `ctest --output-on-failure` +- All 302 tests must pass +- **Scenario Testing**: Run at least these validation scenarios: + 1. Build library only (basic validation) + 2. Build with examples and run 2-3 different examples + 3. Build with tests and run complete test suite + 4. Run formatting tool to ensure code style compliance + +## Project Structure + +### Key Directories +``` +/home/runner/work/FTXUI/FTXUI/ +├── include/ftxui/ # Public header files +│ ├── component/ # Interactive component headers +│ ├── dom/ # DOM element headers +│ ├── screen/ # Screen and rendering headers +│ └── util/ # Utility headers +├── src/ftxui/ # Implementation files +│ ├── component/ # Interactive components (buttons, menus, etc.) +│ ├── dom/ # DOM elements (layout, styling, text) +│ ├── screen/ # Screen rendering and terminal handling +│ └── util/ # Utilities +├── examples/ # Example applications +│ ├── component/ # Interactive component examples +│ └── dom/ # DOM element examples +├── cmake/ # CMake configuration files +├── tools/ # Development tools (formatting, etc.) +└── .github/workflows/ # CI/CD configuration +``` + +### Core Library Modules +FTXUI is organized into three main modules that depend on each other: +``` +┌component──┐ (Interactive UI components) +│┌dom──────┐│ (Layout and styling elements) +││┌screen─┐││ (Terminal rendering and input) +└┴┴───────┴┴┘ +``` + +1. **screen**: Low-level terminal handling, colors, pixels, input +2. **dom**: Layout elements (hbox, vbox, text, borders, etc.) +3. **component**: Interactive components (buttons, menus, input fields) + +### CMake Build Options +| Option | Description | Default | +|-----------------------------------|----------------------------------|---------| +| FTXUI_BUILD_EXAMPLES | Build example applications | OFF | +| FTXUI_BUILD_DOCS | Build documentation | OFF | +| FTXUI_BUILD_TESTS | Build and enable tests | OFF | +| FTXUI_BUILD_MODULES | Build C++20 modules | OFF | +| FTXUI_ENABLE_INSTALL | Generate install targets | ON | +| FTXUI_MICROSOFT_TERMINAL_FALLBACK | Windows terminal compatibility | ON/OFF | + +## Common Tasks + +### Building Examples +```bash +# Build specific examples +cmake --build build --target ftxui_example_border +cmake --build build --target ftxui_example_button +cmake --build build --target ftxui_example_menu + +# List all available examples +find build -name "ftxui_example_*" -type f +``` + +### Running Tests +```bash +# Run all tests +cd build && ctest + +# Run tests with verbose output +cd build && ctest --verbose + +# Run specific test pattern +cd build && ctest -R "Button" --verbose +``` + +### Working with Source Code +- **Component Development**: Modify files in `src/ftxui/component/` for interactive elements +- **DOM Development**: Modify files in `src/ftxui/dom/` for layout and styling +- **Screen Development**: Modify files in `src/ftxui/screen/` for terminal rendering +- **Adding Examples**: Add new `.cpp` files in `examples/component/` or `examples/dom/` +- **Header Files**: Public APIs are in `include/ftxui/[module]/` + +### Integration Patterns +When adding FTXUI to a project, use CMake FetchContent (recommended): +```cmake +include(FetchContent) +FetchContent_Declare(ftxui + GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui + GIT_TAG v6.1.9 +) +FetchContent_MakeAvailable(ftxui) + +target_link_libraries(your_target PRIVATE + ftxui::component # For interactive components + ftxui::dom # For layout elements + ftxui::screen # For basic rendering +) +``` + +## Troubleshooting + +### Build Issues +- If CMake configuration fails, ensure C++20 support: `cmake --version` (need 3.12+) +- If Ninja build fails, fall back to Make: `cmake -S . -B build` (without `-G Ninja`) +- If tests fail to build, GoogleTest download might have failed - check network connectivity +- Build artifacts are in `build/` directory - delete with `rm -rf build` to clean + +### Example Issues +- Examples are interactive terminal applications - use `timeout` to terminate them +- If examples don't display correctly, terminal might not support colors/Unicode +- Examples require terminal size of at least 80x24 for proper display + +### Formatting Issues +- Format script requires clang-format to be installed +- If format script fails, check that source files are not read-only +- Format script modifies files in-place - commit changes afterwards + +## Critical Reminders + +- **NEVER CANCEL long-running builds** - they may take 2-3 minutes +- **ALWAYS run the formatting tool** before committing changes +- **ALWAYS build and test examples** when making component/dom changes +- **SET APPROPRIATE TIMEOUTS**: 300+ seconds for builds, 60+ seconds for tests +- **BUILD TIMING EXPECTATIONS**: + - Basic library: ~30 seconds + - With examples: ~70 seconds + - With examples + tests: ~113 seconds (first time, includes GoogleTest download) + - Subsequent builds: ~60-70 seconds + - Tests execution: ~4 seconds + - Formatting: ~7 seconds \ No newline at end of file diff --git a/.gitignore b/.gitignore index 40a2b7c4..90b093ab 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ out/ # .github directory: !.github/**/*.yaml !.github/**/*.yml +!.github/**/*.md # cmake directory: !cmake/**/*.in @@ -70,3 +71,4 @@ out/ # tools directory: !tools/**/*.sh !tools/**/*.cpp +build/ diff --git a/build/_deps/googlebenchmark-src b/build/_deps/googlebenchmark-src deleted file mode 160000 index 015d1a09..00000000 --- a/build/_deps/googlebenchmark-src +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 015d1a091af6937488242b70121858bce8fd40e9 diff --git a/build/_deps/googlebenchmark-subbuild/CMakeLists.txt b/build/_deps/googlebenchmark-subbuild/CMakeLists.txt deleted file mode 100644 index cf260eeb..00000000 --- a/build/_deps/googlebenchmark-subbuild/CMakeLists.txt +++ /dev/null @@ -1,42 +0,0 @@ -# Distributed under the OSI-approved BSD 3-Clause License. See accompanying -# file Copyright.txt or https://cmake.org/licensing for details. - -cmake_minimum_required(VERSION 3.31.6) - -# Reject any attempt to use a toolchain file. We must not use one because -# we could be downloading it here. If the CMAKE_TOOLCHAIN_FILE environment -# variable is set, the cache variable will have been initialized from it. -unset(CMAKE_TOOLCHAIN_FILE CACHE) -unset(ENV{CMAKE_TOOLCHAIN_FILE}) - -# We name the project and the target for the ExternalProject_Add() call -# to something that will highlight to the user what we are working on if -# something goes wrong and an error message is produced. - -project(googlebenchmark-populate NONE) - - -# Pass through things we've already detected in the main project to avoid -# paying the cost of redetecting them again in ExternalProject_Add() -set(GIT_EXECUTABLE [==[/usr/bin/git]==]) -set(GIT_VERSION_STRING [==[2.51.0]==]) -set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION - [==[/usr/bin/git;2.51.0]==] -) - - -include(ExternalProject) -ExternalProject_Add(googlebenchmark-populate - "UPDATE_DISCONNECTED" "False" "GIT_REPOSITORY" "https://github.com/google/benchmark" "EXTERNALPROJECT_INTERNAL_ARGUMENT_SEPARATOR" "GIT_TAG" "015d1a091af6937488242b70121858bce8fd40e9" "GIT_PROGRESS" "TRUE" - SOURCE_DIR "/home/runner/work/FTXUI/FTXUI/build/_deps/googlebenchmark-src" - BINARY_DIR "/home/runner/work/FTXUI/FTXUI/build/_deps/googlebenchmark-build" - CONFIGURE_COMMAND "" - BUILD_COMMAND "" - INSTALL_COMMAND "" - TEST_COMMAND "" - USES_TERMINAL_DOWNLOAD YES - USES_TERMINAL_UPDATE YES - USES_TERMINAL_PATCH YES -) - - diff --git a/build/_deps/googletest-src b/build/_deps/googletest-src deleted file mode 160000 index 23ef2955..00000000 --- a/build/_deps/googletest-src +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 23ef29555ef4789f555f1ba8c51b4c52975f0907 diff --git a/build/_deps/googletest-subbuild/CMakeLists.txt b/build/_deps/googletest-subbuild/CMakeLists.txt deleted file mode 100644 index 6aeea503..00000000 --- a/build/_deps/googletest-subbuild/CMakeLists.txt +++ /dev/null @@ -1,42 +0,0 @@ -# Distributed under the OSI-approved BSD 3-Clause License. See accompanying -# file Copyright.txt or https://cmake.org/licensing for details. - -cmake_minimum_required(VERSION 3.31.6) - -# Reject any attempt to use a toolchain file. We must not use one because -# we could be downloading it here. If the CMAKE_TOOLCHAIN_FILE environment -# variable is set, the cache variable will have been initialized from it. -unset(CMAKE_TOOLCHAIN_FILE CACHE) -unset(ENV{CMAKE_TOOLCHAIN_FILE}) - -# We name the project and the target for the ExternalProject_Add() call -# to something that will highlight to the user what we are working on if -# something goes wrong and an error message is produced. - -project(googletest-populate NONE) - - -# Pass through things we've already detected in the main project to avoid -# paying the cost of redetecting them again in ExternalProject_Add() -set(GIT_EXECUTABLE [==[/usr/bin/git]==]) -set(GIT_VERSION_STRING [==[2.51.0]==]) -set_property(GLOBAL PROPERTY _CMAKE_FindGit_GIT_EXECUTABLE_VERSION - [==[/usr/bin/git;2.51.0]==] -) - - -include(ExternalProject) -ExternalProject_Add(googletest-populate - "UPDATE_DISCONNECTED" "False" "GIT_REPOSITORY" "https://github.com/google/googletest" "EXTERNALPROJECT_INTERNAL_ARGUMENT_SEPARATOR" "GIT_TAG" "23ef29555ef4789f555f1ba8c51b4c52975f0907" "GIT_PROGRESS" "TRUE" - SOURCE_DIR "/home/runner/work/FTXUI/FTXUI/build/_deps/googletest-src" - BINARY_DIR "/home/runner/work/FTXUI/FTXUI/build/_deps/googletest-build" - CONFIGURE_COMMAND "" - BUILD_COMMAND "" - INSTALL_COMMAND "" - TEST_COMMAND "" - USES_TERMINAL_DOWNLOAD YES - USES_TERMINAL_UPDATE YES - USES_TERMINAL_PATCH YES -) - -