Skip to content

Project Configuration

Project configuration

To create a new project using PhoenixGenerator, you will have to write a project.toml file describing some attributes of your project.

[project]
name = "StereoData"
url = "https://gitlab.in2p3.fr/CTA-LAPP/RTA/Stereo/StereoData"
version = "0.1.0"
description = "A very important project"
main_branch = "main"
runner_tag = "MUST_big_runner"
ci_toolkit_url = "https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/citoolkit/phoenixcitoolkitcpp/phoenix-workflow-cpp"
ci_toolkit_version = "3.0.4"
authors = [
    { firstName = "Oprinsen", lastName = "Thibaut", affiliation = "LAPP, Univ. Savoie Mont-Blanc, CNRS", mail = "thibaut.oprinsen@lapp.in2p3.fr" },
    { firstName = "Aubert", lastName = "Pierre", affiliation = "LAPP, Univ. Savoie Mont-Blanc, CNRS", mail = "pierre.aubert@lapp.in2p3.fr" }
]
maintainers = [
    { firstName = "Aubert", lastName = "Pierre", affiliation = "LAPP, Univ. Savoie Mont-Blanc, CNRS", mail = "pierre.aubert@lapp.in2p3.fr" }
]
contributors = [
    { firstName = "Pollet", lastName = "Vincent", affiliation = "LAPP, Univ. Savoie Mont-Blanc, CNRS", mail = "vincent.pollet@lapp.in2p3.fr" }
]
keywords = ["stereo", "data", "analysis", "CTA", "RTA"]
dependencies = ["PhoenixToml >=1.0.0, <2.0.0",
                "PhoenixYml ==1.0.0",
                "PhoenixCore",
                "curl >=8.0.0, <9.0.0"]

Warning

The fields provided in the example configuration are required. If you forget one of those, the generation process will fail.

Config file attributes

As described in the example, the project.toml requires multiple attributes to generate your project :

name : The name of the project you want to generate. You can use all UTF-8 characters inside it.
url : The Gitlab url where your project is hosted on.
version : The initial version of the project you want to use. By convention, the first release of your software should be 1.0.0.
description : A small description of your porject. It will be added in the doxygen documentation.
main_branch : Name of the main branch of your project (basically refers to 'master' or 'main').
runner_tag : Gitlab runner you want to use for your CI/CD pipelines.
ci_toolkit_url : URL of the toolkit you want to use for the CI pipelines. Our team provides a fully operationnal workflow for your C++ projects. If you want to use it, you can use the phoenix-workflow-cpp component from phoenixcitoolkitcpp
ci_toolkit_version : The version of the toolkit to be used. PLease refer to the release section of PhoenixCiToolkit to use the latest version of the toolkit.
authors : Should be a list of dictionnary containing the information of all the authors of the project. Every dictionnary in the list should contain :

  • firstName : The first name of the author.
  • lastName : The last name of the author.
  • affiliation : The affiliation or group the author is related to.
  • mail : A contact address.

maintainers and contributors sections should also contain lists of dictionnaries containing information of every maintainer and contributor of the package.
keywords : A comma separated list of keywords related to the project.
dependencies : A comma separated list of the requried dependencies of the project. Dependencies can be Phoenix dependenceis, but also third-party packages. If you don't need any dependency, you can keep this field empty.
Every dependency in the list can be defined using some paramaters and for each dependency, you can specify :

  • Dependency name
  • minimum required version of the package with the format >=version,
  • maximum version to be used with the format <version
  • specific version to be used with the format ==version

Warning

If you don't specify the version of the dependency, the system will automatically add the latest found on prefix.dev.

Examples : To add curl as a dependency, you can :

  • Select a version to be used : "curl ==8.17.0"
  • Select a version between 8 and 9 : curl >=8.0.0, <9.0.0
  • Let the system add the latest version : curl

Adding an unknown dependency

