minor improvements

- examples are not part of ALL anymore - import-xp disables pdb warnings publicly - silenced or fixed tests warnings - build on readthedocs powered by a CMake script - minor doc readability improvements
Lucide · Feb 2, 2021 · 00c47af · 00c47af
1 parent 1e5f434
commit 00c47af
Show file tree

Hide file tree

Showing 11 changed files with 128 additions and 109 deletions.
diff --git a/doc/build.rst b/doc/build.rst
@@ -4,4 +4,102 @@ Build instructions
 .. toctree::
 
     build/import
-    build/specs
+
+----
+
+CMake specs
+***********
+
++-----------------------+--------------------------------------------+
+| default build type    | Release                                    |
++-----------------------+--------------------------------------------+
+| supported build types | Release, Debug, RelWithDebInfo, MinSizeRel |
++-----------------------+--------------------------------------------+
+| *ALL* targets         | VisualT_library, VisualT_import_xp [1]_    |
++-----------------------+--------------------------------------------+
+| default installation  | VisualT::library, VisualT::import_xp [1]_  |
++-----------------------+--------------------------------------------+
+
+.. [1] If the respective conditions are met.
+
+.. note:: Hunter packages are built at configure time. When using a multi-config generator, they will default to Release.
+
+Options
+*******
+
+.. glossary::
+
+    VisualT_BUILD_SHARED_LIBS
+        type: ``BOOL`` |n|
+        default: ``NO`` |n|
+        Build all libraries (VisualT and modules) as shared libraries. A more specific alternative to :term:`BUILD_SHARED_LIBS`, otherwise completely equivalent.
+
+    VisualT_ASSUME_LITTLE_ENDIAN
+        type: ``BOOL`` |n|
+        default ``NO`` |n|
+        Skip CMake endianness detection (which can take a bit long), and assume a little endian system, like all x86/x86-64 cpus.
+
+    VisualT_PYTHON_VENV
+        type: ``PATH`` |n|
+        default: ``""`` |n|
+        Path to a python venv where Sphinx is installed. If your python packages are installed under an unconventional path, use this option to let CMake find them.
+
+    VisualT_XP_IMPORTER
+        type: ``BOOL`` |n|
+        default: ``NO`` |n|
+        Enable the .xp file import module, and adds a zlib dependency that will be downloaded through Hunter.
+
+.. rubric:: Common CMake options
+
+.. glossary::
+
+    `BUILD_SHARED_LIBS <https://cmake.org/cmake/help/v3.17/variable/BUILD_SHARED_LIBS.html>`_
+        The standard way to select the type of libraries.
+
+    `CMAKE_POSITION_INDEPENDENT_CODE <https://cmake.org/cmake/help/v3.17/variable/CMAKE_POSITION_INDEPENDENT_CODE.html>`_
+        This is useful when you want to link a static VisualT to a shared library (instead of an executable). When building static libraries, the export of symbols is automatically disabled, to prevent them from "bleeding out" when linked to shared libraries.
+
+Targets
+*******
+
+A list of all targets that can be defined by VisualT. If specified, the target is defined only if the respective *condition* is met.
+
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+|            target            |                conditions                 |                                description                                 |
++==============================+===========================================+============================================================================+
+| VisualT_library              | none                                      | The VisualT library.                                                       |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VisualT_tests                | none                                      | Some visual feedback tests for VisualT. Currently not very indicative.     |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VisualT_xp_importer          | :term:`VisualT_XP_IMPORTER`               | The .xp file import module.                                                |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VisualT_doxygen_generate_xml | root project, doxygen found               | Step 1/2 for generating documentation.                                     |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VisualT_sphinx_generate_html | root project, doxygen found, sphinx found | Step 2/2 for generating documentation.                                     |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VTExamples_demo              | root project                              | An example showcasing a variety of VisualT's features, starring the VTCat. |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VTExamples_car               | root project                              | An example of a proof of concept game with non-blocking input.             |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+| VTExamples_waves             | root project                              | An example showcasing the pen feature.                                     |
++------------------------------+-------------------------------------------+----------------------------------------------------------------------------+
+
+Install Components
+******************
+
+A list of all install components that can be defined by VisualT. If specified, the component is defined only if the respective *condition* is met. Each component is paired with an export set with the same name. Component dependencies are checked by the config package file.
+
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+|       component       |                          targets                           |    dependencies     |         conditions          |                        description                        |
++=======================+============================================================+=====================+=============================+===========================================================+
+| VisualT_runtime       | VisualT_library                                            | none                | none                        | The VisualT library binaries.                             |
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+| VisualT_development   | VisualT_library                                            | VisualT_runtime     | none                        | The VisualT library public header.                        |
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+| VisualT_xp_importer   | VisualT_xp_importer                                        | VisualT_runtime     | :term:`VisualT_XP_IMPORTER` | The .xp file importer module binaries and public headers. |
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+| VisualT_documentation | VisualT_doxygen_generate_xml, VisualT_sphinx_generate_html | none                | root project, sphinx found  | The html documentation.                                   |
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+| VisualT_examples      | VTExamples_demo, VTExamples_car, VTExamples_waves          | VisualT_development | root project                | The examples, as a standalone CMake project.              |
++-----------------------+------------------------------------------------------------+---------------------+-----------------------------+-----------------------------------------------------------+
+
diff --git a/doc/build/specs.rst b/doc/build/specs.rst
diff --git a/doc/importers/import-xp.rst b/doc/importers/import-xp.rst
@@ -44,7 +44,7 @@ CMake specs
 | dependencies | VisualT_runtime             |
 +--------------+-----------------------------+
 
