fedora-llm-docs/Documents/pages/C_and_C++.txt

= C and C++ Packaging Guidelines
// https://github.com/asciidoctor/asciidoctor/commit/426d8389aa1706a589b66c96801542f587ae6b61
:pp: ++

== Introduction

The C and {cpp} languages and runtimes
are one of the most common development frameworks for packages in fedora.
As such there is a wide variety of quality, style, and convention
in all of those packages.
The follow document provides best practice
for certain aspects of C and {cpp} packaging.

== Packaging

=== BuildRequires and Requires

If your application is a C or {cpp} application
you must list a `BuildRequires` against `gcc`, `gcc-c{pp}` or `clang`.
Those packages will include everything that is required
to build a standards conforming C or {cpp} application.

If your library includes standard C or {cpp} headers,
you must list `BuildRequires` against `gcc`, `gcc-c{pp}`, or `clang`
to install the needed standards conforming headers.

If at runtime you use `cpp` to process C or {cpp} language headers
then you have no choice but to use `Requires` for `gcc`, `gcc-c{pp}`, or `clang`
to install the required headers
for a standard conforming C or {cpp} application.
In the future this might change
if a set of standard C or {cpp} language headers are provided
by a special-purpose provides e.g. `c-headers` or `c{pp}-headers`.

You need not include a `BuildRequires` or `Requires` on `glibc-headers`,
or any other core C or {cpp} implementation package
unless you have a specific and special need
e.g. static compilation requires the `.*-static` library packages
e.g. `BuildRequires: glibc-static`.
The default use case of a dynamically compiled C or {cpp} application
is taken care of by the `gcc`, `gcc-c{pp}`, and `clang` packages.

Please refer to xref:index.adoc#compiler[Compiler Guidelines]
for the list of supported compilers for C and {cpp} compilers.

=== Packaging Q&A

[qanda]
Do I need a `Requires: glibc` to ensure I have the C runtime installed for my application?::
No.
RPM will automatically determine what ELF libraries you need
based on the binaries in your package.
This is sufficient to cause glibc to be installed.

Do I need to include a `Requires: libgcc`?::
If you are using an API from `libgcc` directly,
then yes, you must have a `Requires: libgcc`.
In general though `glibc` requires `libgcc`, so it is always installed.

== Libraries

Libraries should have unique shared object names
(SONAMEs via `-Wl,-soname=libfoo.so`)
that do not conflict with other library SONAMEs used in the distribution.
For example there should be only one `libfoo.so` in the distribution.
The exception is when there are multiple implementations of the same library
`libfoo.so` provided by different authors and each conflicts with the other.
In this case both `libfoo.so` must provide exactly the same interface,
but with a different implementation.
Having two `libfoo.so` each with a different API is bad practice
and makes it harder to package and distribute those packages.

Libraries should version all of their symbols using a version script.
Versioning allows the library to avoid changing the SONAME when the API changes
and instead compatibility functions can be written
to provide backwards compatibility for older applications.

== Applications

No additional suggestions are provided for applications at this time.