Improve doc

doc/CMakeLists.txt

@@ -73,6 +73,37 @@ if(DOXYGEN_FOUND)
         set(GIT_CHANGESET "")
     endif()
 
+    # Get awesome css
+    set(RADIUM_DOXYGEN_AWESOME_CSS_ROOT
+        "${CMAKE_CURRENT_SOURCE_DIR}/../external/doxygen-awesome-css"
+    )
+    set(RADIUM_DOXYGEN_AWESOME_CSS "${RADIUM_DOXYGEN_AWESOME_CSS_ROOT}/doxygen-awesome.css")
+    set(USE_AWESOME_CSS YES)
+    if(NOT EXISTS "${RADIUM_DOXYGEN_AWESOME_CSS}")
+        set(USE_AWESOME_CSS OFF)
+        if(GIT_FOUND AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../.git")
+            execute_process(
+                COMMAND ${GIT_EXECUTABLE} submodule update --init ${RADIUM_DOXYGEN_AWESOME_CSS_ROOT}
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} RESULT_VARIABLE GIT_SUBMOD_RESULT
+            )
+            if(NOT GIT_SUBMOD_RESULT EQUAL "0")
+                message(
+                    FATAL_ERROR
+                        "git submodule update --init ${DOXYGEN_AWESOME_CSS_ROOT} failed with ${GIT_SUBMOD_RESULT}, please checkout submodules"
+                )
+            else()
+                set(USE_AWESOME_CSS YES)
+            endif()
+            set(RADIUM_DOXYGEN_AWESOME_CSS
+                "${RADIUM_DOXYGEN_AWESOME_CSS}"
+                "${RADIUM_DOXYGEN_AWESOME_CSS_ROOT}/doxygen-awesome-sidebar-only.css"
+            )
+        else()
+            set(RADIUM_DOXYGEN_AWESOME_CSS "")
+        endif()
+    endif()
+    message(STATUS "Use Doxygen Awesome CSS?                  ${USE_AWESOME_CSS}")
+
     set(RADIUM_PROJECT_NUMBER ${GIT_CHANGESET})
 
     # be nice with IDE: add .md files
@@ -109,10 +140,7 @@ if(DOXYGEN_FOUND)
     set(DOXYGEN_HTML_COLORSTYLE_GAMMA "160")
     set(DOXYGEN_HTML_TIMESTAMP "YES")
     set(DOXYGEN_HTML_DYNAMIC_SECTIONS "YES")
-    set(DOXYGEN_HTML_EXTRA_STYLESHEET
-        "${CMAKE_CURRENT_SOURCE_DIR}/../external/doxygen-awesome-css/doxygen-awesome.css"
-        "${CMAKE_CURRENT_SOURCE_DIR}/../external/doxygen-awesome-css/doxygen-awesome-sidebar-only.css"
-    )
+    set(DOXYGEN_HTML_EXTRA_STYLESHEET ${RADIUM_DOXYGEN_AWESOME_CSS})
     set(DOXYGEN_DOCSET_BUNDLE_ID "com.storm-irit.RadiumEngine")
     set(DOXYGEN_DOCSET_PUBLISHER_NAME "IRIT")
     set(DOXYGEN_GENERATE_TREEVIEW "YES")

doc/basics.md

@@ -1,6 +1,9 @@
 \page basicsmanual Radium Basics
 [TOC]
 
- * \subpage basicsCompileRadium
- * \subpage basicsRadiumSubmodule
- * \subpage basicsTroubleshooting
+This part of the documentation describes how to compile Radium and use it in your own project.
+If it is your first time with Radium, please follow the instructions in this order:
+ * \subpage dependenciesmanagement : Fetch and compile dependencies
+ * \subpage basicsCompileRadium : Compile and install Radium
+ * \subpage basicsRadiumSubmodule : Link to Radium using cmake package
+ * \subpage basicsTroubleshooting : Handle usual errors

doc/basics/compilation.md

@@ -1,20 +1,6 @@
-\page basicsCompileRadium Compilation instructions
+\page basicsCompileRadium Radium Compilation instructions
 [TOC]
 