-See more on :doc:`/build/specs`.
+See more on :doc:`/build`.
 
 API
 ***

diff --git a/doc/index.rst b/doc/index.rst
@@ -38,4 +38,4 @@ If you appreciated the work, leave a star on the `GitHub repo <https://github.co
 
 .. rubric:: VisualT's dependencies are managed by the `Hunter Package Manager <https://github.com/cpp-pm/hunter>`_:
 
-Hunter is a CMake powered package manager, which means it's completely *written* in CMake! Other than being inherently cross-patform, it offers a CMake-friendly interface for every package, which is a precious quality. It is also committed to complying with modern CMake best practices. If you're starting a new project, give it a try, and spread the word!
+Hunter is a CMake-powered package manager, it's completely *written* in CMake. Other than being inherently cross-patform, it offers a CMake-friendly interface for every available package, which is a quite valuable feature. It is also committed to complying with modern CMake best practices. If you're starting a new project, give it a try, and spread the word!
diff --git a/doc/readthedocs/ci.cmake b/doc/readthedocs/ci.cmake
@@ -0,0 +1,10 @@
+set(cwd "${CMAKE_CURRENT_LIST_DIR}/../..")
+
+file(COPY "${cwd}/doc/" DESTINATION ${CMAKE_CURRENT_LIST_DIR}
+     PATTERN "readthedocs" EXCLUDE)
+
+execute_process(COMMAND ${CMAKE_COMMAND} -D VisualT_ASSUME_LITTLE_ENDIAN:BOOL=YES -S . -B build
+                COMMAND ${CMAKE_COMMAND} --build build --target VisualT_doxygen_generate_xml
+                WORKING_DIRECTORY ${cwd}
+                COMMAND_ECHO STDOUT
+                COMMAND_ERROR_IS_FATAL ANY)
diff --git a/doc/readthedocs/conf.py b/doc/readthedocs/conf.py
@@ -2,8 +2,6 @@
 
 import subprocess
 
-subprocess.run(["cmake -P copy.cmake"], shell=True, check=True)
-subprocess.run(["cmake -D VisualT_ASSUME_LITTLE_ENDIAN:BOOL=YES -S . -B build"], cwd="../..", shell=True, check=True)
-subprocess.run(["cmake --build build --target VisualT_doxygen_generate_xml"], cwd="../..", shell=True, check=True)
+subprocess.run(["cmake -P ci.cmake"], check=True)
 with open("../../build/doc/conf.py") as infile:
     exec(infile.read())
diff --git a/doc/readthedocs/copy.cmake b/doc/readthedocs/copy.cmake
diff --git a/examples/cmake/context-specific.cmake b/examples/cmake/context-specific.cmake
@@ -1,5 +1,7 @@
 list(APPEND CMAKE_MODULE_PATH "${VisualT_SOURCE_DIR}/cmake")
 set(install_dir "${CMAKE_INSTALL_DATADIR}/VTExamples")
+set_property(DIRECTORY
+             PROPERTY EXCLUDE_FROM_ALL YES)
 
 #=============================
 # Installation

diff --git a/src/import-xp/CMakeLists.txt b/src/import-xp/CMakeLists.txt
@@ -65,7 +65,7 @@ target_link_libraries(VisualT_import_xp PRIVATE
                       ZLIB::ZLIB)
 # disable linker warnings about missing zlib .pdb files on windows
 target_link_options(VisualT_import_xp
-                    PRIVATE "$<$<C_COMPILER_ID:MSVC>:LINKER:/ignore:4099>")
+                    PUBLIC "$<$<C_COMPILER_ID:MSVC>:LINKER:/ignore:4099>")
 set_target_properties(VisualT_import_xp PROPERTIES
                       OUTPUT_NAME importXp
                       EXPORT_NAME import_xp