Skip to content

README.md

Latest commit

 

History

History
160 lines (111 loc) · 4.64 KB

README.md

File metadata and controls

160 lines (111 loc) · 4.64 KB

Feel++ Template Project

DOI GitHub Release CI

A template repository to kickstart your finite-element applications with Feel++.

Table of Contents

Features

  • C++ example apps using Feel++ and its toolboxes (located in src/).
  • Python Jupyter notebooks under docs/notebooks/ for interactive demos.
  • Documentation authored in AsciiDoc and published with Antora (docs/).
  • Docker setup for reproducible development and deployment.
  • CI via GitHub Actions: C++ tests, Python wheel builds, docs site.

Quick Start

Installation via APT (Recommended)

The easiest way to get started is to install the pre-built feelpp-project package from the Feel++ APT repository:

# Add Feel++ APT repository
curl -fsSL https://feelpp.github.io/apt/feelpp.gpg | sudo gpg --dearmor -o /usr/share/keyrings/feelpp.gpg
echo "deb [signed-by=/usr/share/keyrings/feelpp.gpg] https://feelpp.github.io/apt/stable noble feelpp-project" | sudo tee /etc/apt/sources.list.d/feelpp.list

# Install feelpp-project
sudo apt update
sudo apt install feelpp-project

For development/testing versions, replace stable with testing:

echo "deb [signed-by=/usr/share/keyrings/feelpp.gpg] https://feelpp.github.io/apt/testing noble feelpp-project" | sudo tee /etc/apt/sources.list.d/feelpp.list

Building from Source

If you prefer to build from source:

Prerequisites

  • CMake ≥ 3.21
  • A C++ compiler (GCC or Clang) with MPI support
  • Python 3.8+ and pip
  • Docker (optional, for container builds)

Clone & Rename

If you used this as a template, rename the project metadata:

./rename.sh your-project-name

📌 NOTE
After renaming, verify URLs in docs/site.yml and docs/package.json.

Docker Usage

You can also run feelpp-project using Docker, which automatically uses the published APT packages:

# Run latest stable version
docker run --rm -it ghcr.io/feelpp/feelpp-project:master

# Run specific version  
docker run --rm -it ghcr.io/feelpp/feelpp-project:v4.0.0

Building from Source

CMake Presets

Create CMakePresets.json in your project root or update the one provided:

cmake --preset default
cmake --build --preset default
cmake --build --preset default --target install

build/default will contain the build artifacts and the build directory.

Creating Debian Packages

To build .deb packages locally:

cmake --build --preset default --target package

The generated .deb files will be in build/default/assets/.

Continuous Integration & Distribution

Our GitHub Actions workflow (.github/workflows/ci.yml) includes:

  • build_wheel: Python wheel compilation and artifact upload.
  • build_docs: Builds the Antora site, deploys to GitHub Pages on master.
  • build_code: CMake build, tests with ctest --preset default, Debian packaging.
  • APT Publishing: Automatic publication of .deb packages to Feel++ APT repository:
    • master branch → testing channel
    • Tagged releases → stable channel
    • Pull requests → pr channel
  • docker: Docker image build & push to GHCR using published APT packages.
  • release: On tags vX.Y.Z, publishes binaries, wheels, and creates a GitHub release.

APT Repository Structure

The Feel++ APT repository provides packages for different channels:

  • Stable: https://feelpp.github.io/apt/stable/dists/noble/feelpp-project/
  • Testing: https://feelpp.github.io/apt/testing/dists/noble/feelpp-project/
  • PR: https://feelpp.github.io/apt/pr/dists/noble/feelpp-project/

Versioning & Release

Project version is centrally defined in:

  • CMakeLists.txt
  • docs/antora.yml
  • docs/package.json

Release Process

** Commit with:**

$ git commit -am "Release vX.Y.Z" + . Tag and push: + $ git tag vX.Y.Z && git push --tags + . GitHub Actions will build and publish artifacts automatically.

Contributing

We welcome contributions! Please:

  • Fork the repository and create a feature branch.
  • Adhere to existing coding conventions; add C++ tests where appropriate.
  • Update documentation (docs/) for any new features.
  • Submit a pull request with a clear description of your changes.

License

This project is licensed under the BSD 3-Clause License. See LICENSE for full details.