diff --git a/AGENTS.md b/AGENTS.md index 05ee2955..e0c61bad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,8 @@ platform setup (Vulkan SDK, GLFW, etc.). Resources, Editor) are documented in [`docs/BuildModules.md`](docs/BuildModules.md) — read it before restructuring includes or CMake targets, it records locked decisions. - Orientation for where things live today: [`Skills/architecture.md`](Skills/architecture.md). +- Adding a new CMake module (folder + `fling_add_module`, with a UI example): + [`Skills/adding-modules.md`](Skills/adding-modules.md). ## Contribution conventions diff --git a/CMake/FlingEngineInc.cmake b/CMake/FlingEngineInc.cmake index 210e73ec..b51a9be3 100644 --- a/CMake/FlingEngineInc.cmake +++ b/CMake/FlingEngineInc.cmake @@ -31,8 +31,6 @@ MACRO(FLING_ENGINE_INC EngineDir ) ${EngineDir}Core/inc ${EngineDir}Graphics/inc ${EngineDir}Resources/inc - ${EngineDir}Utils/inc - ${EngineDir}Platform/inc ${EngineDir}Gameplay/inc ${GENERATED_INC_FOLDER} # Generated include files that cmake will handle (i.e. GitVersion) ) diff --git a/FlingEngine/CMakeLists.txt b/FlingEngine/CMakeLists.txt index 767969cd..ff06fc51 100644 --- a/FlingEngine/CMakeLists.txt +++ b/FlingEngine/CMakeLists.txt @@ -123,14 +123,6 @@ if( MSVC ) endforeach() endif() -################# Add dynamic module directories ################### -# TODO: Can't we do this recursively or something like that?? -add_subdirectory(Foundation) -# Link against the Foundation module -set( LINK_LIBS ${LINK_LIBS} Foundation ) - -#find_package(Foundation REQUIRED) - ################# Add library and link ###################### add_library ( ${PROJECT_NAME} ${_source_list} ) diff --git a/FlingEngine/Utils/inc/CircularBuffer.hpp b/FlingEngine/Core/inc/CircularBuffer.hpp similarity index 100% rename from FlingEngine/Utils/inc/CircularBuffer.hpp rename to FlingEngine/Core/inc/CircularBuffer.hpp diff --git a/FlingEngine/Platform/inc/FlingExports.h b/FlingEngine/Core/inc/FlingExports.h similarity index 100% rename from FlingEngine/Platform/inc/FlingExports.h rename to FlingEngine/Core/inc/FlingExports.h diff --git a/FlingEngine/Platform/inc/FlingLinuxExports.h b/FlingEngine/Core/inc/FlingLinuxExports.h similarity index 100% rename from FlingEngine/Platform/inc/FlingLinuxExports.h rename to FlingEngine/Core/inc/FlingLinuxExports.h diff --git a/FlingEngine/Utils/inc/FlingTypes.h b/FlingEngine/Core/inc/FlingTypes.h similarity index 100% rename from FlingEngine/Utils/inc/FlingTypes.h rename to FlingEngine/Core/inc/FlingTypes.h diff --git a/FlingEngine/Platform/inc/FlingWindowsExports.h b/FlingEngine/Core/inc/FlingWindowsExports.h similarity index 100% rename from FlingEngine/Platform/inc/FlingWindowsExports.h rename to FlingEngine/Core/inc/FlingWindowsExports.h diff --git a/FlingEngine/Utils/inc/FreeList.h b/FlingEngine/Core/inc/FreeList.h similarity index 100% rename from FlingEngine/Utils/inc/FreeList.h rename to FlingEngine/Core/inc/FreeList.h diff --git a/FlingEngine/Utils/inc/Logger.h b/FlingEngine/Core/inc/Logger.h similarity index 100% rename from FlingEngine/Utils/inc/Logger.h rename to FlingEngine/Core/inc/Logger.h diff --git a/FlingEngine/Utils/inc/Memory.h b/FlingEngine/Core/inc/Memory.h similarity index 100% rename from FlingEngine/Utils/inc/Memory.h rename to FlingEngine/Core/inc/Memory.h diff --git a/FlingEngine/Utils/inc/MovingAverage.hpp b/FlingEngine/Core/inc/MovingAverage.hpp similarity index 100% rename from FlingEngine/Utils/inc/MovingAverage.hpp rename to FlingEngine/Core/inc/MovingAverage.hpp diff --git a/FlingEngine/Utils/inc/NonCopyable.hpp b/FlingEngine/Core/inc/NonCopyable.hpp similarity index 100% rename from FlingEngine/Utils/inc/NonCopyable.hpp rename to FlingEngine/Core/inc/NonCopyable.hpp diff --git a/FlingEngine/Platform/inc/Platform.h b/FlingEngine/Core/inc/Platform.h similarity index 100% rename from FlingEngine/Platform/inc/Platform.h rename to FlingEngine/Core/inc/Platform.h diff --git a/FlingEngine/Platform/inc/PlatformLinux.h b/FlingEngine/Core/inc/PlatformLinux.h similarity index 100% rename from FlingEngine/Platform/inc/PlatformLinux.h rename to FlingEngine/Core/inc/PlatformLinux.h diff --git a/FlingEngine/Platform/inc/PlatformWindows.h b/FlingEngine/Core/inc/PlatformWindows.h similarity index 100% rename from FlingEngine/Platform/inc/PlatformWindows.h rename to FlingEngine/Core/inc/PlatformWindows.h diff --git a/FlingEngine/Utils/inc/Random.h b/FlingEngine/Core/inc/Random.h similarity index 100% rename from FlingEngine/Utils/inc/Random.h rename to FlingEngine/Core/inc/Random.h diff --git a/FlingEngine/Utils/inc/Singleton.hpp b/FlingEngine/Core/inc/Singleton.hpp similarity index 100% rename from FlingEngine/Utils/inc/Singleton.hpp rename to FlingEngine/Core/inc/Singleton.hpp diff --git a/FlingEngine/Utils/inc/StackAllocator.h b/FlingEngine/Core/inc/StackAllocator.h similarity index 100% rename from FlingEngine/Utils/inc/StackAllocator.h rename to FlingEngine/Core/inc/StackAllocator.h diff --git a/FlingEngine/Utils/inc/Stats.h b/FlingEngine/Core/inc/Stats.h similarity index 100% rename from FlingEngine/Utils/inc/Stats.h rename to FlingEngine/Core/inc/Stats.h diff --git a/FlingEngine/Utils/inc/Timing.h b/FlingEngine/Core/inc/Timing.h similarity index 100% rename from FlingEngine/Utils/inc/Timing.h rename to FlingEngine/Core/inc/Timing.h diff --git a/FlingEngine/Utils/inc/pch.h b/FlingEngine/Core/inc/pch.h similarity index 100% rename from FlingEngine/Utils/inc/pch.h rename to FlingEngine/Core/inc/pch.h diff --git a/FlingEngine/Core/src/Engine.cpp b/FlingEngine/Core/src/Engine.cpp index 308b156b..ea58e482 100644 --- a/FlingEngine/Core/src/Engine.cpp +++ b/FlingEngine/Core/src/Engine.cpp @@ -4,7 +4,6 @@ #include "File.h" #include "VulkanApp.h" #include "Misc/CommandLine.h" -#include "Foundation.h" #include "ComponentTypeRegistry.h" #include "RegisterGraphicsComponents.h" diff --git a/FlingEngine/Utils/src/FreeList.cpp b/FlingEngine/Core/src/FreeList.cpp similarity index 100% rename from FlingEngine/Utils/src/FreeList.cpp rename to FlingEngine/Core/src/FreeList.cpp diff --git a/FlingEngine/Utils/src/Logger.cpp b/FlingEngine/Core/src/Logger.cpp similarity index 100% rename from FlingEngine/Utils/src/Logger.cpp rename to FlingEngine/Core/src/Logger.cpp diff --git a/FlingEngine/Utils/src/Memory.cpp b/FlingEngine/Core/src/Memory.cpp similarity index 100% rename from FlingEngine/Utils/src/Memory.cpp rename to FlingEngine/Core/src/Memory.cpp diff --git a/FlingEngine/Utils/src/Random.cpp b/FlingEngine/Core/src/Random.cpp similarity index 100% rename from FlingEngine/Utils/src/Random.cpp rename to FlingEngine/Core/src/Random.cpp diff --git a/FlingEngine/Utils/src/StackAllocator.cpp b/FlingEngine/Core/src/StackAllocator.cpp similarity index 100% rename from FlingEngine/Utils/src/StackAllocator.cpp rename to FlingEngine/Core/src/StackAllocator.cpp diff --git a/FlingEngine/Utils/src/Stats.cpp b/FlingEngine/Core/src/Stats.cpp similarity index 100% rename from FlingEngine/Utils/src/Stats.cpp rename to FlingEngine/Core/src/Stats.cpp diff --git a/FlingEngine/Utils/src/Timing.cpp b/FlingEngine/Core/src/Timing.cpp similarity index 100% rename from FlingEngine/Utils/src/Timing.cpp rename to FlingEngine/Core/src/Timing.cpp diff --git a/FlingEngine/Utils/src/pch.cpp b/FlingEngine/Core/src/pch.cpp similarity index 100% rename from FlingEngine/Utils/src/pch.cpp rename to FlingEngine/Core/src/pch.cpp diff --git a/FlingEngine/Foundation/CMakeLists.txt b/FlingEngine/Foundation/CMakeLists.txt deleted file mode 100644 index 3fc39a27..00000000 --- a/FlingEngine/Foundation/CMakeLists.txt +++ /dev/null @@ -1,40 +0,0 @@ -# The Foundation target contains the core building blocks that Fling can use to make the Engine. -# this shouldn't depend on any other Fling Engine targets to avoid circular build dependcies - -cmake_minimum_required (VERSION 3.11.0) - -project("Foundation" VERSION 0.1) - -message(status "-- The foundation library is being configured!! -- ") - -# Find any C++ files here -file( GLOB_RECURSE foundation_source_list - *.cpp* src/*.h* src/*.hpp* *.h* *.inl -) - -# Make VS look ok -if( MSVC ) - foreach( _source IN ITEMS ${foundation_source_list} ) - get_filename_component( _source_path "${_source}" PATH ) - string( REPLACE "${CMAKE_SOURCE_DIR}" "" _group_path "${_source_path}" ) - string( REPLACE "/" "\\" _group_path "${_group_path}" ) - source_group( "${_group_path}" FILES "${_source}" ) - endforeach() -endif() - -# Libraries will produce a shared .dll file, and a .lib file that has the actual -# linking interface. If a module doesn't export any symbols (i.e. __declspec(dllexport)), then it won't -# produce a .lib and VS will error when building the game target -add_library ( ${PROJECT_NAME} SHARED ${foundation_source_list} ) - -# I think fix the include paths? -target_include_directories(${PROJECT_NAME} PUBLIC inc) -target_include_directories(${PROJECT_NAME} PRIVATE src) - -# set the version of this library -set_target_properties(${PROJECT_NAME} PROPERTIES VERSION ${PROJECT_VERSION}) - -#target_include_directories (${PROJECT_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${SPIRV_CROSS_INCLUDE_DIR}) - -# If we need to link against anything, do so here -# target_link_libraries( ${PROJECT_NAME} LINK_PUBLIC ${LINK_LIBS} ) \ No newline at end of file diff --git a/FlingEngine/Foundation/inc/Foundation.h b/FlingEngine/Foundation/inc/Foundation.h deleted file mode 100644 index 2c48f9d3..00000000 --- a/FlingEngine/Foundation/inc/Foundation.h +++ /dev/null @@ -1,10 +0,0 @@ -#pragma once - -#include "FoundationAPI.h" - -class FOUNDATION_API FoundationClass -{ -public: - static bool RunFoundationFunction(); - -}; \ No newline at end of file diff --git a/FlingEngine/Foundation/inc/FoundationAPI.h b/FlingEngine/Foundation/inc/FoundationAPI.h deleted file mode 100644 index 8dd295c3..00000000 --- a/FlingEngine/Foundation/inc/FoundationAPI.h +++ /dev/null @@ -1,26 +0,0 @@ -#pragma once - -#if _WIN32 - -// TODO: Per-platform definitions here - #ifndef FOUNDATION_API - #define FOUNDATION_API __declspec(dllexport) - #else // Not exporting function - #define FOUNDATION_API - #endif - -#endif // _WIN32 - -// TODO: make an actual export for this in the CMakeLists.txt file instead of doing it in C++ -// Or just make one exports file in C++ and properly do it for each platform -// which means that we should figure a nice way to include different directories based on your platform... -// ah geez -#if __linux__ - - #if __GNUC__ >= 4 - #define FOUNDATION_API __attribute__ ((visibility ("default"))) - #else - #define FOUNDATION_API - #endif - -#endif // __linux__ \ No newline at end of file diff --git a/FlingEngine/Foundation/src/Foundation.cpp b/FlingEngine/Foundation/src/Foundation.cpp deleted file mode 100644 index d70ebc2a..00000000 --- a/FlingEngine/Foundation/src/Foundation.cpp +++ /dev/null @@ -1,6 +0,0 @@ -#include "Foundation.h" - -bool FoundationClass::RunFoundationFunction() -{ - return true; -} \ No newline at end of file diff --git a/FlingEngine/Platform/inc/ImGuiInputBinding.hpp b/FlingEngine/Graphics/inc/ImGuiInputBinding.hpp similarity index 100% rename from FlingEngine/Platform/inc/ImGuiInputBinding.hpp rename to FlingEngine/Graphics/inc/ImGuiInputBinding.hpp diff --git a/FlingTests/CMakeLists.txt b/FlingTests/CMakeLists.txt index f4c27229..f91f543c 100644 --- a/FlingTests/CMakeLists.txt +++ b/FlingTests/CMakeLists.txt @@ -21,7 +21,6 @@ set ( LINK_LIBS glfw ${GLFW_LIBRARIES} Catch2::Catch2WithMain "FlingEngine" - Foundation ) # link pthread if we need to diff --git a/Sandbox/CMakeLists.txt b/Sandbox/CMakeLists.txt index cbcf5fe9..b24a1593 100644 --- a/Sandbox/CMakeLists.txt +++ b/Sandbox/CMakeLists.txt @@ -21,7 +21,6 @@ endif() set ( LINK_LIBS "FlingEngine" - Foundation ) # link pthread if we need to diff --git a/Skills/README.md b/Skills/README.md index 0360870f..606bead9 100644 --- a/Skills/README.md +++ b/Skills/README.md @@ -10,6 +10,7 @@ detail on a given topic. These files are meant to be read on demand, not all at | [`testing.md`](testing.md) | Running FlingTests, adding new Catch2 tests | | [`coding-style.md`](coding-style.md) | Doc-comment conventions, formatting, what not to touch | | [`architecture.md`](architecture.md) | Current folder/module layout, where new code belongs | +| [`adding-modules.md`](adding-modules.md) | How to add a new engine module (`fling_add_module`, UI example) | These are supplementary to, not a replacement for, the canonical docs they reference (`docs/CodingStyle.md`, `docs/BuildModules.md`) — when in doubt, the diff --git a/Skills/adding-modules.md b/Skills/adding-modules.md new file mode 100644 index 00000000..0d988d21 --- /dev/null +++ b/Skills/adding-modules.md @@ -0,0 +1,143 @@ +# Adding an engine module + +Canonical design and locked decisions: [`docs/BuildModules.md`](../docs/BuildModules.md). +This file is the how-to. Do not invent a second pattern (extra globs in the root +CMakeLists, a hand-rolled `*_API` header, or edits under `external/`). + +`fling_add_module()` lives in [`CMake/FlingModule.cmake`](../CMake/FlingModule.cmake). +Until `FlingEngine/CMakeLists.txt` `add_subdirectory`s each module, the engine is +still one static library and new folders are picked up by the monolith glob. +Do **not** add a `fling_add_module` target that compiles the same sources as +`FlingEngine` — that double-builds. Use this recipe once modules are separate +targets (or when you are the change that splits them). + +## What you add + +A module is: + +1. A folder under `FlingEngine/` with `inc/` (public headers) and `src/` (sources). +2. A `CMakeLists.txt` that calls `fling_add_module`. +3. `add_subdirectory(...)` in `FlingEngine/CMakeLists.txt` **after** that module's + dependencies exist. +4. `MODULE_API` on types that cross the DLL boundary. +5. `target_link_libraries(Consumer PRIVATE Fling::ModuleName)` on anything that + should see that module's headers. + +You do not list `.cpp` files by hand. You do not edit the old engine-wide glob. + +## Example: a `UI` module + +In-game HUD / widgets. Publicly needs Core and Gameplay (types, `Transform`). +Privately needs Graphics and ImGui to draw. A physics-only tool would not link +`Fling::UI` and would not see `UISystem.h`. + +### 1. Folder + +``` +FlingEngine/UI/ + CMakeLists.txt + inc/UISystem.h + src/UISystem.cpp +``` + +Keep `#include "UISystem.h"` (flat names). Isolation comes from include **paths** +via `target_link_libraries`, not from renaming headers to `UI/UISystem.h`. + +### 2. `FlingEngine/UI/CMakeLists.txt` + +```cmake +fling_add_module(UI + PUBLIC_DEPS Core Gameplay + PRIVATE_DEPS Graphics + PRIVATE_LIBS ImGui +) +``` + +| Argument | Meaning | +|----------|---------| +| `PUBLIC_DEPS` | Fling modules whose headers consumers of UI may also include | +| `PRIVATE_DEPS` | Fling modules UI uses internally; not pushed onto UI's consumers' include path | +| `PUBLIC_LIBS` / `PRIVATE_LIBS` | Third-party CMake targets (glfw, ImGui, Vulkan::Vulkan, …) | +| `STATIC` | Optional. Default is a shared library | + +CMake generates `UIAPI.h` (macro `UI_API`) into the UI build dir and puts that +dir on UI's **public** include path. Do not check `UIAPI.h` into git. + +### 3. Register it bottom-up + +In `FlingEngine/CMakeLists.txt`, add UI **after** Core, Gameplay, and Graphics. +A dependency cycle is a configure error. + +```cmake +add_subdirectory(Core) +add_subdirectory(Resources) +add_subdirectory(Gameplay) +add_subdirectory(Graphics) +add_subdirectory(UI) +``` + +If Sandbox or Engine should use UI, link the alias — do not `include_directories` +the UI folder: + +```cmake +target_link_libraries(SandboxEditor PRIVATE Fling::UI) +``` + +### 4. Export the DLL surface + +```cpp +#pragma once + +#include "UIAPI.h" +#include "FlingTypes.h" + +namespace Fling +{ + class UI_API UISystem + { + public: + void Init(); + void Draw(float deltaTime); + }; +} +``` + +```cpp +#include "UISystem.h" + +namespace Fling +{ + void UISystem::Init() {} + void UISystem::Draw(float deltaTime) { (void)deltaTime; } +} +``` + +- Mark classes/functions that are **defined in this module's `.cpp`** and called + from another module with `UI_API`. +- Header-only templates stay unmarked. +- Do not use `FLING_LIB_EXPORT` / `FLING_LIB_IMPORT` on engine types; those are + only for the generated `*API.h` headers. + +### 5. Consume it + +```cpp +#include "UISystem.h" + +Fling::UISystem hud; +hud.Init(); +``` + +If a target does not link `Fling::UI`, `#include "UISystem.h"` must fail to +compile. That is the isolation test. + +## Checklist for any new module + +- [ ] Folder is `FlingEngine//{inc,src}` plus `CMakeLists.txt`. +- [ ] `fling_add_module( ...)` only; no extra `add_library` / globs. +- [ ] `add_subdirectory()` after every module in `PUBLIC_DEPS` / `PRIVATE_DEPS`. +- [ ] Public headers include `API.h` and use `_API` on exported types. +- [ ] Consumers `target_link_libraries(... Fling::)`. No new + `include_directories()` for engine headers. +- [ ] Gameplay still does not include Graphics headers. Editor stays a leaf + (Engine/Graphics do not include Editor). See [`architecture.md`](architecture.md). +- [ ] Nothing under `external/` is modified. diff --git a/Skills/architecture.md b/Skills/architecture.md index 4041e116..11cc99a3 100644 --- a/Skills/architecture.md +++ b/Skills/architecture.md @@ -9,11 +9,12 @@ several things that look like cleanups are explicitly deferred or ruled out ther ## Today - `FlingEngine/` — the engine, currently one CMake library (`FlingEngine`) built - from almost every source file under this tree via glob. Subfolders already hint - at future module boundaries (`Core`, `Graphics`, `Gameplay`, `Resources`, `Utils`, - `Platform`, `Editor`, `Foundation`) but CMake/includes still treat it as one target - — `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder - location doesn't currently enforce isolation. + from almost every source file under this tree via glob. Subfolders are + `Core` (includes former Utils + Platform), `Graphics`, `Gameplay`, + `Resources`, and `Editor`. CMake/includes still treat it as one target — + `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder + location doesn't currently enforce isolation. `fling_add_module()` lives in + `CMake/FlingModule.cmake` but is not yet used for a real shared module. - `Sandbox/` — the sample game + editor, one executable today (editor support is toggled by a project-wide `WITH_EDITOR` define, which `docs/BuildModules.md` plans to remove in favor of two separate executables). @@ -37,5 +38,5 @@ several things that look like cleanups are explicitly deferred or ruled out ther it describes instead. - Don't add a new module folder or CMake target without reading the "Locked decisions" section of `docs/BuildModules.md` first — several plausible-looking - approaches (per-module PCH, merging Foundation into something else, git - submodules per system) are explicitly rejected there. + approaches (per-module PCH, git submodules per system) are explicitly rejected there. + The how-to (including a UI module example) is [`adding-modules.md`](adding-modules.md).