When generating the project, the generator checks a list of known dependencies. If a dependency is not recognized, you will be prompted to complete a template file with all the information required to integrate your dependency into the project. Feel free to open a pull request on the PhoenixGenerator project to add your dependency to the list of known dependencies. This way, it will be integrated into the generator for future reuse.

The file you will be prompted to fill is the following : 

# To fill the package info use the description below, then remove the commented lines.
[[Package]]
# This is the name of your package (eg on your git repository)
name = ""
# This is the name of your package for the pixi.toml. You can find the name of the pixi package by searching it on https://prefix.dev
pixi_name = ""
# If your package provides a CMake configuration file (find File), this should be the value used in find_package().
cmake_find = ""
# If your package provides a CMake configuration library, this should be the name of the main library target provided by the package.
cmake_lib = ""
#This is the URL of your package repository if you want to use the pull_extra_module feature of PhoenixCMake (only for Phoenix packages)
url = ""

Once you have filled in this file, make sure it is included in the installation path of PhoenixGenerator. Then, regenerate the project. This time, the process should complete successfully!

Project types

For now, PhoenixGenerator handles the creation of only one type of project : the SimpleCpp which is described in the Project architecture section

Project architecture

Projects generated with PhoenixGenerator have the following structure :

🏛️ SimpleCpp 

📁 doc
|─── 📁 doxygen          
|────── 📄 CMakeLists.txt   ──► target for generating the software documentation
|────── 📄 mainpage.dox     ──► Content of mainpage for doxygen documentation
|─── 📁 mkdocs
|────── 📄 mkdocs.yml       ──► configuration file for user documentation generation
|────── 📁 doc_src
|───────── 📄 index.md      ──► Content of mainpage of user doc (contains the README.md of current project)
|───────── 📄 license.md    ──► Copy of license file of the current project
|───────── 📄 softdep.md    ──► Phoenix projects this project is linked to
|───────── 📄 usage.md      ──► Phoenix projects this project is linked to
|─── 📁 images
|────── 📄 logo.png         ──► Placeholder logo you can replace with your own one
|────── 📄 logo.svg         ──► Placeholder logo you can replace with your own one
|────── 📄 icon.bmp         ──► Placeholder logo you can replace with your own one
📁 pdata
|─── 📄 generate_class.sh   ──► Script to regenerate the sources from your .pdata files
|─── 📄 yourClass.pdata     ──► The pdata file(s) you added in input when generating the project
📁 src  
|─── 📄 CMakeLists.txt      ──► Define src targets
|─── 📄 projectName.h       ──► your project header     
|─── 📄 projectName.cpp     ──► your porject implementation
|─── 📄 yourClass.h         ──► Gnerated class(es) header from your pdata file(s)
|─── 📄 yourClass.cpp       ──► Gnerated class(es) implementation from your pdata file(s)
📁 TESTS    
|─── 📄 CMakeLists.txt      ──► Define test targets
|─── 📁 TEST_yourClass
|────── 📄 CMakeLists.txt   ──► Add the tests from your generated class  
|────── 📄 main.cpp         ──► Test of your class (including Datastream, TYpeStream tests if option is passed)
📄 .gitattributes           ──► set the pixi.lock file as a abinary attribute for git
📄 .gitignore               ──► ignore folders
📄 .gitlab-ci.yml           ──► CI/CD using the C++ workflow of phoenix
📄 CMakeLists.txt           ──► CMakeLists of this project
📄 codemeta.json            ──► Metadata file containing information about the projects (can be used with zenodo)
📄 install.sh               ──► Installation script (if you want to install the project locally without pixi)
📄 LICENSE                  ──► CeCILL-C license
📄 pixi.toml                ──► Contains the information about pixi's environment, tasks and dependencies
📄 README.md                ──► This README
📄 renovate.json            ──► Configuration for renovate bot
📄 update.sh                ──► update script you can run to update your local installation