-# Dependencies
-All the dependencies are automatically fetched and compiled at build time.
- * [Core] Eigen, OpenMesh
- * [Engine] glm, globjects, glbindings
- * [IO] Assimp
- * [Gui] Qt Core, Qt Widgets and Qt OpenGL v5.5+ (5.14 recommended)
- * stb_image
-
-\note See @ref develbuildchain for technical details on dependencies management and how to provide locally installed dependencies.
-
-Minimal requirements
- * OpenGL 3+ / GLSL 330+
- * CMake 3.15.7+
-
 # Supported compiler and platforms
 
 The following platforms and tool chains have been tested and should work :
@@ -23,25 +9,41 @@ The following platforms and tool chains have been tested and should work :
  * *Mac OSX* : gcc 10 or higher, Apple clang
  * *Linux* : gcc 8  or higher, clang
 
-## Continuous Integration:
- * *Linux (gcc10), Windows (MSVC 19.28.29335.0), and Mac OSX (AppleClang 12)* https://github.com/STORM-IRIT/Radium-Engine/actions
+See also our Continuous Integration system at https://github.com/STORM-IRIT/Radium-Engine/actions.
+
+Minimal requirements
+* OpenGL 4.1+ / GLSL 410+
+* CMake 3.15.7+
 
 # Build instructions
+If not already done, follow instructions at \ref dependenciesmanagement.
 
-## Getting dependencies
-They are automatically fetched by cmake at compile time.
-To force cmake re-fetching the dependencies, called
-~~~bash
-make update
-~~~
+Radium follows a standard cmake structure, so any IDE supporting cmake should be able to configure and build it.
+
+\note We strongly recommend to have dedicated build and install directories for each build type (Release, Debug).
+Remember that compiling Radium in Debug mode needs to have the dependencies compiled and installed in Debug mode
+(due to a limitation in assimp).
 
 ## Folder structure
-Radium-Engine relies on CMake buildchain on all supported platforms.
+Radium-Engine relies on CMake build-chain on all supported platforms.
 In most cases, building should be pretty straightforward, provided that cmake can locate the dependencies.
-If cmake doesn't locate the Qt files (e.g. if you manually installed Qt as opposed to using your distribution's package),
-see the troubleshooting section below.
 
-Build output is generated in the `Radium-Engine/Bundle-*` directory (with `*` the name of the CXX compiler, followed by the build type), with the following structure, if externals are compiled along Radium
+### Installation directory
+By default, `${CMAKE_INSTALL_PREFIX}` is set as follow:
+
+- For release build :
+
+~~~{.cmake}
+    set(RADIUM_BUNDLE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/Bundle-${CMAKE_CXX_COMPILER_ID})
+~~~
+
+- For Debug or RelWithDebInfo build
+
+~~~{.cmake}
+    set(RADIUM_BUNDLE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/Bundle-${CMAKE_CXX_COMPILER_ID}-${CMAKE_BUILD_TYPE})
+~~~
+
+It has the following structure, if externals are compiled along Radium
 ~~~
 Bundle-*
  - bin/  include/  lib/  libdata/  LICENSE  README.md  Resources/  share/
@@ -52,7 +54,7 @@ Bundle-*
  - bin/  include/  lib/  LICENSE  README.md  Resources/  share/
 ~~~
 
-## Configure build
+### Configure build options
 
 Radium offers the following build options:
 ~~~bash
@@ -118,52 +120,66 @@ All radium related cmake options (with their current values) can be printed with
 
 \warning For computers with low RAM capacities (under 12G) we recommend to set the `CMAKE_BUILD_PARALLEL_LEVEL` environment variable to a reasonable value (i.e. 2) to prevent the computer from swapping.
 
-##  Building on Linux/MacOS (command line instruction)
 
-Out-of source builds are mandatory, we recommand to follow the usual sequence:
+### Dependencies between libraries
 
-~~~bash
-$ mkdir build
-$ cd build
-$ cmake ..
-$ make
+The options `RADIUM_GENERATE_LIB_XXXX` allows to enable/disable each Radium library.
+The dependencies between libraries are set as follow:
+
+~~~{.cmake}
+add_dependencies (${ra_engine_target} PUBLIC Radium::Core)
+add_dependencies (${ra_io_target} PUBLIC Radium::Core)
+add_dependencies (${ra_pluginbase_target} Radium::Core Radium::Engine)
+add_dependencies (${ra_gui_target} PUBLIC Radium::Core Radium::Engine Radium::PluginBase Radium::IO)
 ~~~
 
