Merge pull request #1057 from dlyr/1055-doc-move-all-reference-to-req…

…uirements-and-supported-ide-into-one-place 1055 doc move all reference to requirements and supported ide into one place
STORM-IRIT · Jul 26, 2023 · a349c0c · a349c0c
2 parents a2035eb + 34e81bd
commit a349c0c
Show file tree

Hide file tree

Showing 16 changed files with 549 additions and 547 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -99,34 +99,61 @@ if(DOXYGEN_FOUND)
         "${CMAKE_CURRENT_SOURCE_DIR}/LICENSES.md"
     )
 
-    set(DOXYGEN_PROJECT_NAME "Radium Engine")
-    set(DOXYGEN_PROJECT_NUMBER "${RADIUM_PROJECT_NUMBER}")
-    set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/images/radium-logo.png")
-    set(DOXYGEN_EXTENSION_MAPPING "dox=C++" "inl=C++")
+    set(DOXYGEN_ALIASES [[complexity="@par Complexity:^^"]])
     set(DOXYGEN_BUILTIN_STL_SUPPORT "YES")
-    set(DOXYGEN_EXTRACT_ALL "NO")
-    set(DOXYGEN_EXTRACT_STATIC "YES")
-    set(DOXYGEN_SHOW_GROUPED_MEMB_INC "YES")
-    set(DOXYGEN_FORCE_LOCAL_INCLUDES "NO")
-    set(DOXYGEN_RECURSIVE "YES")
-    set(DOXYGEN_STRIP_FROM_INC_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../src")
+    set(DOXYGEN_CALL_GRAPH "YES")
+    set(DOXYGEN_COLS_IN_ALPHA_INDEX "2")
+    set(DOXYGEN_DOCSET_BUNDLE_ID "com.storm-irit.RadiumEngine")
+    set(DOXYGEN_DOCSET_PUBLISHER_NAME "IRIT")
+    set(DOXYGEN_DOT_GRAPH_MAX_NODES "60")
+    set(DOXYGEN_DOT_IMAGE_FORMAT "svg")
+    set(DOXYGEN_EXAMPLE_RECURSIVE "YES")
     set(DOXYGEN_EXAMPLE_PATH
         "${CMAKE_CURRENT_SOURCE_DIR}/../tests" "${CMAKE_CURRENT_SOURCE_DIR}/../examples/"
         "${CMAKE_CURRENT_SOURCE_DIR}/../src"
     )
     set(DOXYGEN_EXAMPLE_PATTERNS "*.cpp" "*.h" "*.cu")
-    set(DOXYGEN_EXAMPLE_RECURSIVE "YES")
     set(DOXYGEN_EXCLUDE_PATTERNS "*/src/Headless/CLI/*")
-    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${RADIUM_MAIN_DOC_FILE}")
-    set(DOXYGEN_SOURCE_BROWSER "YES")
-    set(DOXYGEN_REFERENCES_LINK_SOURCE "NO")
-    set(DOXYGEN_COLS_IN_ALPHA_INDEX "2")
-    set(DOXYGEN_HTML_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/header.html")
+    set(DOXYGEN_EXPAND_ONLY_PREDEF "YES")
+    set(DOXYGEN_EXTENSION_MAPPING "dox=C++" "inl=C++")
+    set(DOXYGEN_EXTRACT_ALL "NO")
+    set(DOXYGEN_EXTRACT_STATIC "YES")
+    set(DOXYGEN_EXT_LINKS_IN_WINDOW "YES")
+    set(DOXYGEN_FORCE_LOCAL_INCLUDES "NO")
+    set(DOXYGEN_GENERATE_TREEVIEW "YES")
+    set(DOXYGEN_HAVE_DOT "YES")
+    set(DOXYGEN_HIDE_UNDOC_CLASSES "YES")
+    set(DOXYGEN_HIDE_UNDOC_RELATIONS "NO")
+    set(DOXYGEN_HTML_COLORSTYLE_GAMMA "160")
     set(DOXYGEN_HTML_COLORSTYLE_HUE "40")
     set(DOXYGEN_HTML_COLORSTYLE_SAT "50")
-    set(DOXYGEN_HTML_COLORSTYLE_GAMMA "160")
-    set(DOXYGEN_HTML_TIMESTAMP "YES")
     set(DOXYGEN_HTML_DYNAMIC_SECTIONS "YES")
+    set(DOXYGEN_HTML_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/header.html")
+    set(DOXYGEN_HTML_TIMESTAMP "YES")
+    set(DOXYGEN_IMAGE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/images")
+    set(DOXYGEN_INCLUDE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../src")
+    set(DOXYGEN_INTERACTIVE_SVG "YES")
+    set(DOXYGEN_MACRO_EXPANSION "YES")
+    set(DOXYGEN_MATHJAX_EXTENSIONS "TeX/AMSsymbols" "TeX/AMSmath")
+    set(DOXYGEN_MATHJAX_RELPATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/")
+    set(DOXYGEN_PREDEFINED "PARSED_BY_DOXYGEN MULTIARCH= ")
+    set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/images/radium-logo.png")
+    set(DOXYGEN_PROJECT_NAME "Radium Engine")
+    set(DOXYGEN_PROJECT_NUMBER "${RADIUM_PROJECT_NUMBER}")
+    set(DOXYGEN_RECURSIVE "YES")
+    set(DOXYGEN_REFERENCES_LINK_SOURCE "NO")
+    set(DOXYGEN_SHOW_GROUPED_MEMB_INC "YES")
+    set(DOXYGEN_SOURCE_BROWSER "YES")
+    set(DOXYGEN_STRIP_FROM_INC_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../src")
+    set(DOXYGEN_TEMPLATE_RELATIONS "YES")
+    set(DOXYGEN_TOC_INCLUDE_HEADINGS "2")
+    set(DOXYGEN_UML_LIMIT_NUM_FIELDS "50")
+    set(DOXYGEN_UML_LOOK "YES")
+    set(DOXYGEN_USE_MATHJAX "YES")
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${RADIUM_MAIN_DOC_FILE}")
+    set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
+    set(DOXYGEN_WARN_IF_UNDOCUMENTED "NO")
+
     if(USE_AWESOME_CSS)
         set(DOXYGEN_HTML_EXTRA_STYLESHEET
             "${RADIUM_DOXYGEN_AWESOME_CSS}"
@@ -140,32 +167,6 @@ if(DOXYGEN_FOUND)
             "${RADIUM_DOXYGEN_AWESOME_CSS_ROOT}/doxygen-awesome-paragraph-link.js"
         )
     endif()
-    set(DOXYGEN_HIDE_UNDOC_CLASSES "YES")
-
-    set(DOXYGEN_DOCSET_BUNDLE_ID "com.storm-irit.RadiumEngine")
-    set(DOXYGEN_DOCSET_PUBLISHER_NAME "IRIT")
-    set(DOXYGEN_GENERATE_TREEVIEW "YES")
-    set(DOXYGEN_EXT_LINKS_IN_WINDOW "YES")
-    set(DOXYGEN_USE_MATHJAX "YES")
-    set(DOXYGEN_MATHJAX_RELPATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/")
-    set(DOXYGEN_MATHJAX_EXTENSIONS "TeX/AMSsymbols" "TeX/AMSmath")
-    set(DOXYGEN_MACRO_EXPANSION "YES")
-    set(DOXYGEN_EXPAND_ONLY_PREDEF "YES")
-    set(DOXYGEN_INCLUDE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../src")
-    set(DOXYGEN_PREDEFINED "PARSED_BY_DOXYGEN MULTIARCH= ")
-    set(DOXYGEN_HIDE_UNDOC_RELATIONS "NO")
-    set(DOXYGEN_HAVE_DOT "YES")
-    set(DOXYGEN_UML_LOOK "YES")
-    set(DOXYGEN_UML_LIMIT_NUM_FIELDS "50")
-    set(DOXYGEN_TEMPLATE_RELATIONS "YES")
-    set(DOXYGEN_CALL_GRAPH "YES")
-    set(DOXYGEN_DOT_IMAGE_FORMAT "svg")
-    set(DOXYGEN_INTERACTIVE_SVG "YES")
-    set(DOXYGEN_TOC_INCLUDE_HEADINGS "2")
-    set(DOXYGEN_IMAGE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/images")
-    set(DOXYGEN_DOT_GRAPH_MAX_NODES "60")
-    set(DOXYGEN_ALIASES [[complexity="@par Complexity:^^"]])
-    set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
     # resolve std to cpp ref
     # https://upload.cppreference.com/mwiki/images/f/f8/cppreference-doxygen-web.tag.xml
     set(DOXYGEN_TAGFILES

diff --git a/doc/basics.md b/doc/basics.md
@@ -3,7 +3,65 @@
 
 This part of the documentation describes how to compile Radium and use it in your own project.
 
-TL;DR; command line version.
+## Supported system and compilers
+
+The following platforms and tool chains have been tested and should work :
+
+* CMake 3.18+
+* *Windows* : IDEs: Visual Studio 2019, 2022 (2017 is not supported due to embedded cmake version), QtCreator. Command Line: cmake+ninja+MSVC(2017, 2019, 2022) .
+* *Mac OSX* : gcc 10 or higher, Apple clang, llvm clang 11 or higher
+* *Linux* : gcc 8  or higher, clang
+
+See also our Continuous Integration system at <https://github.com/STORM-IRIT/Radium-Engine/actions>.
+
+## System wide dependencies
+
+Radium expects the following dependencies to be available during compilation.
+
+* [Engine]
+  * OpenGL 4.1+ / GLSL 410+
+* [Gui]
+  * Qt Core/Widgets/OpenGL 5.15 or 6.2+
+* [Headless] One, or both of
+  * EGL
+  * glfw 3.3
+
+## External dependencies (included with radium)
+
+These dependencies are shipped with radium, fetching external git sources.
+
+<!--  (generated running ../scripts/list_dep.py from Radium-Engine/external directory) -->
+* [IO]
+  * assimp: https://github.com/assimp/assimp.git, [tags/v5.0.1],
+    * with options `-DASSIMP_BUILD_ASSIMP_TOOLS=False -DASSIMP_BUILD_SAMPLES=False -DASSIMP_BUILD_TESTS=False -DIGNORE_GIT_HASH=True -DASSIMP_NO_EXPORT=True`
+  * tinyply: https://github.com/ddiakopoulos/tinyply.git, [tags/2.3.2],
+    * with options `-DSHARED_LIB=TRUE`
+* [Gui]
+  * PowerSlider: https://github.com/dlyr/PowerSlider.git, [origin/master],
+    * with options `-DBUILD_DESIGNER_PLUGIN=OFF -DBUILD_EXAMPLE_APP=OFF`
+* [Engine]
+  * glm: https://github.com/g-truc/glm.git, [cc98465e3508535ba8c7f6208df934c156a018dc],
+    * with options `-DGLM_TEST_ENABLE=OFF -DBUILD_STATIC_LIBS=OFF -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>`
+  * glbinding: https://github.com/cginternals/glbinding.git, [758d33b4d4f1815d46d91fcf4ca4914d837267fa],
+    * with options `-DOPTION_BUILD_TESTS=OFF -DOPTION_BUILD_DOCS=OFF -DOPTION_BUILD_TOOLS=OFF -DOPTION_BUILD_EXAMPLES=OFF -DOPTION_BUILD_OWN_KHR_HEADERS=ON -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>`
+  * globjects: https://github.com/cginternals/globjects.git, [4363356ae2ef5c936ab078fba48d1ea507c295c4],
+    * with options `-DOPTION_BUILD_DOCS=OFF -DOPTION_BUILD_EXAMPLES=OFF -DOPTION_USE_EIGEN=ON -Dglbinding_DIR=${glbinding_DIR} -Dglm_DIR=${glm_DIR} -DEigen3_DIR=${Eigen3_DIR} -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>`
+  * stb: https://github.com/nothings/stb.git, [1034f5e5c4809ea0a7f4387e0cd37c5184de3cdd],
+    * with options `None`
+  * tinyEXR: https://github.com/MathiasPaulin/tinyexr.git, [origin/radium],
+    * with options `-DBUILD_INSTALLABLE_LIB=ON`
+* [Core]
+  * Eigen3: https://gitlab.com/libeigen/eigen.git, [tags/3.4.0],
+    * with options `-DEIGEN_TEST_CXX11=OFF -DBUILD_TESTING=OFF -DEIGEN_BUILD_DOC=OFF`
+  * OpenMesh: https://www.graphics.rwth-aachen.de:9000/OpenMesh/OpenMesh.git, [tags/OpenMesh-8.1],
+    * with options `-DBUILD_APPS=OFF`
+  * cpplocate: https://github.com/cginternals/cpplocate.git, [tags/v2.2.0],
+    * with options `-DOPTION_BUILD_TESTS=OFF -DOPTION_BUILD_DOCS=OFF -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>`
+  * nlohmann_json: https://github.com/nlohmann/json.git, [tags/v3.10.5],
+    * with options `-DJSON_Install=ON -DJSON_BuildTests=OFF`
+<!--  (end script copy) -->
+
+## TL;DR; command line version
 
 ```bash
 git clone --recurse-submodules https://github.com/STORM-IRIT/Radium-Engine.git
@@ -30,7 +88,8 @@ default Radium-Engine install prefix is `Radium-Engine/Bundle-${CMAKE_CXX_COMPIL
 
 More details and other systems information (including visual studio setup) are in the following pages, to be read in order.
 
-* \subpage dependenciesmanagement : Fetch and compile dependencies
-* \subpage basicsCompileRadium : Compile and install Radium
+* \subpage basicsCompileVs
+* \subpage basicsCompileCommand
 * \subpage basicsRadiumSubmodule : Link to Radium using cmake package
+* \subpage basicsCompileRadiumDetails
 * \subpage basicsTroubleshooting : Handle usual errors
diff --git a/doc/basics/commandline.md b/doc/basics/commandline.md
@@ -0,0 +1,45 @@
+\page basicsCompileCommand Commandline Compilation Instructions (Linux, macos...)
+
+# Building and installing Radium dependencies once for all {#builddep}
+
+We provide a standalone cmake project (`Radium-Engine/external/CMakeLists.txt`) to compile and install the Radium dependencies at any location.
+
+## Configuration and compilation of the dependencies
+
+For command line, tested on Linux and mac OS, **for windows might need more configuration options**.
+
+External dependencies have to be installed outside Radium-Engine source tree.
+
+~~~{.bash}
+# from wherever you want outside radium source tree
+# in release
+cmake -S Radium-Engine/external -B builds/radium-external-build-r -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=installs/radium-external-r
+cmake --build builds/radium-external-build-r --config Release --parallel
+
+# in debug
+cmake -S Radium-Engine/external -B builds/radium-external-build-d -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=installs/radium-external-d
+cmake --build builds/radium-external-build-d --config Debug --parallel
+~~~
+
+If not given on the command line, the installation directory is set by default to `Radium-Engine/{CMAKE_CURRENT_BINARY_DIR}/Bundle-${CMAKE_CXX_COMPILER_ID}` for `CMAKE_BUILD_TYPE=Release`, and  `Radium-Engine/{CMAKE_CURRENT_BINARY_DIR}/Bundle-${CMAKE_CXX_COMPILER_ID}-${CMAKE_BUILD_TYPE}` for any other `CMAKE_BUILD_TYPE`.
+
+## Command line instructions (linux, macos, windows)
+
+For command line, tested on Linux and mac OS, **for windows might need more configuration options**.
+
+Follow the usual sequence, assuming you have build dependencies as explained [here](@ref builddep):
+
+~~~{.bash}
+cmake -S Radium-Engine -B builds/radium-build-r -DCMAKE_BUILD_TYPE=Release -C installs/radium-external-r/radium-options.cmake
+cmake --build builds/radium-build-r --config Release --parallel -DQt5_DIR=path/to/qt5
+cmake --install builds/radium-build-r
+~~~
+
+If Qt is installed system wide (likely on linux), `-DQt5_DIR` is not needed.
+
+\note Qt6 is also supported. To enable it, replace `-DQt5_DIR=path/to/qt5` by `-DQt6_DIR=path/to/qt6`. To ease maintenance accross Qt versions, you should also configure the path to Qt cmake package using `-DCMAKE_PREFIX_PATH=path/to/qtX` where `X` is the Qt version you want to use.
+
+If both Qt5 and Qt6 are installed system wide, Qt6 is the default, `-DQT_DEFAULT_MAJOR_VERSION=5` allow select Qt5. During client application cmake setup `find_package(Radium COMPONENTS ... Gui ...)` will check Qt version consistency.
+
+\note Running `cmake --install` is recommended as it will copy all the radium related library in the same place,
+generate the cmake packages and bundle applications with their dependencies (on macos and windows).