When we use naked primitive types (int, double, and similar), the meaning of values is not explicit. Code becomes more fragile: it is easy to swap two parameters and, in some cases, impossible to express the intended meaning correctly.

To understand the problem, let's start from a very common case.

struct rectangle{    rectangle(double const width, double const height);    ...};

In this example nothing prevents you from accidentally swapping width and height: rectangle(800, 600) and rectangle(600, 800) are both valid for the compiler, but one of them may be semantically wrong. The problem appears only at runtime.

Let's try to make the intent clearer with different parameter names.

struct circle{public:    explicit circle(double const radius) : m_radius{radius} {}    explicit circle(double const diameter) : m_radius{diameter/2} {} // This doesn't compile! :(    ...}

Here the two constructors have the same signature (circle(double)): only the parameter names change, and they do not participate in overloading. As a result, the code does not compile, and in any case we don't have distinct types to express Radius and Diameter.

Primitive types do not capture domain semantics. We need a way to give values an identity and make the call site self-explanatory, reducing errors and unexpected behavior.

For this we introduce strong, self-explanatory types: Width, Height, Radius, Diameter, and so on. In the sections that follow we will look at a C++23 header-only library, st::strong_type<T, Tag, Ability...>, where Tag separates semantic axes and the Ability mixins enable only the desired operators in opt-in mode. This way the compiler helps us express intent and prevent entire classes of bugs.

What is a strong type?

A strong type is a type wrapper that replaces an underlying type to make the semantics explicit at the type level (not just in the parameter name). With st::strong_type<T, Tag, Ability...> we "brand" a T with a Tag (phantom type) that makes it incompatible with other values that are isomorphic but semantically different, and we enable only the operations declared in opt-in mode through the Ability mixins.

The strong type in code:

namespace st {template<class T, class Tag, template<class> class... Ability>struct strong_type;} // namespace st

• T: underlying type (e.g. double, int, std::uint32_t, an enum...).
• Tag: empty type that identifies the semantic axis (e.g. width_tag, height_tag).
• Ability: feature mixins (opt-in operators and utilities). The ready-to-use group st::arithmetic is also available.

How does it work?

• Tag barrier. Binary operators between strong types are allowed only if they share the same Tag. Adding Width and Height? Compilation error.
• Ability gating. Each operator/utility is protected by a requires: both operands must declare the required ability, and the underlying type must actually support the operation (checked at the expression level).
• Correct constructors. From T: the constructor is explicit by default; it becomes implicit only when the conversion to T is safe (no narrowing). From another strong type with the same Tag: allowed if the underlying types are convertible; the same explicit rules apply.
• Disciplined result type. Binary operators return a new strong type with: underlying = std::common_type_t<UA, UB>; abilities = the union of the abilities of the two operands, filtered based on the new underlying (e.g. shift only on unsigned); same Tag.
• Safe shifts. Counts are normalized modulo the bit-width (with assert on negatives in debug), avoiding UB.
• Saturating arithmetic. st::sat_add and st::sat_sub clamp to min and max (dedicated signed/unsigned paths) and return a type consistent with the union/filtering rules above.
• Access and utilities. x.value() (lvalue/rvalue overloads), st::to_underlying(x) (preserves the value category), st::clamp, explicit operator bool() bool-testable style, st::static_strong_cast(x) (intentional cast between strong types with the same Tag).
• STL integration. Consistent specializations of std::hash, std::formatter and std::common_type aligned with the previous rules.

An example

This intentionally complete example shows the usefulness of a header file dedicated to strong types.

#include <cstdint>#include <expected>#include <format>#include <iostream>#include <limits>#include <numeric>#include <print>#include <ranges>#include <sstream>#include <string_view>#include <unordered_map>#include <vector>#include "strong.h"// tagsstruct distance_tag{};struct time_tag{};struct flag_bits_tag{};struct counter_tag{};// strong aliasesusing meters    = st::strong_type<int, distance_tag, st::arithmetic, st::equality_comparable, st::three_way_comparable, st::ostream_insertable>;using meters64 = st::    strong_type<long long, distance_tag, st::arithmetic, st::equality_comparable, st::three_way_comparable, st::ostream_insertable>;using meters_d = st::    strong_type<double, distance_tag, st::arithmetic, st::equality_comparable, st::three_way_comparable, st::ostream_insertable>;using seconds = st::    strong_type<int, time_tag, st::equality_comparable, st::three_way_comparable, st::ostream_insertable, st::istream_extractable>;using flags = st::strong_type<std::uint8_t,                              flag_bits_tag,                              st::bitwise_and,                              st::bitwise_and_assign,                              st::bitwise_or,                              st::bitwise_or_assign,                              st::bitwise_xor,                              st::bitwise_xor_assign,                              st::bitwise_not,                              st::shift_left,                              st::shift_left_assign,                              st::shift_right,                              st::shift_right_assign,                              st::ostream_insertable>;using flag_mask = st::strong_type<std::uint8_t,                                  flag_bits_tag,                                  st::bitwise_and,                                  st::bitwise_or,                                  st::bitwise_xor,                                  st::bitwise_not,                                  st::shift_left,                                  st::shift_right,                                  st::ostream_insertable,                                  st::bitops_extras>;using meters_u    = st::strong_type<unsigned, distance_tag, st::arithmetic, st::saturating, st::equality_comparable, st::ostream_insertable>;using meters_s_sat    = st::strong_type<int, distance_tag, st::arithmetic, st::saturating, st::equality_comparable, st::ostream_insertable>;using counter = st::strong_type<int, counter_tag, st::arithmetic, st::bool_testable, st::ostream_insertable>;// helpers[[nodiscard]] auto average_distance(const std::vector<meters> &path) -> std::expected<meters_d, std::string_view>{    if (path.empty())        return std::unexpected{"empty path"};    const auto total = std::accumulate(        path.begin(), path.end(), meters{0}, [](const meters &a, const meters &b) -> meters { return a + b; });    return st::static_strong_cast<meters_d>(total) / static_cast<double>(path.size());}[[nodiscard]] auto pairwise_sum(const std::vector<meters> &a, const std::vector<meters> &b)    -> std::expected<std::vector<meters>, std::string_view>{    if (a.size() != b.size())        return std::unexpected{"size mismatch"};    std::vector<meters> out;    out.reserve(a.size());    for (auto &&[x, y] : std::views::zip(a, b))        out.push_back(x + y);    return out;}auto main() -> int{    static_assert(std::same_as<decltype(meters{1} + meters{2}), meters>);    static_assert(std::same_as<std::common_type_t<meters, meters64>::underlying_type, long long>);    // extra compile-time sanity checks    static_assert(std::is_trivially_copyable_v<meters>);    static_assert(sizeof(flags) == sizeof(std::uint8_t));    // construction & conversions    meters a = 12;    meters b{short{30}};    meters c = meters64{42};   // strong -> strong (same tag)    meters_d d{meters64{100}}; // strong -> strong (same tag) to double    std::println("a={}, b={}, c={}, d={}", a, b, c, d);    // arithmetic + comparisons    const auto sum{a + b};    const auto diff{b - a};    const auto ord{a <=> b};    std::println("sum={}, diff={}, cmp={}", sum, diff, (ord < 0 ? "a<b" : (ord > 0 ? "a>b" : "a==b")));    // compound ops / modulo / ++ --    auto mwork = meters{5};    ++mwork;    mwork++;    mwork -= meters{1};    mwork += meters{3};    mwork %= meters{4};    std::println("mwork after ops = {}", mwork);    // scalar rebind (multiply/divide)    const auto scaled = a * 2.5;    const auto halved = scaled / 2.0;    std::println("scaled={}, halved={}", scaled, halved);    // clamp, unary -, cast, to_underlying    const auto lo{meters{5}}, hi{meters{25}};    std::println("clamp({}, {}, {}) = {}", a, lo, hi, st::clamp(a, lo, hi));    std::println("unary_minus(-{}) = {}", lo, -lo);    std::println("static_strong_cast<double> = {}", st::static_strong_cast<meters_d>(a));    std::println("sum as raw int: {}", st::to_underlying(sum));    // streams & parsing    std::istringstream iss{"77"};    seconds t{0};    iss >> t;    std::println("parsed seconds = {}", t);    // unordered_map / hash    std::unordered_map<meters, std::string_view> names;    names.emplace(a, "start");    names.emplace(b, "end");    std::println("names[a] = {}", names.at(a));    // bitwise flags    auto f = flags{std::uint8_t{0b0101}};    const auto g = flags{std::uint8_t{0b0011}};    f |= g;    f &= flags{std::uint8_t{0b0110}};    f ^= flags{std::uint8_t{0b0010}};    f <<= 42; // 42 % 8 = 2    f >>= 2;    std::println("flags final = {}", f);    // bit-ops extras    const auto mk = flag_mask{std::uint8_t{0b1101}};    std::println("mask={}, popcount={}, bit_width={}", mk, st::popcount(mk), st::bit_width(mk));    std::println("rotl({}, 3)={}, rotr({}, 2)={}", mk, st::rotl(mk, 3), mk, st::rotr(mk, 2));    std::println("countl_zero={}, countl_one={}, countr_zero={}, countr_one={}",                 st::countl_zero(mk),                 st::countl_one(mk),                 st::countr_zero(mk),                 st::countr_one(mk));    // saturating arithmetic (unsigned + signed)    const auto umax_less = meters_u{std::numeric_limits<unsigned>::max() - 5u};    const auto uplus = meters_u{100u};    const auto usat = st::sat_add(umax_less, uplus);    std::println("sat_add({}, {}) = {}", umax_less, uplus, usat);    const auto smin = meters_s_sat{std::numeric_limits<int>::min() + 10};    const auto sneg = meters_s_sat{-1000};    const auto ssat = st::sat_sub(smin, sneg);    std::println("sat_sub({}, {}) = {}", smin, sneg, ssat);    // ranges / expected    const std::vector<meters> path{meters{3}, meters{4}, meters{5}, meters{6}};    if (auto avg = average_distance(path))    {        std::println("average(path) = {}", *avg);    }    else    {        std::println("average(path) error: {}", avg.error());    }    const std::vector<meters> p2{meters{7}, meters{8}, meters{9}, meters{10}};    if (auto summed = pairwise_sum(path, p2))    {        std::println("pairwise_sum size={}, last={}", summed->size(), summed->back());    }    else    {        std::println("pairwise_sum error: {}", summed.error());    }    // bool_testable    counter cnt{2};    if (cnt)    {        std::println("counter {} is truthy", cnt);    }    --cnt;    --cnt;    if (!static_cast<bool>(cnt))    {        std::println("counter {} is falsy", cnt);    }    return 0;}// Application output/*parsed seconds = 77names[a] = startflags final = 4mask=13, popcount=3, bit_width=4rotl(13, 3)=104, rotr(13, 2)=67countl_zero=4, countl_one=0, countr_zero=0, countr_one=1sat_add(4294967290, 100) = 4294967295sat_sub(-2147483638, -1000) = -2147482638average(path) = 4.5pairwise_sum size=4, last=16counter 2 is truthycounter 0 is falsy*/

Conclusion

Strong types make APIs more explicit, catch errors earlier, and control which operations are available for each value. Concrete aliases such as using Width = st::strong_type<double, width_tag, st::arithmetic>; make both call sites and tests clearer, because the compiler can distinguish values that share the same representation but have different meanings.

This post shows how std::ranges and std::views, introduced in C++20, make algorithm composition on collections clearer.

Computational model

Problem

We want to write an algorithm that takes a collection of integers as input and returns only the ones divisible by 3, in reverse order.

The following table shows a few examples of input and output.

Pre-C++20 solution

#include <algorithm>#include <vector>#include <iostream>auto main() -> int {    const std::vector<int> numbers{3, 0, 10, 9, 12, 7, 30, 14, 6};    auto isDivisibleByThree = [](int const i) { return i % 3 == 0; };    std::vector<int> tmp{};    std::copy_if(numbers.begin(), numbers.end(), std::back_inserter(tmp), isDivisibleByThree);    std::reverse(tmp.begin(), tmp.end());    for (auto const& i : tmp)        std::cout << i << " ";    return 0;}

This small snippet of code performs these steps:

• Creates a temporary helper std::vector.
• Copies into tmp all the elements of numbers that satisfy the isDivisibleByThree predicate.
• Reverses the order of the elements in tmp.

The solution works, but it requires a temporary container and several separate steps. With C++20 we can describe the same transformation more directly.

Solution with std::ranges

#include <algorithm>#include <vector>#include <iostream>#include <ranges>auto main() -> int {    const std::vector<int> numbers{3, 0, 10, 9, 12, 7, 30, 14, 6};    auto isDivisibleByThree = [](int const i) { return i % 3 == 0; };    auto result{std::views::reverse(std::views::filter(numbers, isDivisibleByThree))};    for (auto const& i : result)        std::cout << i << " ";    return 0;}

The difference is clear; before going into specifics, however, it's worth clarifying the concepts of range and view.

Ranges

A range represents a sequence of elements, or more generally something that can be iterated.

By definition, a range is a pair of iterators begin and end: the first points to the start of a collection or sequence, the second to its end.

Standard-library containers satisfy this definition and can therefore be used as ranges.

Classification

Ranges can be classified in different ways. One of the most important distinctions is based on iterator capabilities.

Having covered concepts in the previous post, we can summarize ranges in the following table.

This classification corresponds to the related iterator concepts, such as std::forward_iterator.

Views

Three ideas about views are especially important:

• A view is a range.
• A view does not own the data it accesses.
• A view applies changes only when an element is requested (lazy evaluation).

A view is a range

By definition, a view \(w\) is a range defined on another range \(r\). The view can apply transformations to the observed range through algorithms and other operations, taking advantage of lazy evaluation.

A view does not own the data it accesses

When you access an element through a view, you still work with the data managed by the underlying range.

This has two implications:

• Views are fast to create, because they don't need to copy the underlying data.
• Structural transformations performed by the view do not modify the original container.

#include<iostream>#include<vector>#include<ranges>auto main() -> int {    std::vector numbers{1, 2, 3, 4, 5};    auto v{std::views::reverse(numbers)};    for (auto const& i : numbers)        std::cout << i << " ";    return 0;}// Output: 1 2 3 4 5

As you can see, the view did not modify the numbers range. However, the opposite is true: if you modify the original container, the change is reflected on every view that uses that range.

So we would get

#include<iostream>#include<vector>#include<ranges>auto main() -> int {    std::vector numbers{1, 2, 3, 4, 5};    auto v{std::views::reverse(numbers)};    for (auto const& i : v)        std::cout << i << " ";    std::cout << std::endl;    numbers[2] = 100;    numbers[4] = 77;    for (auto const& i : v)        std::cout << i << " ";    return 0;}// Output: 5 4 3 2 1//         77 4 100 2 1

Lazy evaluation

A view applies transformations when elements are requested, not necessarily when the view is created. This deferred evaluation avoids unnecessary work and copies.

#include<iostream>#include<vector>#include<ranges>auto main() -> int {    std::vector numbers{1, 2, 3, 4, 5};    auto v{std::views::reverse(numbers)};    std::cout << *v.begin() << std::endl; // the view is evaluated here    return 0;}// Output: 5

Composition and pipelines

You may wonder why I wrote

auto v{std::views::reverse(numbers)};

instead of

std::views::reverse v{numbers};

The reason is that std::views::reverse is not itself a view, but an adapter: it takes the underlying range, in this case a std::vector, and returns a view over it. The exact type of the view is hidden behind the auto keyword; this way we don't have to worry about writing the view's template arguments. Another advantage of this form is the ability to chain multiple adapters via pipes.

For example, instead of using

auto v{std::views::reverse(std::views::filter(numbers, isDivisibleByThree))};

We can write

auto v{numbers | std::views::filter(isDivisibleByThree) | std::views::reverse};

Examples

We want to create a view of the first 5 elements of a std::vector and print the result.

#include<iostream>#include<vector>#include<ranges>auto main() -> int {    std::vector numbers{1, 2, 3, 4, 5, 6, 7, 8, 9, 10};    auto v{numbers | std::views::take(5)};    for (auto const& i : v)        std::cout << i << " ";}// Output: 1 2 3 4 5

We want to use a range-based algorithm to print an std::vector in reverse order, excluding negative values.

#include <algorithm>#include <iostream>#include <ranges>#include <vector>auto main() -> int {    std::vector numbers{-1, 3, -100, -4, 0, 3, -7, 1};    auto predicate = [](int const i) -> bool {        return i >= 0;    };    auto printer = [](int const i) {        std::cout << i << " ";    };    std::ranges::for_each(numbers | std::views::reverse | std::views::filter(predicate), printer);}// Output: 1 3 0 3

Advanced concepts

Range factories

The standard library also provides adapters that can generate a view without starting from an existing range.

One example is std::views::iota, which creates an incremental view of integers.

#include <iostream>#include <ranges>auto main() -> int {    for (int const i : std::views::iota(1, 7)) {        std::cout << i << " ";    }}// Output: 1 2 3 4 5 6

Zip views

std::views::zip, introduced in C++23, lets you combine multiple ranges into a single view. Each produced element is a tuple containing the corresponding values from the source ranges.

Here is a small example.

#include <iostream>#include <ranges>#include <vector>auto main() -> int {    std::vector numbers{1, 2, 3, 4};    std::vector english{"cat", "dog", "table", "sun"};    std::vector italian{"gatto", "cane", "tavolo", "sole"};    for (const auto& i : std::views::zip(numbers, english, italian)) {        std::cout << std::get<0>(i) << ". "                  << std::get<1>(i) << ": "                  << std::get<2>(i) << '\n';    }    return 0;}

Conclusion

Ranges and views let you describe a transformation pipeline without introducing unnecessary temporary containers. For a complete overview of the available adapters and algorithms, see the ranges library documentation.

This post introduces concepts, one of the most useful C++20 features for generic code. We will cover the essential terminology and see how concepts make template requirements explicit.

For a complete reference, cppreference has detailed documentation on constraints and concepts.

Motivation

The first question is simple: what are concepts useful for?

When we write code we almost always want the algorithms and data structures we implement to be generic, that is, usable with different data types. We want a single generic solution, without having to reimplement it for specific data types. This has several advantages:

• Better maintainability.
• Reusing the same code with different types.
• Allowing API users to provide custom types.

Common examples are standard-library algorithms and containers such as std::swap and std::vector.

In C++, this abstraction is expressed with templates. A template can be instantiated with different types, but sometimes the type cannot be arbitrary: the implementation may require specific operations or properties.

Suppose we have an algorithm that, given two values of the same type, wants to perform a binary addition and return the result.

#include <iostream>#include <format>template <typename T>auto add(T const& a, T const& b) -> T {    return a + b;}auto main() -> int {    std::cout << std::format("{}\n", add(1, 2));    // std::cout << std::format("{}\n", add("foo", "bar")); -> compilation error    return 0;}

The generic template parameter T is unconstrained: from the compiler's point of view it can be instantiated with any type. However, if you ask for this function to be instantiated with certain data types, the compiler will produce an error.

This happens because the function template implicitly requires the types passed as parameters to provide the binary addition operator. If a type does not provide that operator, the compiler cannot generate the function.

But where does the compiler fail?

Not at the template declaration, but during instantiation, when the implementation tries to use an operation that is not available.

This produces error messages that are hard to decipher and causes plenty of frustration. In medium-to-large codebases, with nested data structures, the situation worsens exponentially.

To work around this issue we need to introduce constraints, so that we can explicitly define the requirements of the template parameters.

Terminology

Template

A template is a construct that generates an ordinary type or function at compile time based on the arguments the user supplies for the template parameters. A template's arguments can be constrained.

Requirements

Requirements are expressed with the requires keyword, which describes the conditions that a type or expression must satisfy. For details, see the cppreference documentation on requires.

Constraint

A constraint is a set of requirements on a template's arguments.

These are used to:

• Correctly select function overloads.
• Decide the most appropriate specialization for a template.

Concepts

A concept is a predicate that wraps a set of constraints. Each concept is evaluated at compile time and becomes part of the interface of a template when it is used as a constraint.

In addition:

• A data type that satisfies all the requirements (and therefore the constraints) of a concept is said to model that concept.
• A concept made up of another concept plus additional constraints is said to refine that concept (or those concepts).

Syntax

Depending on the complexity of a constraint declaration, you can use three different syntaxes to enforce constraints. All the definitions below are equivalent, and you can combine them. Note that std::integral is a predefined concept.

Full, explicit declaration

Very useful when you have multiple constraints to enforce.

template <typename T, typename Q>    requires std::integral<T> and std::integral<Q>auto add(T const t, Q const q) {    return t + q;}

Intermediate declaration

template <std::integral T, std::integral Q>auto add(T const t, Q const q) {    return t + q;}

Compact declaration

auto add(std::integral auto const t, std::integral auto const q) {    return t + q;}

Solution

To solve the problem, we declare the Addable concept and apply it to the parameters of add. In this case we use the compact form.

#include <iostream>#include <concepts>template <typename T> concept Addable = requires(T a, T b) { a + b; // requirement 1};auto add(Addable auto const t, Addable auto const q) {    return t + q;}auto main() -> int {    std::cout << add(5, 6) << std::endl;    //std::cout << add("foo", "bar") << std::endl;  -> compilation error    return 0;}

The template rejects any type that does not satisfy the requirement at compile time. Compared with the unconstrained version, the compiler can produce an error closer to the function interface and therefore easier to interpret.

Conclusion

Concepts and constraints make template requirements explicit and help produce more understandable compilation errors. For more detail, cppreference offers a complete guide to constraints and concepts.

After leaving Arch Linux behind, I moved to openSUSE Tumbleweed, which eventually became my main operating system. I used it for software development, gaming, office work, and everyday use.

What I appreciate most is the balance between frequent updates and reliability. Tumbleweed is a rolling-release distribution, but its testing process removes many of the problems usually associated with that model.

After trying several distributions over the years, Tumbleweed stands out for its KDE Plasma integration, administration tools, and update quality. This article collects what worked well for me and the trade-offs I ran into.

What works well

Stable and bleeding-edge

openSUSE Tumbleweed is a rolling-release distribution that gives users the latest features and developments from the Linux world: kernel, drivers, desktop environments and up-to-date applications.

That is useful for advanced users, software developers, and gamers who need recent packages.

Because Tumbleweed is updated continuously, you do not need large version upgrades every six months as with some other GNU/Linux distributions.

This distribution does not rely on rigid periodic release cycles; it is based on Factory, openSUSE's development base, which is updated frequently.

Each update, which follows a strict industrial standard and a rigorous quality-assurance process, is published only after passing thorough tests and quality checks through the openQA platform.

In practice, every new package version is tested individually and together with other groups of versions, ensuring overall system consistency.

In addition, openSUSE uses a modern filesystem like Btrfs, which lets users take snapshots of the system state and roll back to a previous state when something goes wrong.

All of this makes Tumbleweed suitable for everyday use despite being a rolling release. Once installed and configured, it can be used continuously as long as it is kept updated.

YaST and Snapper

Tumbleweed includes YaST, a very complete control panel. YaST, short for Yet another Setup Tool, can manage users, printers, software sources, the boot loader, partitions, services, networking, virtualization, AppArmor, filesystem snapshots, and more.

Tumbleweed also ships Snapper, created by Arvin Schnell, to manage snapshots of Btrfs filesystem subvolumes and LVM thin-provisioned volumes. Beyond creating and deleting snapshots, including scheduled and automatic ones, Snapper can compare snapshots and restore the differences between them. In practice, it lets users view earlier versions of files and recover changes in a controlled way.

Together, YaST and Snapper make system administration easier and simplify recovery after a problematic update.

Intuitive setup

Let's start with the installation. Tumbleweed's installer is, in my opinion, the most complete and straightforward one I have ever encountered. It gives you full control over what will be installed and provides a default configuration that is more than sufficient for most users. I personally prefer and always recommend enabling full-disk encryption and Logical Volume Management to manage physical resources more effectively.

Once the installation is finished, if you need third-party codecs, you just install opi, a front-end for openSUSE's Open Build Service. To pull in all codecs at once, just use opi codecs, which enables new repositories and installs them.

If you need drivers for your NVIDIA graphics card, you can install them directly from YaST or via the simple zypper install-new-recommends --repo NVIDIA command.

The downsides

One of Tumbleweed's main drawbacks is that it may not be compatible with some third-party kernel modules or proprietary drivers, especially for graphics cards. That's because the Linux kernel is updated very frequently in Tumbleweed and some external modules or drivers may not keep up with the changes, or may not be available at all. The workaround is to compile such modules or drivers from source, or to avoid using them entirely.

Also, installing third-party software not in the repositories, even through YaST Software, triggers an integrity-check error. The error can be safely ignored and the software will still install correctly.

A sore point: the ongoing conflict between PackageKit and YaST Software. Just remove the PackageKit package and the problem disappears.

openSUSE is still a niche distribution, so third-party documentation is less abundant. The official documentation is excellent, although it can feel more concise than the documentation available for distributions like Fedora or Ubuntu.

I'll end with an annoyance rather than a serious problem. If you enable third-party repositories, especially Packman, you may run into package-version conflicts that block updates. Usually, waiting a few days before updating or using Flatpak versions of the affected applications is enough.

Conclusion

In my experience, openSUSE Tumbleweed offers recent packages without sacrificing system reliability. openQA, Btrfs, Snapper, and YaST form a solid base for a rolling-release distribution.

The main compromises are external kernel modules and possible conflicts between repositories. To reduce those issues, I prefer limiting third-party repositories and using Flatpak for applications that need proprietary codecs. With those precautions, Tumbleweed has been a strong distribution for both work and everyday use.

F-Droid is often recommended by security and privacy enthusiasts, and I imagine that many people use it to download, install and update their favorite apps on their phones. I used F-Droid for a long time too, but after reading PrivSec's article on its security issues, I decided to look for an alternative.

At first I used RSS feeds to follow the updates of the applications I was interested in. I would download the app directly from the developer's GitHub or GitLab page, subscribe to the RSS feed and wait for the update notifications. When a new release came out I would go back to the dedicated page, download the APK and manually install the update. Soon, however, I realized it was a clunky, slow and tiresome process.

I needed something that could do the same job automatically after the initial setup. The solution I chose was Obtainium.

What is Obtainium?

Obtainium automates the download and installation of Android app updates directly from source websites, meaning sites where the APK files are available for direct download.

How to get Obtainium

To install Obtainium, start from its official GitHub page.

Under "Installation", select "Get it on GitHub", expand the assets, and pick the APK variant for your device. For a Google Pixel, for example, the variant is usually app-arm64-v8a. The download will start, then proceed with the install as usual. Once the install is finished, you can open the app. I recommend allowing notifications: they are handled locally and do not require Google Play services.

The interface

When I first opened Obtainium I was pleasantly surprised by the design.

The project changes often, so names and screen layout may differ over time, but the overall flow should remain similar.

The app has a bottom navigation with these entries:

• Apps, the full list of apps added to Obtainium.
• Add App, to register a new app to track.
• Import/Export, to import or export the app list and Obtainium configuration.
• Settings, to configure the application.

Adding an app

To add a new application, tap "Add App". At the bottom there is a button to see the supported sources. Some, like GitHub and Codeberg, are flagged as searchable: in those cases you can search directly from Obtainium. There are two text fields: in the first you can paste the source URL of the app you want to add; the second lets you search for it by a text string.

In this case, let's search for NewPipe since the project is on GitHub. The search may return many results, especially for a popular project; in my case, the first one was the official NewPipe repository. For safety, I always suggest verifying that the project is the right one; even better, look up the page in your browser and paste the URL manually.

Once the source is validated, you can select it by tapping "Select".

A separate section appears with additional options. The most important ones are:

• Include prereleases: enable this only if you want preview versions that may be unstable.
• Fallback to older releases: useful when GitHub releases are not organized cleanly. For example, if iOS and Android builds are published as separate releases and the iOS one is newer, Obtainium may otherwise find no Android APK to install.
• Filter Release Titles by Regular Expression: to filter release titles by a regular expression. It's an edge case, but it can happen that the URL points to multiple downloadable applications.
• Track Only: track only, with no automatic updates. I leave this option off, since I want Obtainium to download the APKs for me so they can be installed automatically.

Now you can tap "Add". The APK is downloaded to your device; once the download is complete, Obtainium shows the details of the newly added app. Tapping "Install" asks Android to allow app installation from Obtainium as an unknown source. Enable it and install the app.

After the installation is finished, going back to the app list you can see that NewPipe is now monitored, with the latest version correctly installed.

It sounds like a long process, but once you know the basic steps it takes only a few seconds.

What if Obtainium were compromised by malware?

As always, you should be skeptical about everything you download from the web, open source or not. An extra precaution is to install the first version manually from the official source and add it to Obtainium only afterwards. Android accepts updates only when the signature matches the app already installed, so an APK signed with a different key would be rejected.

Limitations

There are some limitations to keep in mind. The first is that app installs happen asynchronously and you cannot directly determine the success or failure of an installation. This means that install state and versions are not synced with the operating system until the next launch or until the issue is fixed manually. In short, you have to restart the application.

The second is that for some sources, data is gathered through web scraping, which can easily break due to changes in the website design. Anyone who has used NewPipe will have noticed that, on every change in YouTube's interface, NewPipe's extractor is at risk of breaking and may no longer be able to extract fundamental data. Something similar can happen with Obtainium: it's a consequence of the fragile nature of web scraping.

Conclusion

Obtainium lets you follow updates directly from official sources and reduces the manual work needed to download new releases. It still requires care when choosing repositories and does not remove the risks of APK distribution, but it is a good compromise for managing open-source apps outside traditional stores.

After moving to GrapheneOS, I decided to replace many of my apps with more privacy-respecting alternatives. I also realized how dependent I was on applications from the major platforms.

These were the apps I used most on my old Samsung S10:

• WhatsApp.
• Google suite: Mail, Calendar and Drive.
• Google Workspace suite.
• YouTube.
• Google Maps.
• Google Play Store.

These were only some of the main applications I used. In practice, a large part of my digital life went through Google, Microsoft, and Meta.

I started looking for open-source and privacy-oriented alternatives, accepting a few compromises compared with the services I used before.

Replacing WhatsApp

This was the hardest step, not because of the app choice but because of the migration. Today almost everyone uses WhatsApp, and for many people it has become the default channel. I had to warn my contacts that I was moving away from it and would soon no longer be reachable there. There were plenty of questions. In the end I moved to Signal Messenger, and very few people followed me. That was not a big problem: anyone who needed to reach me could still call instead of sending text messages or endless voice notes.

Why Signal and not alternatives like Session, Briar, Element, or SimpleX Chat?

In short:

Contact lists on Signal are encrypted with the Signal PIN and the server has no access to them. Personal profiles are also encrypted and only shared with the contacts you chat with. Signal supports private groups, where the server has no record of group membership, group titles, group avatars or group attributes. Signal has minimal metadata when Sealed Sender is enabled. The sender address is encrypted alongside the message body and only the recipient address is visible to the server. Sealed Sender is enabled only for people in your contact list, but it can be enabled for all recipients, at the cost of a higher risk of receiving spam.

In addition, the protocol has been independently reviewed and its specifications are public.

As a bonus, Signal's interface is very close to WhatsApp's.

Replacing the Google suite: Mail, Calendar and Drive

These are some of the providers I evaluated, grouped by category.

Email services:

• Proton Mail
• Tutanota
• Mailbox.org

Cloud storage services:

• Proton Drive
• Tresorit
• Peergos

Calendar services:

• Proton Calendar
• Tuta (Tutanota's calendar)

The options were two: split the services across different providers or use a single company.

I chose Proton because it brings mail, calendar, and cloud storage into one service, with polished applications and a privacy-focused model.

To recap, I replaced Gmail, Google Calendar, and Google Drive with Proton Mail, Proton Calendar, and Proton Drive.

Replacing the Google Workspace suite

Unfortunately, for this one I did not find a solid alternative. The choice I made was to pair an excellent app, Collabora Office, for editing documents, with a good sync service, Syncthing.

That's because Collabora Online (Office) is not a standalone piece of software. On the contrary, the online office suite plugs into an existing infrastructure and requires a cloud solution as its base (NextCloud, Dropbox, etc.).

Replacing YouTube

I mostly use YouTube for learning, but also for entertainment. In this case I still use Google's platform, but through a third-party client instead of the official app.

Fortunately, I did not need to do much research: I had already been using NewPipe for several years.

NewPipe is an intuitive, feature-rich and privacy-respecting app that lets you watch videos on YouTube. The app offers many parts of the YouTube experience without invasive ads and without the permissions requested by the official app. It is also open source and its code is available on GitHub.

Replacing Google Maps

Here the only solution is to switch to a client based on OpenStreetMap.

The alternatives are:

• OsmAnd
• Organic Maps
• Magic Earth

The first two are excellent both for browsing maps and for the features they offer; however, they fall short in real-time navigation. During navigation, they often suggest very inconvenient secondary roads or pick routes that needlessly lengthen the trip. The third one excels where the others struggle, but its source code is not available.

I mostly use Organic Maps for its clean interface and for hiking. When I need to drive somewhere unfamiliar, I prefer Magic Earth.

Replacing the Google Play Store

As with YouTube, one solution is to use an alternative client for the Play Store catalog. The app I use for this is Aurora Store. Aurora Store is a free alternative to the Google Play Store. With this app you can download applications, update the existing ones, get details on in-app trackers, hide your location, search for applications and much more. Aurora's developers have also done good work on the design and interface.

Conclusion

Replacing mainstream smartphone apps requires compromises: sometimes you lose convenience, sometimes you gain control. For me the switch made sense because it reduced my dependency on major platforms without making the phone uncomfortable to use.

In June 2023, my old Samsung Galaxy S10 died after a bad fall down the stairs.

I had already been thinking about replacing it, and I wanted a device that gave me more control, with a system designed around security and privacy.

I compared several operating systems based on the Android Open Source Project, each with different privacy and security goals.

I eventually narrowed the choice down to three alternatives: CalyxOS, LineageOS, and GrapheneOS.

After evaluating them, I chose GrapheneOS and bought an officially supported device.

Let's look at what GrapheneOS is, how it is installed, and which features convinced me.

What is GrapheneOS?

GrapheneOS is an operating system based on the Android Open Source Project, with many additional security and privacy features. It is open source, officially supports all the most recent Google Pixel devices, and can be installed with great ease to replace the operating system on a Google Pixel.

By default it includes neither Google applications nor Google services: it essentially breaks the control Google has over the mobile device.

The result is a spartan device, in the positive sense: only stock applications from the AOSP project, everything to be configured by you, with no constraints imposed by third parties.

How do you install GrapheneOS?

The project provides a minimal web interface that lets you install the operating system by following clear instructions.

To get started, open the official installation guide and choose between the WebUSB-based installation and the classic terminal-based one.

After that, just follow the step-by-step guide.

Some GrapheneOS features

What follows is a non-exhaustive overview of GrapheneOS features. For details, see the official features page.

Protection against zero-day vulnerabilities, plus extra user and network features.

GrapheneOS protects its users from zero-day vulnerabilities. To achieve this, GrapheneOS reduces the attack surface by removing unnecessary code from the operating system.

For app management, GrapheneOS includes dedicated toggles for network and sensor permissions, which are rare on AOSP-based custom ROMs.

At the network level, the operating system supports MAC randomization for every connection and an LTE-only mode to reduce the network attack surface by disabling legacy code (2G, 3G) and bleeding-edge code (5G). Wi-Fi and Bluetooth (as well as the mobile hotspot) support automatic shutdown if they are not connected to a device, saving battery life and preventing potential wireless attacks from outside.

A notable feature is the private screenshot function that disables the inclusion of sensitive metadata.

Sandboxing and memory-corruption protection.

To significantly reduce operating system vulnerabilities, the team behind GrapheneOS dedicates significant resources to the development of memory-safe languages and libraries, static and dynamic analysis tools and much more.

GrapheneOS applies sandboxing at multiple levels, hardening both the kernel and the operating system components. In short, every element of the operating system is isolated in its own compartment, allowing app permissions and processes to remain separate and protecting them from malware and other potential security threats.

The applications

GrapheneOS provides a set of hardened applications designed to reduce permissions and attack surface.

First, there is the WebViewer and the Vanadium browser. Vanadium is a hardened Chromium-based browser with additional security and privacy measures.

Secure Camera, built by the GrapheneOS team, is the system's default camera. It includes the usual camera features and adds privacy and security options, such as QR scanning without network or media-access permissions and optional EXIF metadata removal from photos and videos.

Auditor provides hardware-based attestation for the device's software and firmware. It is a specialized feature, especially useful for people exposed to targeted risks.

Last but not least is Secure PDF Viewer, another application built by the GrapheneOS team. It is a PDF reader that requires no permissions and runs in a sandbox.

Improved profile management

GrapheneOS has improved the user-profile functionality and is improving monitoring across profiles.

In detail, it gives you the ability to:

• Add multiple profiles.
• End the session.
• Disable app installs in specific profiles.
• Install available apps from one profile into another.
• Forward notifications from inactive profiles to the current session.

Google in a sandbox

Google apps can be installed on GrapheneOS through a dedicated compatibility layer. The apps are stripped of the special access or privileges they would normally have. You can use Google's applications and services, but they will be reshaped to meet high privacy and security standards.

Conclusion

I have been using GrapheneOS for about a year, and the experience has been positive. Privacy-focused products often require significant usability compromises; in this case, the impact on everyday use stayed limited.

I did not have to radically change how I use my phone. The most annoying part was replacing many applications tied to the Google ecosystem, which deserves its own post.

The main limitation concerns apps that depend on Google Play services. Without installing the dedicated compatibility layer, some features, such as Firebase-based push notifications, may not be available.

Overall, I ended up with a phone that is more controllable, more privacy-oriented, and still comfortable for daily use.

A kill switch prevents traffic from leaving through the regular connection when the WireGuard tunnel is not active, avoiding accidental exposure of the real IP address.

After moving from iptables to nftables, I had to translate the rules in my wg-quick peer configuration. Since I could not find useful information at the time, I decided to share the solution I used.

Configuration

This configuration assumes that nftables rules are reloaded through the init system.

In the wg-quick configuration file, add these two lines:

PostUp = nft insert rule <family> <table> <chain> ip oifname != "%i" mark != $(wg show %i fwmark) fib daddr type != local counter rejectPostDown = systemctl restart <service>

These lines need to be adapted to your system and firewall.

PostUp

In a terminal, run nft list ruleset and look for the type filter hook output directive.

Now adjust the PostUp line with the information you found. In my case this directive lives in the firewalld table, family inet, chain filter_OUTPUT.

PostDown

In the PostDown line, put the command that reloads the firewall. In this example I use systemd.

Example

PostUp = nft insert rule ip inet firewalld filter_OUTPUT oifname != "%i" mark != $(wg show %i fwmark) fib daddr type != local counter rejectPostDown = systemctl restart firewalld.service

nftables is the Netfilter framework introduced in the Linux kernel as the successor to iptables. It provides a more consistent and flexible interface, replacing separate tools such as iptables, ip6tables, arptables, and ebtables.

With iptables, IPv4 and IPv6 rules often had to be maintained separately through iptables and ip6tables.

Aside from a new syntax and a few updates, nftables works similarly to its predecessor.

Chains and rules

The most common iptables tables use predefined chains such as INPUT, OUTPUT, and FORWARD. Each chain contains rules evaluated in order; if none matches, the default policy, such as ACCEPT or DROP, is applied.

iptables can become inefficient because packets traverse the expected chains even when some of them are not actually needed, adding unnecessary checks.

nftables keeps the same conceptual model of tables, chains, and rules, but it does not force predefined chains. You create only the chains you need and attach them to the appropriate kernel hooks.

Syntax difference

iptables syntax can become hard to read as rules grow. nftables uses a more uniform grammar and can express many cases with less duplication.

To create a new rule you use a form similar to this:

nft add rule family_type table_name chain_name handle handle_value statement

Let's compare a few equivalent examples.

Blocking a connection

This command blocks an inbound connection from IP 192.168.7.5.

# iptablesiptables -A INPUT -s 192.168.7.5 -j DROP# nftablesnft add rule ip filter INPUT ip saddr 192.168.7.5 counter drop

Allowing incoming SSH connections

This command allows incoming SSH connections.

# iptablesiptables -A INPUT -p tcp --dport 22 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT# nftablesnft add rule ip filter INPUT tcp dport 22 ct state new,established counter accept

This command allows incoming SSH connections from the whole 192.168.155.0/24 network.

# iptablesiptables -A INPUT -p tcp -s 192.168.155.0/24 --dport 22 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT# nftablesnft add rule ip filter INPUT ip saddr 192.168.155.0/24 tcp dport 22 ct state new,established counter accept

Allowing MySQL traffic on the eth0 network interface

This command allows connections on the eth0 network interface toward the MySQL server.

# iptablesiptables -A INPUT -i eth0 -p tcp --dport 3306 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT# nftablesnft add rule ip filter INPUT iifname eth0 tcp dport 3306 ct state new,established counter accept

Allowing HTTP and HTTPS traffic

This command allows traffic on ports 80 and 443.

# iptablesiptables -A INPUT -p tcp -m multiport --dports 80,443 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT# nftablesnft add rule ip filter INPUT ip protocol tcp tcp dport { 80, 443 } ct state new,established counter accept

Conclusion

nftables offers a more uniform model for managing IPv4, IPv6, and other protocols, with clearer syntax and more flexible configuration. For more details on creating tables and chains, the Arch Linux nftables documentation is a good starting point.

While developing the "Enne 2D Engine" project, I asked myself more than once: why do I keep writing header guards when I could just use the #pragma once directive?

So I decided to dig into the question and share my analysis.

Why do declaration files need to be protected?

The ODR principle

The One Definition Rule is a fundamental rule in C++.

In simplified form, it states that a function, variable, or type must respect precise constraints on how many definitions may appear in a program.

Violating the ODR can cause "multiple definitions" errors during compilation or linking problems when the linker cannot decide which definition to use.

In the example below, with three files, compilation fails because struct foo is defined more than once.

File alpha.hpp

struct foo {};

File bravo.hpp

#include "alpha.hpp"

File charlie.hpp

#include "alpha.hpp"#include "bravo.hpp"

The preprocessor, once the relevant substitutions are done, produces the following result.

struct foo {};struct foo {};

So how do you make sure the ODR is respected?

The first solution that comes to mind, although very spartan, is to manage the #include hierarchy manually. In the example above, you would have to avoid including alpha.hpp in charlie.hpp. This is fragile and does not scale to medium or large projects.

There are two common solutions:

• Header guards.
• The #pragma once directive.

Header guards

The solution that is part of the C++ standard is the use of header guards. These guards prevent a header file from being included more than once in a single translation unit. To achieve this, they use preprocessor macros to check whether the header has already been included before. If it has already been included, those clauses prevent it from being included again.

The #define directive creates a macro, that is, the association of an identifier (or an identifier with parameters) with a string of tokens. Once the macro is defined, the compiler can substitute the token string for every occurrence of the identifier in the source file.

Going back to the previous example, with a few small changes we get:

File alpha.hpp

#ifndef ALPHA_HPP#define ALPHA_HPPstruct foo {};#endif // ALPHA_HPP

File bravo.hpp

#ifndef BRAVO_HPP#define BRAVO_HPP#include "alpha.hpp"#endif // BRAVO_HPP

File charlie.hpp

#ifndef CHARLIE_HPP#define CHARLIE_HPP#include "alpha.hpp"#include "bravo.hpp"#endif // CHARLIE_HPP

After the relevant substitutions, the preprocessor produces the following result.

struct foo {};

When working on large projects, it is important to define clear guidelines for macro names: using only the file name can easily lead to clashes. Other problems appear when a header is copied and the macro is not updated, or when the final #endif is missing. Tools such as clang-tidy can help catch some of these mistakes.

I, for example, follow this scheme to define a macro name: <PROJECT_ROOT>_<RELATIVE_PATH_TO_HPP_FILE>_<FILE_NAME>_HPP_.

This avoids generating the same identifier for two files with the same name.

Assume the following structure, with CPP_PROJECT as the root directory, and two files with the same name in different directories.

.├── libfoo│   ├── CMakeLists.txt│   ├── docs│   │   └── CMakeLists.txt│   ├── include│   │   └── libfoo│   │       ├── detail│   │       │   └── alpha.hpp│   │       └── common│   │           └── alpha.hpp

The macro name on the alpha.hpp file inside the detail directory will be:

#define CPP_PROJECT_LIBFOO_INCLUDE_LIBFOO_DETAIL_ALPHA_HPP_

The macro name on the alpha.hpp file inside the common directory will be:

#define CPP_PROJECT_LIBFOO_INCLUDE_LIBFOO_COMMON_ALPHA_HPP_

Pragma once

The alternative to header guards, widely used but not part of the C++ standard, is the #pragma once directive.

File alpha.hpp

#pragma oncestruct foo {};

File bravo.hpp

#pragma once#include "alpha.hpp"

File charlie.hpp

#pragma once#include "alpha.hpp"#include "bravo.hpp"

After the relevant substitutions, the preprocessor produces the following result.

struct foo {};

You write less code and avoid macro-name clashes, but this solution has trade-offs.

#pragma once is not part of the C++ standard, so compilers are not required by ISO C++ to support it.

But why isn't it part of the standard?

The answer lies in the complexity of detecting file equality consistently. One known issue involves reaching the same file through different paths or symbolic links. In some cases, a compiler may fail to recognize that two paths refer to the same header and include it more than once. See https://en.m.wikipedia.org/wiki/Pragma_once#Caveats.

There is also no guarantee that support for #pragma once is the same across different compilers, which can be a problem for some developers.

Header guards or pragma once?

It depends on the case.

The choice depends on portability requirements and project conventions.

Header guards are standard and work everywhere, at the cost of a few extra lines and a reliable macro convention. #pragma once is shorter and widely supported by common compilers, but it is not part of the standard.

Conclusion

For projects where portability is a priority, I prefer header guards. In codebases with a well-defined toolchain, #pragma once remains a pragmatic and widely supported choice.

Suppose you are working on a project with Git. By mistake or distraction, you may create a commit that should not exist. In that situation you need to undo it in the right way, choosing between two very different approaches.

The main commands are:

• The revert command
• The reset command

The revert command

The revert command creates a new commit that reverses the changes from the commit we want to undo.

The basic form is:

git revert <commit to revert>

The usual steps are:

1. Run the git log command.
2. Find the commit you want to revert.
3. Copy the alphanumeric hash of the commit to revert.
4. Run git revert <commit to revert>.

Example.

cd project_with_a_dot_git_foldergit log### Example of the git log output## commit 2596f783998c8ec230b38a044b49e39d07770901 (HEAD -> main, origin/main)# Author: Foo <foo@bar.com># Date:   Tue Apr 9 14:47:17 2024 +0200##     Add something bad## commit 2ce5e2e7e36f23673b32ccef7f908f161527142b# Author: Foo <foo@bar.com># Date:   Tue Apr 2 23:33:27 2024 +0200##     Update somethinggit revert 2ce5e2e7e36f23673b32ccef7f908f161527142b

After running the command, a new commit will be generated that reverses the earlier changes, without rewriting commit history.

The reset command

The alternative is the reset command. git reset rewrites local history, so it should be used carefully, especially if the commits have already been shared. It moves HEAD to the selected commit; what happens to files and the index depends on the option used.

Soft reset

The --soft option moves HEAD while keeping the removed commit's changes staged in the index.

git reset --soft HEAD~1

Hard reset

The --hard option aligns both the index and working tree with the selected commit, discarding local uncommitted changes too.

git reset --hard HEAD~1

Conclusion

git revert is the safer choice for history that has already been shared, because it adds a new commit instead of rewriting existing ones. git reset is mainly useful for cleaning up local history before it is published.

After the backdoor in the XZ Utils package was disclosed (CVE-2024-3094), I noticed many people suggesting xz --version to check the installed package version instead of asking the distribution's package manager.

If an executable may be compromised, it is better not to run it just to learn its version. The package manager can provide the same information without executing the binary.

So let's look at how to check the version of an installed package on GNU/Linux systems. For convenience I split the distributions by package manager.

Note that the commands below explicitly filter for packages with xz in the name.

Debian

This works on every Debian-based distribution.

# aptapt list xz# or with more detailsapt show xz# or with dpkgdpkg-query -l '*xz*'# ordpkg-query -l | grep xz

Fedora

This applies to Fedora and to distributions that use RPM and DNF. You can also use RPM Package Manager (RPM).

# dnfdnf list installed xz*# ordnf list installed | grep xz# or with yumyum list installed | grep xz# or via RPMrpm -qa | grep xz

Arch Linux

This also works for Arch-based distributions, including Manjaro, EndeavourOS and SteamOS.

# pacmanpacman -Qs xz# orpacman -Q | grep xz

openSUSE Tumbleweed

These commands are also valid for SUSE- and openSUSE-based distributions like GeckoLinux and Linux Kamarada. You can also use RPM.

# zypperzypper info xz# orrpm -qa | grep xz

After working with Qt, I started wondering how a signal/slot mechanism could be implemented in modern C++.

Wikipedia defines it this way.

[...] a language construct [...] which makes it easy to implement the Observer pattern while avoiding boilerplate code. The concept is that GUI widgets can send signals containing event information which can be received by other controls using special functions known as slots.

-- Wikipedia

In simpler words, the signal/slot mechanism enables event-based communication between objects. Several libraries implement this pattern very well; here I present a small personal implementation built mainly to understand the mechanism better.

UML diagram

The following UML diagram summarizes the project structure.

The code

Because the implementation uses templates, the code lives entirely in a header file. The comments describe the responsibilities and behavior of the main components.

#ifndef LIBSIGSLOTPP_INCLUDE_LIBSIGSLOTPP_SIGNAL_HPP_#define LIBSIGSLOTPP_INCLUDE_LIBSIGSLOTPP_SIGNAL_HPP_#include <functional>#include <memory>namespace sigslotpp {typedef std::size_t IDType;/** * @brief Interface ISlotConnection * It provides a simple interface that identifies the Slot and its main * connectivity operations. * ISignal can access private and protected regions for design purposes. */class ISlotConnection { private:  friend class ISignal;  IDType id_;         ///< identifier and index into the signal slots vector.  bool isConnected_;  ///< slot connection status.  bool isBlocked_;    ///< slot connection block status. protected:  /**   * @brief Getter for the identifier   * @return id_   */  IDType id() const noexcept { return id_; }  /**   * @brief Getter/Setter for the identifier   * @return a reference to id_   */  IDType &id() noexcept { return id_; }  /**   * @brief Clears the slot connection   * Where the real disconnection happens.   * This gets called by the ISlotConnection::disconnect() function, the   * implementation depends on the child subclasses.   */  virtual void clear() noexcept = 0; public:  ISlotConnection() = delete;  // not needed but better for compilation error  /**   * @brief Primary constructor   * @post id_ == id   * @post isConnected__ == isConnected   * @post isBlocked_ == isBlocked   */  explicit ISlotConnection(const IDType id, const bool isConnected = true,                           const bool isBlocked = false) noexcept      : id_(id), isConnected_(isConnected), isBlocked_(isBlocked) {}  /**   * @brief Destructor   */  virtual ~ISlotConnection() {} public:  /**   * @brief Checks the connection status   * Used to see if a slot is still connected to a Signal   */  virtual bool isConnected() const noexcept { return isConnected_; }  /**   * @brief Checks if the connection is blocked   * Used to temporarily disable slot invocation.   * @return true if the slot invocation is blocked else false.   */  bool isBlocked() const noexcept { return isBlocked_; } public:  /**   * @brief Blocks the slot invocation   * @post isBlocked_ == true   */  void block() noexcept { isBlocked_ = true; }  /**   * @brief Unblocks the slot invocation   * @post isBlocked_ == false   */  void unblock() noexcept { isBlocked_ = false; }  /**   * @brief Disconnects the slot from the signal   * @post isConnected_ == false   */  void disconnect() {    if (isConnected_) {      isConnected_ = false;      clear();    }  }};/** * @brief Class Connection * This class allows interaction with an ongoing signal-slot connection and * exposes an interface to manipulate and query the status of this connection. * Note that Connection is not a RAII object, one does not need to hold one * such object to keep the signal-slot connection alive. */class Connection { private:  std::weak_ptr<ISlotConnection> slot_;  ///< the slot to manipulate and query public:  Connection() = delete;  // not needed but better for compilation error  /**   * @brief Primary constructor   * @param slot that will be handled by this connection   */  explicit Connection(std::weak_ptr<ISlotConnection> &&slot) : slot_(slot) {}  /**   * @brief Destructor   */  virtual ~Connection() {} public:  /**   * @brief Checks if this connection is still valid   * To have this information just see if the std::weak_ptr is expired   * @return true if the connection is valid else false   */  bool isValid() const noexcept { return !slot_.expired(); }  /**   * @brief Checks if the slot is still connected to its signal   * @return true if the slot is still connected else false   * @see ISlotConnection::isConnected()   */  bool isConnected() const noexcept {    std::shared_ptr<ISlotConnection> d = slot_.lock();    return d && d->isConnected();  }  /**   * @brief Checks if the slot connection is blocked   * @return true if the slot connection is blocked else false   * @see ISlotConnection::isBLocked()   */  bool isBlocked() const noexcept {    std::shared_ptr<ISlotConnection> d = slot_.lock();    return d && d->isBlocked();  }  /**   * @brief Blocks the slot invocation   * @see ISlotConnection::block()   */  void block() noexcept {    std::shared_ptr<ISlotConnection> d = slot_.lock();    if (d) d->block();  }  /**   * @brief Unblocks the slot invocation   * @see ISlotConnection::unblock()   */  void unblock() noexcept {    std::shared_ptr<ISlotConnection> d = slot_.lock();    if (d) d->unblock();  }  /**   * @brief Disconnects the slot from its signal   * @see ISlotConnection::disconnect()   */  void disconnect() {    std::shared_ptr<ISlotConnection> d = slot_.lock();    if (d) d->disconnect();  }};////////////////////////////////** * @brief Interface ISignal * It provides a simple interface that identifies the Signal and its essential * functions. */class ISignal { protected:  /**   * @brief Getter for specified ISlotConnection identifier   * @return id of the specified slot   */  IDType idOf(ISlotConnection *const slotPtr) const noexcept {    return slotPtr->id();  }  /**   * @brief Getter/Setter for specified ISlotConnection identifier   * @return a reference to id of the specified slot   */  IDType &idOf(ISlotConnection *const slotPtr) noexcept {    return slotPtr->id();  } public:  /**   * @brief Destructor   */  virtual ~ISignal() {}  /**   * @brief Disconnect the slot from this signal   * @param slot a pointer to the slot to disconnect from   */  virtual void disconnect(ISlotConnection *const slot) = 0;};/** * @brief Interface ISlot * It provides a simple interface that identifies the Slot and its core * invocation functionality. * @tparam Args... the argument types of the function to call */template <typename... Args>class ISlot : public ISlotConnection { private:  ISignal &signal_;  ///< reference to the signal protected:  /**   * @brief Clears the slot connection   */  virtual void clear() noexcept override { signal_.disconnect(this); }  /**   * @brief Invokes the function   * Where the function is really invoked.   * This gets called by the ISlot::operator()() function, the   * implementation depends on the child subclasses.   * @param args the arguments of the function to call   */  virtual void invoke(Args... args) = 0; public:  ISlot() = delete;  // not needed but better for compilation error  /**   * @brief Primary constructor   * We have a reference that must be initialized, so no default constructor   * allowed here.   * @param id the slot identifier   * @param signal the reference of the signal connected to this slot   * @post signal_ points to the signal connected to this slot   * @see ISlotConnection   */  ISlot(const IDType id, ISignal &signal) noexcept      : ISlotConnection(id), signal_(signal) {}  /**   * @brief Invokes the function   * Invokes or calls the function stored in the slot.   * Take note that i add an extra template here for flexibility and design   * purposes. As mentioned in Signal::emit() we use the signature here.   * At the end it is used std::forward to forward lvalues as either lvalues   * or as rvalues, depending on Params.   * @see Signal::emit()   * @param params the parameters of the function to call   * @tparam ...Params types of the parameters of the function to call   */  template <typename... Params>  void operator()(Params &&...params) {    if (ISlotConnection::isConnected() && !ISlotConnection::isBlocked())      invoke(std::forward<Params>(params)...);  }};/** * @brief Class SimpleSlot * Basic slot that does not track anything and thus it is imperative that what * is called by the std::function must exceeds the lifetime of signal this * slot is connected to. * @tparam Args... the argument types of the function to call */template <typename... Args>class SimpleSlot final : public ISlot<Args...> { private:  std::function<void(Args...)>      function_;  ///< function to be invoked by this slot protected:  /**   * @copydoc ISlot::invoke()   */  void invoke(Args... args) override final {    function_(std::forward<Args>(args)...);  } public:  SimpleSlot() = delete;  // not needed but better for compilation error  /**   * @brief Primary constructor   * @param id the slot identifier   * @param function to be invoked by this slot   * @param signal the reference to the signal this slot is connected to   * @see ISlot   */  SimpleSlot(const IDType id, std::function<void(Args...)> &&function,             ISignal &signal) noexcept      : ISlot<Args...>(id, signal),        function_(std::forward<std::function<void(Args...)>>(function)) {}};/** * @brief Class TrackingSlot * Tracking slot that tracks an object with a std::weak_ptr, it is auto * disconnected upon expiration of the std::weak_ptr thus no need to take care * of complex object lifetime managment. * @tparam T the type of the object to track * @tparam Args... the argument types of the function to call */template <typename T, typename... Args>class TrackingSlot final : public ISlot<Args...> { private:  std::function<void(Args...)>      function_;  ///< function to be invoked by this slot  std::weak_ptr<T>      objectPtr_;  ///< the pointer to the object this slot is tracking protected:  /**   * @copydoc ISlot::invoke()   */  void invoke(Args... args) override final {    // this is probably useless in signle thread    auto sp = objectPtr_.lock();    if (!sp) {      ISlotConnection::disconnect();      return;    }    if (ISlotConnection::isConnected()) {      function_(args...);    }  } public:  TrackingSlot() = delete;  // not needed but better for compilation error  /**   * @brief Primary constructor   * @param id the slot identifier   * @param objectPtr the pointer to the object to track   * @param function to be invoked by this slot   * @param signal the reference to the signal this slot is connected to   * @see ISlot   */  TrackingSlot(const IDType id, std::weak_ptr<T> &&objectPtr,               std::function<void(Args...)> &&function,               ISignal &signal) noexcept      : ISlot<Args...>(id, signal),        function_(std::forward<std::function<void(Args...)>>(function)),        objectPtr_(std::forward<std::weak_ptr<T>>(objectPtr)) {} public:  /**   * @brief Checks if the connection still there   */  bool isConnected() const noexcept override final {    return !objectPtr_.expired() && ISlotConnection::isConnected();  }};/** * @brief Class Signal * This class manages a collection of ISlots * @tparam R the return type of the function to call * @tparam Args... the argument types of the function to call */template <typename R, typename... Args>class Signal final : public ISignal { private:  std::vector<std::shared_ptr<ISlot<Args...>>>      slots_;  ///< slots connected to this Signal  /**   * @brief Disconnects the specified slot   * @param slot the pointer to the slot to disconnect from   * @post slots_.size() decremented by one   */  void disconnect(ISlotConnection *const slot) noexcept override final {    IDType index = idOf(slot);    if (!slots_.empty()) {      std::swap(slots_[index], slots_.back());      idOf(slots_[index].get()) = index;      slots_.pop_back();    }  } public:  /**   * @brief Default constructor   * @post slots_.size() == 0   */  Signal() noexcept : slots_() {}  /**   * @brief Destructor   */  virtual ~Signal() noexcept { disconnectAll(); }  /**   * @brief Move constructor   * @see Signal::operator=()   */  Signal(Signal &&other) noexcept : slots_() { *this = std::move(other); }  /**   * @brief Move assignment operator   * @return a reference to this   * @post slots_ == other.slots_   */  Signal &operator=(Signal &&other) noexcept {    if (this != &other) {      slots_ = std::move(other.slots_);    }    return *this;  }  /**   * @brief Connects a slot to the signal   * Connects a std::function to the signal.   * @param function the signal connects to   * @return a Connection instance for managment purposes   * @post slots_.size() incremented by one   */  Connection connect(std::function<R(Args...)> &&function) noexcept {    IDType id = slots_.size();    std::shared_ptr<ISlot<Args...>> slot =        std::make_shared<SimpleSlot<Args...>>(            id, std::forward<std::function<R(Args...)>>(function), *this);    slots_.push_back(slot);    return Connection(std::weak_ptr(slots_[id]));  }  /**   * @brief Connects and tracks a slot to the signal   * Connects a std::function to the signal but this time the slot is tracked   * by a std::weak_ptr pointing to the object of type T. The purpose is to   * disconnect this slot automatically upon said object destruction.   * @param function the signal connects to   * @param objectPtr pointer to the object to be tracked   * @tparam T the type of the object to track   * @return a Connection instance for managment purposes   * @post slots_.size() incremented by one   */  template <typename T>  Connection connect(std::weak_ptr<T> &&objectPtr,                     std::function<R(Args...)> &&function) noexcept {    IDType id = slots_.size();    std::shared_ptr<ISlot<Args...>> slot =        std::make_shared<TrackingSlot<T, Args...>>(            id, std::forward<std::weak_ptr<T>>(objectPtr),            std::forward<std::function<R(Args...)>>(function), *this);    slots_.push_back(slot);    return Connection(std::weak_ptr(slots_[id]));  }  /**   * @brief Connects and tracks a slot to the signal   * Convenience method to connect a member function.   * Connects a function pointer to the signal.   * The slot is tracked by a std::weak_ptr pointing to the object of type T.   * The purpose is to disconnect this slot automatically upon said object   * destruction.   * @param function pointer the signal connects to   * @param objectPtr pointer to the object to be tracked   * @tparam T the type of the object to track   * @return a Connection instance for managment purposes   * @post slots_.size() incremented by one   */  template <typename T>  Connection connect(std::shared_ptr<T> &objectPtr,                     R (T::*function)(Args...)) noexcept {    T *const ptr = objectPtr.get();    return connect(std::weak_ptr<T>(objectPtr),                   [ptr, function](Args... args) -> R {                     return (ptr->*function)(args...);                   });  }  /**   * @brief Connects and tracks a slot to the signal   * Convenience method to connect a const member function.   * Connects a function pointer to the signal.   * The slot is tracked by a std::weak_ptr pointing to the object of type T.   * The purpose is to disconnect this slot automatically upon said object   * destruction.   * @param function pointer the signal connects to   * @param objectPtr pointer to the object to be tracked   * @tparam T the type of the object to track   * @return a Connection instance for managment purposes   * @post slots_.size() incremented by one   */  template <typename T>  Connection connect(std::shared_ptr<T> &objectPtr,                     R (T::*function)(Args...) const) noexcept {    T *const ptr = objectPtr.get();    return connect(std::weak_ptr<T>(objectPtr),                   [ptr, function](Args... args) -> R {                     return (ptr->*function)(args...);                   });  }  /**   * @brief Disconnects all the slots   * Disconnects all the slots this signal is connected to.   * @post slots_.empty() == true   */  void disconnectAll() noexcept { slots_.clear(); }  /**   * @brief Emits the signal   * All non blocked and connected slot functions will be called   * with supplied arguments.   * Important explanation!   * A template is used here, this is for flexibility and design purposes.   * To this function can be passed rvalues or lvalues but if we use the Args   * type it is basically precluding us to emit the signal when it is a   * different types from Args. Suppose Signal<bool, int, double&> the matched   * function is std::function<bool(int, double&)>. Now i can't emit something   * like emit(5, 5.0) because 5.0 is a non const lvalue.   * @see ISlot::operator()()   * @param params arguments to emit   * @tparam ...Params type of the parameter to emit   */  template <typename... Params>  void emit(Params... params) {    for (auto const &it : slots_) {      it->operator()(params...);    }  }  /**   * @brief Gets the number of connected slots   * @return slots.size()   */  std::size_t connectedSlots() const noexcept { return slots_.size(); }};}  // namespace sigslotpp#endif  // LIBSIGSLOTPP_INCLUDE_LIBSIGSLOTPP_SIGNAL_HPP_

Usage

To understand how to use the implemented solution, I'll show you the unit tests I wrote.

const std::string ff = "free function";const std::string mf = "member function";const std::string smf = "static member function";const std::string mo = "member operator";const std::string l = "lambda";const std::string gl = "generic lambda";void f() { fmt::print("{}\n", ff); }struct s {  void m() { fmt::print("{}\n", mf); }  static void sm() { fmt::print("{}\n", smf); }};struct o {  void operator()() { fmt::print("{}\n, mo"); }};TEST_CASE("slots can be added and removed from the signal") {  std::shared_ptr<s> d;  auto lambda = []() { fmt::print("{}\n", l); };  auto gen_lambda = [](auto &&...a) { fmt::print("{}\n", gl); };  sigslotpp::Signal<void> sig;  SUBCASE("connecting slots to signal increases connected slots") {    auto c1 = sig.connect(f);    sig.connect(d, &s::m);    sig.connect(&s::sm);    auto c2 = sig.connect(o());    sig.connect(lambda);    sig.connect(gen_lambda);    CHECK(sig.connectedSlots() == 6);  }  SUBCASE("discconnecting all slots from the signal put size to zero") {    auto c1 = sig.connect(f);    auto c2 = sig.connect(o());    sig.connect(lambda);    sig.connect(gen_lambda);    sig.disconnectAll();    CHECK(sig.connectedSlots() == 0);  }  SUBCASE("disconnecting slots from signal decreases connected slots") {    auto c1 = sig.connect(f);    auto c2 = sig.connect(o());    c1.disconnect();    CHECK(sig.connectedSlots() == 1);  }}TEST_CASE("signal can be emitted") {  int x{0};  auto lambda = [&x](int value) { x = x + value; };  sigslotpp::Signal<void, int> sig;  sig.connect(lambda);  sig.emit(5);  CHECK(x == 5);  sig.emit(1);  CHECK(x == 6);  sig.emit(-6);  CHECK(x == 0);}int sum = 0;struct x {  void f(int i) { sum += i; }};TEST_CASE("signal can be automatically disconnected") {  auto a = std::make_shared<x>();  sigslotpp::Signal<void, int> sig;  sig.connect(a, &x::f);  sig.emit(4);  sig.emit(3);  sig.emit(-2);  CHECK(sum == 5);  a.reset();  sig.emit(9);  CHECK(sum == 5);  CHECK(sig.connectedSlots() == 0);}TEST_CASE("signal connection to slot can be blocked") {  int x{0};  auto lambda = [&x](int value) { x = x + value; };  sigslotpp::Signal<void, int> sig;  auto c1 = sig.connect(lambda);  sig.emit(5);  CHECK(x == 5);  c1.block();  sig.emit(1);  CHECK(x == 5);  c1.unblock();  sig.emit(-6);  CHECK(x == -1);}

Analysis

The classes involved are:

• ISlotConnection
• ISlot
• SimpleSlot
• TrackingSlot
• ISignal
• Signal
• Connection

There is no need to walk through every class line by line, but two elements deserve a closer explanation: TrackingSlot and Connection.

The TrackingSlot class

This class makes it possible, via a std::weak_ptr, to track the in-memory existence of a specific object. To do that, from a design point of view, it requires the use of smart pointers, and in particular a std::shared_ptr to instantiate the object to be tracked.

When the weak_ptr is no longer able to lock, it means the tracked object has reached the end of its lifetime.

This slot is not removed immediately at the end of the tracked object's lifetime, but on the next emit of the signal it is connected to.

It is important to point out that this class does not interfere with the lifecycle of the tracked object.

The Connection class

This class does not follow the RAII pattern. It serves as an explicit access point to the connection between signal and slot. Connection holds a reference, a weak_ptr, to the slot created as the result of a signal.connect(...) call.

The class can operate on the following slot features:

• Disconnection
• Blocking/unblocking the reception of a signal emission
• Checking the state of the slot

It is important to point out that the lifecycle of this class does not affect the lifecycle of the slot.

Open issues

There are some immediate functional gaps, namely:

1. It is not thread-safe.
2. I can't disconnect directly from the slot (imagine a signal that should only be emitted once).
3. Method overloading.
4. Methods with default values.
5. There is no way to retrieve the slots' return value.

I do not address point 1 here, given the complexity of thread safety.

For point 4, I have not found a satisfying solution yet.

Issue 5 only exists for design reasons; I preferred not to implement it because it was unnecessary for the purpose of the Signal class. In my implementation it is possible to connect to slots with return values, which are then transformed into slots with a void return. To implement the return value you would need a helper vector in which to store the return of each slot, and to expose methods that let you read from it. Obviously each emit would overwrite that vector.

Issue: disconnecting directly from the slot

The Connection class solves this problem directly. The idea is to add an ExtendedSlot class with a Connection member variable, so the connection can be injected inside the invoke function. There is a trade-off, however: the connected function now needs to accept a Connection parameter.

Here is one possible solution.

We add an ExtendedSlot class.

template <typename... Args>class ExtendedSlot final : public ISlot<Args...> { private:  std::function<void(Args...)>      function_;  ///< function to be invoked by this slotConnection connection_ ///< connection handle injected into the slot protected:  void invoke(Args... args) override final {    function_(connection_, std::forward<Args>(args)...);  } public:  ExtendedSlot(const IDType id, std::function<void(Args...)> &&function,             ISignal &signal) noexcept      : ISlot<Args...>(id, signal),        function_(std::forward<std::function<void(Args...)>>(function)) {}  // Not ideal, but enough for this implementation.  void setConnection(Connection connection) { connection_ = connection }};

We modify Signal and add a connectExtended method.

 Connection connectExtended(std::function<R(Args...)> &&function) noexcept {  IDType id = slots_.size();  std::shared_ptr<ISlot<Args...>> slot =      std::make_shared<ExtendedSlot<Args...>>(          id, std::forward<std::function<R(Args...)>>(function), *this);  slots_.push_back(slot);  auto c = Connection(std::weak_ptr(slots_[id]));  slots_[id]->setConnection(c);  return c;}

Usage would look like this.

int main() {  int i = 0;  sigslot::signal<void> sig;  auto f = [](auto &con) {    i += 1;    con.disconnect();  };  sig.connectExtended(f);}

The limitation is that each slot now needs that Connection parameter, and it has to be the first argument.

Issue: overloading

If we add the following support functions, we can solve this one too.

template <typename T, typename R, typename... Args>constexpr auto overload(R(I::*ptr)(Args...)) {    return ptr;}template <typename R, typename... Args>constexpr auto overload(R(*ptr)(Args...)) {    return ptr;}

Once expanded, the parameter pack makes the overload unambiguous:

struct obj {  void operator()(int) const {}  void operator()() {}};struct foo {  void bar(int) {}  void bar() {}  static void baz(int) {}  static void baz() {}};void moo(int) {}void moo() {}int main() {  sigslot::signal<void, int> sig;  foo ff;  sig.connect(overload<int>(&foo::bar), &ff);  sig.connect(overload<int>(&foo::baz));  sig.connect(overload<int>(&moo));  sig.connect(obj());  sig(0);  return 0;}

Conclusion

We've seen how to implement a signal/slot mechanism. The solution has clear limitations, but it provides a simple interface without hidden mechanisms.

With this foundation we can implement the observer pattern in a clear and controlled way.

At this link you can find the project folder, which you can compile with CMake.

Sooner or later, every C++ project has to deal with CMake, dependencies, internal libraries, and applications built on top of those libraries. In my first projects I often spent too much time organizing directories and keeping every CMakeLists.txt file consistent. When the structure is unclear, adding a module or dependency can make the build more fragile than it needs to be.

After studying how other developers organize their projects, I found a structure I like for its simplicity and clarity.

What follows is opinionated. The structure is designed to:

• Avoid patterns that cause conflicts.
• Avoid making the build more complicated than it needs to be.
• Make the project easier to read.

Tools used

For this example I will use three tools.

CMake

CMake is a free, cross-platform software for build automation whose name is short for cross platform make. This software was born to replace Automake in the generation of Makefiles, trying to be simpler to use. In fact, on most projects there is no Makefile included in the sources, since that would not be portable.

-- Wikipedia

We will use it to generate the build system and compile the project.

This is not a complete CMake guide; the focus here is project layout. For deeper documentation, start from the official CMake website.

Conan

Conan is a dependency and package manager for C and C++ languages. It is free and open-source, works in all platforms ( Windows, Linux, OSX, FreeBSD, Solaris, etc.), and can be used to develop for all targets including embedded, mobile (iOS, Android), and bare metal. It also integrates with all build systems like CMake, Visual Studio (MSBuild), Makefiles, SCons, etc., including proprietary ones.

-- Conan

We will use it for dependency and package management.

For more details, see the official Conan website.

Before moving on, here are the minimum Conan steps used in this project.

Start by generating a Conan profile, which describes the compiler, build configuration, architecture, and other environment settings.

conan profile detect --force

When the command finishes, if you are on Unix, you'll find a .conan2 folder in your home directory containing the files mentioned above.

To install dependencies, run:

conan install . --output-folder=build --build=missing

Conan then performs two main operations:

• It installs the libraries specified in the conanfile.txt from a remote server, usually Conan Center, if they are available. This server stores both Conan recipes, which define how the libraries should be built, and binaries that can be reused so you don't have to recompile them every time.
• It generates several files in the build directory.
  • CMakeDeps generates the files needed to let CMake find the libraries we downloaded.
  • CMakeToolchain generates a CMake toolchain file so we can build our project with CMake.

Doxygen

Doxygen is an application for the automatic generation of documentation starting from the source code of a generic software. It is an open-source project available under the GPL license, written mostly by Dimitri van Heesch starting in 1997.

-- Wikipedia

Doxygen generates documentation from comments in the source code. As with the previous tools, this article will not cover it in depth. For details, see the official Doxygen website.

Structure

The project structure looks like this.

.├── CMakeLists.txt├── conanfile.txt├── conan_provider.cmake├── libfoo│   ├── CMakeLists.txt│   ├── docs│   │   └── CMakeLists.txt│   ├── include│   │   └── libfoo│   │       └── foo.hpp│   ├── src│   │   └── foo.cpp│   └── tests│       ├── foo.test.cpp│       └── main.cpp└── standalone    ├── CMakeLists.txt    └── main.cpp

Let's go through it more carefully.

The underlying idea is to separate project components by directory. Each directory contains either an executable or a library and defines its own target.

standalone is the executable target. In this example it uses the libfoo library and represents an application built on top of one or more core libraries.

libfoo is a static library used by standalone, but it is organized as a self-contained component with a public interface, implementation, tests, and documentation. Each library has to:

• Follow a predictable structure.
  • An include directory for public declarations, which form the library interface.
  • A src directory for definitions and private headers.
• Provide documentation generation through Doxygen.
• Provide a testing environment with doctest (or similar).

The image below shows the idea: app executables use core libraries, while each component stays separate.

Top-level CMakeLists.txt

The CMakeLists.txt at the root contains the top-level configuration of our project. Its contents are below.

cmake_minimum_required(VERSION 3.27)### Projectproject(cpp_project_structure VERSION 1.0 LANGUAGES CXX)set(CMAKE_CXX_STANDARD 17)set(CMAKE_EXPORT_COMPILE_COMMANDS ON)### Packagesfind_package(fmt REQUIRED)find_package(doctest REQUIRED)find_package(Doxygen REQUIRED)### Subdirectories (the order is important)add_subdirectory(libfoo)add_subdirectory(standalone)

We have a single project and we tell CMake to look for other configuration files in the libfoo and standalone subfolders, respectively "core" and "app". We then specify a few simple variables and issue find_package commands to look for the dependencies needed by the build process.

Dependency management

The conanfile.txt file specifies the packages our project's targets need. In our case fmt is used by both libfoo and standalone, and doctest is required by libfoo for unit tests. Its contents are below.

[requires]fmt/10.2.1doctest/2.4.11[layout]cmake_layout

To use Conan more comfortably, we leverage the cmake-conan wrapper. We're specifically interested in the conan_provider.cmake file, which we save at the root of the project. This file will come in handy later.

The libfoo target

The libfoo target, which in our case is a static library, follows the canonical shape of a standard library. Going back to the idea of one target per subdirectory, our CMakeLists.txt is the one below.

### Library libfooadd_library(libfoo STATIC src/foo.cpp        include/libfoo/foo.hpp)add_library(libfoo::libfoo ALIAS libfoo)set_target_properties(libfoo PROPERTIES VERSION 0.0)target_include_directories(libfoo PUBLIC include PRIVATE src)target_link_libraries(libfoo PRIVATE fmt::fmt)target_compile_options(libfoo PRIVATE -Wall -Wextra -pedantic -Werror)target_compile_features(libfoo PRIVATE cxx_std_17)### Testing libfooadd_executable(libfoo_tests tests/main.cpp)target_link_libraries(libfoo_tests PRIVATE doctest::doctest)target_compile_options(libfoo_tests PRIVATE -Wall -Wextra -pedantic -Werror)target_compile_features(libfoo_tests PRIVATE cxx_std_17)### Subdirectoriesadd_subdirectory(docs)

There are three sections:

• The library definition and its configuration.
• Setting up and creating the target for the unit tests.
• Enabling and configuring Doxygen for documentation generation.

For clarity, here is the contents of the CMakeLists.txt in the docs folder.

set(DOXYGEN_ALPHABETICAL_INDEX NO)set(DOXYGEN_BUILTIN_STL_SUPPORT YES)set(DOXYGEN_CASE_SENSE_NAMES NO)set(DOXYGEN_CLASS_DIAGRAMS NO)set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)# set(DOXYGEN_EXAMPLE_PATH "")set(DOXYGEN_EXCLUDE bin)set(DOXYGEN_EXTRACT_ALL YES)set(DOXYGEN_EXTRACT_LOCAL_CLASSES NO)set(DOXYGEN_FILE_PATTERNS *.hpp)set(DOXYGEN_GENERATE_TREEVIEW YES)set(DOXYGEN_HIDE_FRIEND_COMPOUNDS YES)set(DOXYGEN_HIDE_IN_BODY_DOCS YES)set(DOXYGEN_HIDE_UNDOC_CLASSES YES)set(DOXYGEN_HIDE_UNDOC_MEMBERS YES)set(DOXYGEN_JAVADOC_AUTOBRIEF YES)set(DOXYGEN_QT_AUTOBRIEF YES)set(DOXYGEN_QUIET YES)set(DOXYGEN_RECURSIVE YES)set(DOXYGEN_REFERENCED_BY_RELATION YES)set(DOXYGEN_REFERENCES_RELATION YES)set(DOXYGEN_SORT_BY_SCOPE_NAME YES)set(DOXYGEN_SORT_MEMBER_DOCS NO)set(DOXYGEN_SOURCE_BROWSER YES)set(DOXYGEN_STRIP_CODE_COMMENTS NO)doxygen_add_docs(        libfoo_docs        "../include/"        ALL        COMMENT "Generate HTML documentation for libfoo")

The standalone target

Unlike the libfoo target, this one is much more trivial. The configuration follows.

add_executable(standalone main.cpp)target_link_libraries(standalone PRIVATE fmt::fmt libfoo::libfoo)target_compile_options(standalone PRIVATE -Wall -Wextra -pedantic -Werror)target_compile_features(standalone PRIVATE cxx_std_17)

Building

cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake -DCMAKE_BUILD_TYPE=Debugcmake --build build --config Debug

With the first command we run the out-of-tree configuration phase, generating a build system. With the second one we build the project by calling the system build tool, make on Unix.

Remember the conan_provider.cmake file mentioned earlier? Well, by using the -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake flag in the cmake configuration process, cmake automatically invokes the conan install command, simplifying project management.

Conclusion

Now in the build folder, under the project root, we'll find the binaries and libraries we compiled, plus the Doxygen documentation and the unit-test executable.

This structure can easily be expanded by adding a CI/CD pipeline and more.

I hope this was useful. At this link you can find the repository of the project discussed in this article so you can study it.

For a long time I wondered whether I really had anything useful to write. Eventually I reached a simple conclusion: if I never started, I would never find out.

So this is my first public post.

It does not contain a technical deep dive yet, but it marks the beginning of a space where I can collect what I learn, the projects I work on, and the ideas worth developing with more care.

I will mostly write about computer science, software development, and technology, with room for personal notes and other topics I find interesting.

Thanks for stopping by. Enjoy the reading.

Nicolò