-Finally, the `install` target will copy all the radium related library in the same place, usefull for App compilation
+\warning Consistency of `RADIUM_GENERATE_LIB_***` options is not checked wrt. the dependencies.
+
+- When enabled using `RADIUM_GENERATE_LIB_***`, each library has a compilation target: `Core`, `Engine`, ...
+
+
+
+## Command line instructions for building (on windows, mac and linux)
+
+Out-of source builds are mandatory, we recommend to follow the usual sequence:
 
 ~~~bash
+$ mkdir build
+$ cd build
+$ cmake .. -DQt5_DIR=........ -DCMAKE_BUILD_TYPE=.......
+$ make
 $ make install
 ~~~
 
+\note Running the `install` target 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).
+
 Note that installation requires write access on the installation directory.
 
-## Building on Microsoft Windows with Visual Studio
+## Integration with Visual Studio (Microsoft Windows)
 
 ### Supported versions of MSVC
 Radium requires MSVC 2019 or superior, as it relies on:
 * C++11/C++14/C++17 features such as `constexpr`,
 * cmake built-in support
 
 Our Continuous Integration systems uses Microsoft Compiler 2017, in combination with cmake and ninja.
-Using Visual Studio 2017 with cmake support is however not possible: VS is shipped with cmake: 3.12, while Radium requires cmake 3.13 at least. We recommand to use Visual Studio 2019 in that case.
+Using Visual Studio 2017 with cmake support is however not possible: VS is shipped with cmake: 3.12, while Radium requires cmake 3.13 at least. We recommend to use Visual Studio 2019 in that case.
 Qt 5.15+ is distributed with binaries precompiled with MSVC 2019, but Qt binaries precompiled with MSVC2017 does not break the build.
 
-### Dependencies
+### Qt Dependency
 
 *Qt* distributes precompiled libraries for VS 2017 - 64 bits (tested with 5.10 and 5.12).
 If using earlier versions of Qt (5.5)  or a different toolset you may have to compile Qt yourself.
-You will probaby have to manually point cmake to the Qt folder.
-
-Other dependencies (Eigen, Assimp, glbinding, globjects and glm) are fetched and compiled at configure-time if they are not present at this time on the host system (see @ref develbuildchain).
-
+You will probably have to manually point cmake to the Qt folder.
 
 ### Getting started with Visual Studio
 
 Thanks to the integrated support of CMake in Visual Studio, you don't need a VS solution to build your project: open the Radium folder (via *File* > *Open* > *Folder ...* or `devenv.exe <foldername>`).
 VS should run cmake, generate the target builds (Debug and Release by default).
 Other build types can be added by editing `CMakeSettings.json`.
 
-You may have Cmake errors occuring at the first run.
+You may have Cmake errors occurring at the first run.
 To fix them, you need to edit the VS-specific file `CMakeSettings.json`, via *CMake* > *Change CMake Settings* > path-to-CMakeLists (configuration-name) from the main menu.
 For instance, it usually requires to set cmake build types manually, and to give path to Qt libraries.
 To fix it, edit `CMakeSettings.json`, such that
@@ -195,17 +211,10 @@ To fix it, edit `CMakeSettings.json`, such that
   ]
 }
 ~~~
-*Note*: it is strongly encouraged to use `/` separators in your path, instead of `\\` as previously mentionned. See https://stackoverflow.com/questions/13737370/cmake-error-invalid-escape-sequence-u
-
-
+\note It is strongly encouraged to use `/` separators in your path, instead of `\\`. See https://stackoverflow.com/questions/13737370/cmake-error-invalid-escape-sequence-u
 *Note*: When compiling the dependencies you may hit the max path length fixed by Microsoft OS (260 characters). To fix this, you might need to change the path of your build dir to shorten it, or to change the limit on your system, see: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#enable-long-paths-in-windows-10-version-1607-and-later
 
 ### Compilation
 
 Right click on `CMakeList.txt > build > all`.
 To install, you need to run any installation target, e.g. `Engine.dll (install)` or to select the menu `<Build>/<Install radiumproject>`
-
-## Building with QtCreator
-
-QtCreator is supported on Windows, MacOS and Linux.
-No specific requirement here, just open Radium-Engine CMake project and enjoy !