Pour notre projet Qasari, c'est un projet moderne, donc on fait dans les règles de l'art pour la gestion de projet et on va donc utiliser plusieurs outils:
- Cmake (pour automatiser le build)
- Conan (Package manager, pour la gestion de lib)
- Doxygen (la doc extraite du code depuis les commentaires)
- Sphinx (Générateur et mise en page de la doc)
Comme je le disais, je suis très sévère dans la structure du projet de base, un mauvais projet, c'est un peu le foutoir, le code est mal architecturé, hors Qasari doit être modulaire, de plus des les premières lignes de code on doit gérer la documentation et tout commenter pour permettre la collaboration mais également pour analyser le code.
On va utiliser Conan pour gérer tout de suite note wrapper Lua via la lib LuaBridge dans notre code.
Installation sous Arch Linux
sudo pacman -S cmake doxygen
Arborescence du projet:
qasari/
├── src/
│ ├── main.cpp
├── module/
│ ├── init_project.cpp
│ ├── nanite.cpp
│ └── module.cpp
├── include/
│ └── myheader.h
├── docs/
│ ├── Doxyfile
│ ├── conf.py
│ ├── index.rst
│ ├── Makefile
│ ├── build/
│ └── ...
├── CMakeLists.txt
└── conanfile.txt
Pensez à installer cmake, puis configurer le fichier CmakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(Qasari VERSION 0.1.0 LANGUAGES CXX)
# Chercher LLVM
find_package(LLVM REQUIRED CONFIG)
# Inclure les fichiers de configuration de LLVM
include_directories(${LLVM_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})
# Utiliser Clang comme compilateur
set(CMAKE_C_COMPILER clang)
set(CMAKE_CXX_COMPILER clang++)
# Options de compilation
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra")
# Standard de compilation
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# Mode Debug par défaut
if(NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE Debug)
endif()
# Générer compile_commands.json pour l'intégration avec les éditeurs comme Neovim
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
# Inclure les fichiers Conan
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup()
# Ajouter les fichiers source et headers
file(GLOB_RECURSE SOURCES "src/*.cpp")
file(GLOB_RECURSE HEADERS "include/*.hpp")
# Rechercher tous les fichiers .cpp dans le répertoire module
file(GLOB_RECURSE MODULE_SOURCES "module/*.cpp")
# Créer une bibliothèque partagée pour chaque fichier source dans module/
foreach(SOURCE ${MODULE_SOURCES})
get_filename_component(LIB_NAME ${SOURCE} NAME_WE)
add_library(${LIB_NAME} SHARED ${SOURCE})
# Inclure les headers pour chaque bibliothèque
target_include_directories(${LIB_NAME} PUBLIC ${CMAKE_SOURCE_DIR}/include)
# Spécifier les propriétés des bibliothèques dynamiques
set_target_properties(${LIB_NAME} PROPERTIES VERSION ${PROJECT_VERSION})
set_target_properties(${LIB_NAME} PROPERTIES SOVERSION 1)
set_target_properties(${LIB_NAME} PROPERTIES PUBLIC_HEADER "${HEADERS}")
endforeach()
# Créer un exécutable
add_executable(qasari src/main.cpp)
# Lier LLVM à l'executable
target_link_libraries(qasari ${LLVM_LIBRARIES})
# Lier la bibliothèque dynamique à l'exécutable
target_link_libraries(qasari PRIVATE qasari ${CONAN_LIBS})
# Ajouter chaque bibliothèque partagée à l'exécutable
foreach(SOURCE ${MODULE_SOURCES})
get_filename_component(LIB_NAME ${SOURCE} NAME_WE)
target_link_libraries(qasari PRIVATE ${LIB_NAME})
endforeach
# Inclure les dossiers pour les headers
target_include_directories(qasari PRIVATE ${CMAKE_SOURCE_DIR}/include)
# Ajout de la génération de documentation avec Doxygen et Sphinx
find_package(Doxygen REQUIRED)
find_package(Python3 REQUIRED)
# Configuration Doxygen
set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile)
set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen)
add_custom_target(doxygen ALL
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_IN}
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
COMMENT "Generating API documentation with Doxygen"
VERBATIM)
# Configuration Sphinx
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/docs)
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/docs/build)
add_custom_target(sphinx ALL
COMMAND ${Python3_EXECUTABLE} -m sphinx -b html ${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${SPHINX_SOURCE}
COMMENT "Generating documentation with Sphinx"
VERBATIM)
# Dépendance entre Sphinx et Doxygen
add_dependencies(sphinx doxygen)
Configuration de Conan pour intégrer LuaBridge
Installation des dépendances
pip install conan
Editer le fichier conanfile.txt
[requires]
luabridge/2.7.0
[generators]
cmake
Exemple de fichiers de configuration pour Doxygen
docs/Doxyfile
Vous pouvez générer un fichier Doxyfile par défaut avec la commande doxygen -g docs/Doxyfile, puis le modifier. Voici un exemple de configuration de base :
# Doxyfile
# Project-related settings
PROJECT_NAME = MyProject
OUTPUT_DIRECTORY = docs/doxygen
# Input
INPUT = ../src ../include ../module
RECURSIVE = YES
# HTML output
GENERATE_HTML = NO
# Générer du XML pour Breathe
GENERATE_XML = YES
XML_OUTPUT = doxygen/xml # Chemin relatif où les fichiers XML seront générés
# Use MATHJAX for math rendering
USE_MATHJAX = YES
# Call graph generation
CALL_GRAPH = YES
Installer les dépendances :
Assurez-vous d'avoir Doxygen et Python avec Sphinx et Breathe installés. Vous pouvez installer Sphinx et Breathe avec pip :
pip install sphinx breathe
Configuration de Sphinx
Exécutez la commande sphinx-quickstart :
Ouvrez un terminal et exécutez la commande suivante dans le répertoire docs de votre projet :
sphinx-quickstart
La commande sphinx-quickstart vous guidera à travers une série de questions pour configurer votre projet Sphinx. Voici quelques points clés que vous devrez spécifier :
- Root path for the documentation: Laissez-le par défaut (.).
- Separate source and build directories: Répondez n (yes) à cette question.
- Project name: Donnez un nom à votre projet.
- Author name(s): Votre nom ou le nom de l'équipe.
- Project release: Laissez-le vide si vous n'avez pas de version spécifique.
- Project language: Choisissez votre langue préférée (par exemple, en pour l'anglais).
- Source file suffix: Laissez-le par défaut (rst).
Après avoir exécuté sphinx-quickstart, vous aurez une structure de répertoires initiale sous docs. Vous pouvez personnaliser les fichiers générés pour correspondre à votre projet spécifique :
- index.rst: Ce fichier est le point d'entrée de votre documentation. Vous pouvez ajouter des sections (toctree) pour organiser vos pages.
- conf.py: Ce fichier contient la configuration de Sphinx. Vous devrez ajouter des extensions comme breathe pour intégrer la documentation générée par Doxygen.
docs/conf.py
Ceci est un exemple de fichier de configuration Sphinx (docs/conf.py) :
# Configuration file for the Sphinx documentation builder.
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))
# Project information
project = 'MyProject'
copyright = '2023, MyName'
author = 'MyName'
# General configuration
extensions = [
'breathe',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
]
templates_path = ['_templates']
exclude_patterns = []
# Options for HTML output
html_theme = 'alabaster'
html_static_path = ['_static']
# Breathe configuration
breathe_projects = {
"MyProject": "../doxygen/xml"
}
breathe_default_project = "MyProject"
docs/index.rst
Ceci est un exemple de fichier index.rst pour Sphinx :
.. MyProject documentation master file, created by
sphinx-quickstart on Tue Jul 14 00:00:00 2023.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to MyProject's documentation!
=====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
api
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Configurer le projet avec Cmake et Conan
mkdir build
cd build
conan install ..
cmake ..
Construire le projet et générer la documentation
cmake --build .
La documentation générée sera disponible dans build/docs/build.