From Fedora Project Wiki

(Created page with "There are two basic categories of C and C++ packages: applications and libraries. The following are general packaging guidelines for C and C++ applications and libraries. Some...")
 
(Deprecate page.)
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
There are two basic categories of C and C++ packages: applications and libraries. The following are general packaging guidelines for C and C++ applications and libraries. Some of these guidelines will also apply to packages that use cpp to process C or C++ headers.
+
{{OldGuidelinePage|C_and_C++}}
  
== BuildRequires for C and C++ applications ==
+
= Introduction =
  
If your application is a C or C++ application you must list a `BuildRequires` against `gcc`, `gcc-c++` or `clang`. Those packages will include everything that is required to build a standards conforming C or C++ application.
+
The C and C++ 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 C++ packaging.
  
If your library includes standard C or C++ headers, you must list `Requires` against `gcc`, `gcc-c++`, or `clang` to install the needed standards conforming headers.
+
= Packaging =
  
If at runtime you use `cpp` to process C or C++ langauge headers then you have no choice but to use `Requires` for `gcc`, `gcc-c++`, or `clang` to install the required headers for a standard conforming C or C++ application. In the future this might change if a set of standard C or C++ language headers are provided by a special-purpose provides e.g. `c-headers` or `c++-headers`.
+
== BuildRequires and Requires ==
  
You need not include a `BuildRequires` or `Requires` on `glibc-headers`, or any other core C or C++ implementation package unless you have a specific and special need e.g. static compilation requires the `*-static` library packages. The default use case of a dynamically compiled C or C++ application is taken care of by the gcc, gcc-c++, and clang packages.
+
If your application is a C or C++ application you must list a <code>BuildRequires</code> against <code>gcc</code>, <code>gcc-c++</code> or <code>clang</code>. Those packages will include everything that is required to build a standards conforming C or C++ application.
 +
 
 +
If your library includes standard C or C++ headers, you must list <code>BuildRequires</code> against <code>gcc</code>, <code>gcc-c++</code>, or <code>clang</code> to install the needed standards conforming headers.
 +
 
 +
If at runtime you use <code>cpp</code> to process C or C++ language headers then you have no choice but to use <code>Requires</code> for <code>gcc</code>, <code>gcc-c++</code>, or <code>clang</code> to install the required headers for a standard conforming C or C++ application. In the future this might change if a set of standard C or C++ language headers are provided by a special-purpose provides e.g. <code>c-headers</code> or <code>c++-headers</code>.
 +
 
 +
You need not include a <code>BuildRequires</code> or <code>Requires</code> on <code>glibc-headers</code>, or any other core C or C++ implementation package unless you have a specific and special need e.g. static compilation requires the <code>.*-static</code> library packages e.g. <code>BuildRequires: glibc-static</code>. The default use case of a dynamically compiled C or C++ application is taken care of by the <code>gcc</code>, <code>gcc-c++</code>, and <code>clang</code> packages.
 +
 
 +
Please refer to [https://fedoraproject.org/wiki/Packaging:Guidelines#Compiler Packaging:Guidelines Compiler] for the list of supported compilers for C and C++ compilers.
 +
 
 +
== Packaging Q&A ==
 +
 
 +
Q: Do I need a <code>Requires: glibc</code> to ensure I have the C runtime installed for my application?
 +
 
 +
A: 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.
 +
 
 +
Q: Do I need to include a <code>Requires: libgcc</code>?
 +
 
 +
A: If you are using an API from <code>libgcc</code> directly, then yes, you must have a <code>Requires: libgcc</code>. In general though <code>glibc</code> requires <code>libgcc</code>, so it is always installed.
 +
 
 +
= Libraries =
 +
 
 +
Libraries should have unique shared object names (SONAMEs via <code>-Wl,-soname=libfoo.so</code>) that do not conflict with other library SONAMEs used in the distribution. For example there should be only one <code>libfoo.so</code> in the distribution. The exception is when there are multiple implementations of the same library <code>libfoo.so</code> provided by different authors and each conflicts with the other. In this case both <code>libfoo.so</code> must provide exactly the same interface, but with a different implementation. Having two <code>libfoo.so</code> 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.
  
 
[[Category:Packaging guidelines]]
 
[[Category:Packaging guidelines]]

Latest revision as of 03:38, 20 December 2018

Warning.png
This is an old copy of a packaging guideline, preserved here in the wiki while we complete the transition to the Fedora documentation system. The current version is located at https://docs.fedoraproject.org/en-US/packaging-guidelines/C_and_C++/. Please update your bookmarks.

Introduction

The C and C++ 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 C++ packaging.

Packaging

BuildRequires and Requires

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

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

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

You need not include a BuildRequires or Requires on glibc-headers, or any other core C or C++ 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 C++ application is taken care of by the gcc, gcc-c++, and clang packages.

Please refer to Packaging:Guidelines Compiler for the list of supported compilers for C and C++ compilers.

Packaging Q&A

Q: Do I need a Requires: glibc to ensure I have the C runtime installed for my application?

A: 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.

Q: Do I need to include a Requires: libgcc?

A: 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.