Plantilla para proyectos C++

 

Cómo utilizar la plantilla

• Desde GitHub, clona esta plantilla y úsala al crear un nuevo Repositorio:
  • Repository name: Nombre de tu nuevo repositorio
  • Repository template: CppPlantilla
  • Include All Branches: [x] (Para que incluya gh-pages)
  • Description: Añadir una descripción opcional.
• Realiza los siguientes cambios para que se publique en tu GitHub Pages
  • Repositorio -> Settings -> Pages
    • Source: Deploy from a branch
    • Branch: gh-pages Directorio: /(root)) Clic en SAVE
  • Repositorio -> Settings -> Actions -> General
    • Workflow Permissions: Read and write
  • Modifica el fichero ./docs/Doxyfile y cambia la siguiente línea.
    • PROJECT_NAME = "C++ Plantilla LuisPa"
• Entra en tu cuenta de codecov.io y configura el nuevo repo.
  • CODECOV_TOKEN: Añade nuevo repository secret en Repo > settings > secrets ... > actions
  • .github/workflows/ubuntu.yml: Cambia (slug: TuCuentaGitHub/CppPlantilla) con tu usuario/repo.
• Verifica y adapta el fichero .vscode/settings.json a tus gustos.
• Modifica este fichero ./README.md
  • Cambia la primera línea por el título de tu proyecto
  • Cambia los enlaces a los cuatro Badges: C++, Licencia, Build, Codecov.
  • Cambia el contenido desde ## Cómo utilizar la plantilla por el tuyo.
• Empieza a codificar, cambia los fuentes incluidos como ejemplo:
  • ./tests/main.cc
  • ./src/my_lib/my_lib.cc
  • ./src/my_lib/my_lib.h
  • ./app/main.cc
• Revisa los CMakeLists.txt para indicar tus fuentes, librerías, gestores, etc.
  • ./CMakeLists.txt
  • ./src/my_lib/CMakeLists.txt
  • ./app/CMakeLists.txt
• Ejecuta pre-commit en la raiz del repo
  • $ pre-commit install
  • $ pre-commit run --all-files
• Sube el Repo actualizado
  • `$ git add. && git commit -am "repo actualizado" && git push

 

Qué es esta plantilla?

Puedes utilizarla a la hora de crear un repositorio nuevo para un proyecto C++ en tu cuenta de GitHub. Incluye todo lo siguiente:

• Buenas prácticas separando los fuentes y las cabeceras en carpetas distintas
• Uso de CMake para construir y compilar
• Soporte de bibliotecas externas, usando uno de los tres siguientes gestores:
  • Gestor de paquetes CPM
  • Gestor de paquetes Conan
  • Gestor de paquetes VCPKG
  • Incluye varias bibliotecas de propósito general a modo de ejemplo: JSON, spdlog, cxxopts y fmt
• Incluye Unit Tests con Catch2 v2
• Pruebas de integración continua con Github Actions y pre-commit
• Informes de cobertura del código, incluida la carga automática a Codecov
• Documentación del código con Doxygen y Github Pages
• Herramientas: Clang-Format, Cmake-Format, Clang-tidy, Sanitizers

 

Estructura

├── CMakeLists.txt
├── app
│   ├── CMakesLists.txt
│   └── main.cc
├── cmake
│   └── cmake modules
├── docs
│   ├── Doxyfile
│   └── html/
├── external
│   ├── CMakesLists.txt
│   ├── ...
├── src
│   ├── CMakesLists.txt
│   ├── my_lib.h
│   └── my_lib.cc
└── tests
    ├── CMakeLists.txt
    └── main.cc

El código de la librería está en src/, el programa en app/ y los tests en tests/.

 

Requisitos de software

• CMake 3.21+
  • sudo apt install cmake -y
• GNU Makefile
• Doxygen
• Conan or VCPKG
• MSVC >= 2017, G++ >= 9, Clang++ >= 9
• Opcional: Code Coverage (Solo sobre GNU|Clang): lcov, gcovr
• Optional: Makefile, Doxygen, Conan, VCPKG

 

Instalación y construcción

Primero hacer un clone y seguir los pasos que describo al principio (Cómo utilizar la plantilla).

git clone --recursive https://github.com/LuisPalacios/CppPlantilla.git
make prepare

• Crear el ejecutable

cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release --target main
cd app
./main

• Unit testing

cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug --target unit_tests
cd tests
./unit_tests

• Documentación

La documentación que genera doxygen en el directorio html puede subirse a GitHub Pages. Consultar la siguiente sección.

cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug --target docs

• Code Coverage

cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON ..
cmake --build . --config Debug --target coverage

Si quieres saber más sobre CMake consulta este artículo.

 

Preparar GitHub Pages

Si has creado un repositorio nuevo partiendo de esta plantilla no necesitas crear la rama `gh-pages+ de nuevo, dejo aquí documentado todo el proceso solo como referencia.

GitHub permite, a través de su servicio GitHub Pages hospedar tus propias páginas web en cada uno de tus repositorios. Podemos usarlo para subir la documentación de nuestro repositorio.

El proceso está documentado en pages.github.com y en su documentación oficial.

Para este respositorio sigue esta chuleta:

• Crea la rama gh-pages

Crea una nueva branch, sin histórico ni contenido, llamada gh-pages

git checkout --orphan gh-pages
git rm -rf .

mkdir docs
cd docs
touch .keep.txt
git add .
git commit -m 'Creación inicial de la rama gh-pages'
git push --set-upstream origin gh-pages

• Entra en GitHub desde el navegador y activa GitHub Pages.

  • Haz clic en la pestaña Configuración / Settings.
  • Haz clic en Pages en la parte izquierda.
  • Source: Deploy from a branch
  • Branch: gh-pages Directorio: /(root)) Clic en SAVE

• Verifica que tienes el fichero ~/.github/workflows/documentation.yaml preparado con las acciones a realizar.

• Verifica que tienes permisos.

  • Haz clic en la pestaña Configuración / Settings.
  • Haz clic en Actions->General en la parte izquierda.
  • Workflow Permissions: Read and write

• Haz un push al repositorio.

touch algo.txt
git push

• Ve a tu repositorio -> Actions (debería estar construyendo la documentación)