From 9001804fa6f937058ee48e827505bea13933606a Mon Sep 17 00:00:00 2001 From: Michael Ragazzon Date: Mon, 1 Apr 2024 17:42:01 +0200 Subject: [PATCH] Update changelog --- CMake/RuntimeDependencies.cmake | 1 + CMakeLists.txt | 2 +- changelog.md | 92 +++++++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+), 1 deletion(-) diff --git a/CMake/RuntimeDependencies.cmake b/CMake/RuntimeDependencies.cmake index 50e6b8cc2..5134859c1 100644 --- a/CMake/RuntimeDependencies.cmake +++ b/CMake/RuntimeDependencies.cmake @@ -31,6 +31,7 @@ endfunction() function(install_runtime_dependencies) if(WIN32 AND RMLUI_RUNTIME_DEPENDENCY_SET_ARG) option(RMLUI_INSTALL_RUNTIME_DEPENDENCIES "Include runtime dependencies when installing RmlUi." ON) + mark_as_advanced(RMLUI_INSTALL_RUNTIME_DEPENDENCIES) if(RMLUI_INSTALL_RUNTIME_DEPENDENCIES) install(RUNTIME_DEPENDENCY_SET rmlui_runtime_dependencies PRE_EXCLUDE_REGEXES "api-ms-" "ext-ms-" diff --git a/CMakeLists.txt b/CMakeLists.txt index dcb29c310..fe54effc4 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -20,7 +20,7 @@ include("${PROJECT_SOURCE_DIR}/CMake/OptionsLists.cmake") option(BUILD_SHARED_LIBS "CMake standard option. Choose whether to build shared RmlUi libraries." ON) # Declare project-specific options. Naming conventions: -# - Use "RMLUI_" prefix to make all options specific to this project easily identifiable. +# - Use "RMLUI_" prefix to make all options specific to this project easily identifiable, and avoid colliding with any parent project variables. # - Do not include negations (such as "not" and "disable"), to avoid situations with double negation. # - Do not include a verb prefix (such as "enable" and "build"), as these are often superfluous. option(RMLUI_SAMPLES "Build samples of the library." OFF) diff --git a/changelog.md b/changelog.md index e635d7fd1..edb38d28f 100644 --- a/changelog.md +++ b/changelog.md @@ -232,8 +232,100 @@ input { nav: auto; nav-right: #ok_button; } - OpenGL 3: Restore all modified state after rendering a frame. #449 (thanks @reworks-org) - OpenGL 3: Set forward compatibility flag to fix running on MacOS. #522 (thanks @NaLiJa) +### Modernized CMake + +The CMake code has been fully rewritten from scratch with modern practices. Special thanks to @hobyst who laid the groundwork for this change, with a solid foundation and great guidelines. #198 #446 #551 (thanks @hobyst) + +While modernizing our CMake code, it was clear that we also needed to change our naming conventions. This leads to quite significant breaking changes for building and linking, but the result should make the library a lot easier to work with and link with. + +We now try to support all setups including: + +1. Adding the library as a subdirectory directly from CMake. +2. Building the library "in-source" without installing. +3. Building and installing the library. +4. Using pre-built Windows binaries. + +It should be a lot easier now to simply point to the built library or sources, and have everything link correctly. + +And naturally, we will continue to support package managers however we can, and that is still considered the default recommendation. However, for the most part we rely on contributors to keep supporting this. Please help out with your favorite package manager if you see missing versions, or room for improvements. + +Large parts of the CI workflows have also been rewritten to accommodate these changes. Most of the Windows building and packaging procedures have been moved from Appveyor to GitHub Actions, which streamlines our testing and also helps speed up the CI builds. + +#### New target names + +We now export the following targets: + +| Target | Description | +|-----------------|-----------------------------------------------------------------| +| RmlUi::RmlUi | Includes all sub-libraries of the project, as listed just below | +| RmlUi::Core | The main library | +| RmlUi::Debugger | The debugger library | +| RmlUi::Lua | The Lua plugin (when enabled) | + +When including RmlUi as a subdirectory, the targets are constructed as aliases. When using pre-built or installed binaries, they are constructed using imported targets, which are available through the exported build targets. + +The internal target names have also been changed, although they are typically only needed when exploring or developing the library. They are all lowercase and contain the prefix `rmlui_` to avoid colliding with names in any parent projects. Some examples are: `rmlui_core`, `rmlui_debugger`, `rmlui_sample_invaders`, `rmlui_tutorial_drag`, `rmlui_unit_tests`, and `rmlui_visual_tests`. + +#### New library filenames + +The library binaries have also changed names. These names would be suffixed by e.g. `.dll` on Windows, and so on. + +| Library | Description | +|------------------|-------------------------------| +| `rmlui` | The core (main) library | +| `rmlui_debugger` | The debugger library | +| `rmlui_lua` | The Lua plugin (when enabled) | + +#### New option names + +We have a new set of CMake naming conventions for the library: + +- Use `RMLUI_` prefix to make all options specific to this project easily identifiable, and avoid colliding with any parent project variables. +- Do not include negations (such as "not" and "disable"), to avoid situations with double negation. +- Do not include a verb prefix (such as "enable" and "build"), as these are often superfluous. + +The following table lists all the new option names. + +| Option | Default value | Old related option | Comment | +|--------------------------------------|---------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| RMLUI_BACKEND | auto | SAMPLES_BACKEND | | +| RMLUI_COMPILER_OPTIONS | ON | | Automatically sets recommended compiler flags | +| RMLUI_CUSTOM_CONFIGURATION | OFF | CUSTOM_CONFIGURATION | | +| RMLUI_CUSTOM_CONFIGURATION_FILE | | CUSTOM_CONFIGURATION_FILE | | +| RMLUI_CUSTOM_INCLUDE_DIRS | | CUSTOM_INCLUDE_DIRS | | +| RMLUI_CUSTOM_LINK_LIBRARIES | | CUSTOM_LINK_LIBRARIES | | +| RMLUI_CUSTOM_RTTI | OFF | DISABLE_RTTI_AND_EXCEPTIONS | No longer modifies compiler flags - only enables RmlUi's custom RTTI solution so that the user can disable language RTTI and exceptions | +| RMLUI_FONT_ENGINE | freetype | NO_FONT_INTERFACE_DEFAULT | Now takes a string with one of the options: `none`, `freetype` | +| RMLUI_HARFBUZZ_SAMPLE | OFF | | | +| RMLUI_INSTALL_RUNTIME_DEPENDENCIES | ON | | Automatically install runtime dependencies on supported platforms (e.g. DLLs) | +| RMLUI_LOTTIE_PLUGIN | OFF | ENABLE_LOTTIE_PLUGIN | | +| RMLUI_LUA_BINDINGS | OFF | BUILD_LUA_BINDINGS | | +| RMLUI_LUA_BINDINGS_LIBRARY | lua | BUILD_LUA_BINDINGS_FOR_LUAJIT | Now takes a string with one of the options: `lua`, `lua_as_cxx`, `luajit` | +| RMLUI_MATRIX_ROW_MAJOR | OFF | MATRIX_ROW_MAJOR | | +| RMLUI_PRECOMPILED_HEADERS | ON | ENABLE_PRECOMPILED_HEADERS | | +| RMLUI_SAMPLES | OFF | BUILD_SAMPLES | | +| RMLUI_SVG_PLUGIN | OFF | ENABLE_SVG_PLUGIN | | +| RMLUI_THIRDPARTY_CONTAINERS | ON | NO_THIRDPARTY_CONTAINERS | | +| RMLUI_TRACY_PROFILING | OFF | ENABLE_TRACY_PROFILING | | +| RMLUI_VISUAL_TESTS_RML_DIRECTORIES | | VISUAL_TESTS_RML_DIRECTORIES | | +| RMLUI_VISUAL_TESTS_COMPARE_DIRECTORY | | VISUAL_TESTS_COMPARE_DIRECTORY | | +| RMLUI_VISUAL_TESTS_CAPTURE_DIRECTORY | | VISUAL_TESTS_CAPTURE_DIRECTORY | | + +For reference, the following options have not changed names, as these are standard options used by CMake. + +| Unchanged options | Default value | +|-------------------|---------------| +| CMAKE_BUILD_TYPE | | +| BUILD_SHARED_LIBS | ON | +| BUILD_TESTING | OFF | + ### Breaking changes +#### CMake and linking + +- Most options, target names, and library filenames, have been changed, please see the tables above. +- CMake minimum version raised to 3.10. + #### Layout - Possible layout changes, usually due to better CSS conformance. Please see notes above.