From Fedora Project Wiki

m (Add Packaging guidelines category)
(7 intermediate revisions by 4 users not shown)
Line 7: Line 7:
== Compilation ==
== Compilation ==


Ada code in Fedora '''MUST''' be compiled using GNAT, the default Ada compiler in Fedora. All packages that contain Ada code MUST build-require the gcc-gnat package to ensure that the compiler is available. The RPM macro %{GNAT_optflags} '''MUST''' be used in the compilation. It contains the standard Fedora optimization flags adapted to GNAT.
* Ada code in Fedora '''MUST''' be compiled using GNAT, the default Ada compiler in Fedora. All packages that contain Ada code '''MUST''' have "<code>BuildRequires: gcc-gnat</code>" to ensure that the compiler is available.


All packages that contain Ada code '''MUST''' build-require the fedora-gnat-project-common package to ensure that the necessary RPM macros are defined.
* The RPM macros Gnatmake_optflags and GPRbuild_optflags expand to Fedora's standard compiler and linker flags adapted for Gnatmake and GPRbuild respectively. The appropriate macro '''MUST''' be used in packages that are built with Gnatmake or GPRbuild. In case the package's build system invokes the underlying GNAT tools without using Gnatmake or GPRbuild, then the appropriate macro for each tool '''MUST''' be used. If for example Gnatlink is invoked directly, then the expansion of Gnatlink_flags shall be passed to it.


If the upstream source package comes with a build system, for example a GNAT project file or makefiles and a configuration script, then it's probably best to use that if possible. If not, it is recommended that the packager write a GNAT project file to control the compilation.
* The macro GNAT_arches expands to a list of architectures where GNAT packages are available in Fedora. Starting with Fedora 18, when there is a need to prevent attempts to build an Ada package on secondary architectures where GNAT has not been bootstrapped, this '''MUST''' be done with "<code>ExclusiveArch: %{GNAT_arches}</code>".
 
* All packages that contain Ada code '''MUST''' have "<code>BuildRequires: fedora-gnat-project-common</code>" to ensure that the necessary RPM macros are defined.
 
* If the upstream source package comes with a build system, for example a GNAT project file or makefiles and a configuration script, then it's probably best to use that if possible. If not, it is recommended that the packager write a GNAT project file to control the compilation.


== Devel packages ==
== Devel packages ==


* Ada library packages '''MUST''' have a -devel subpackage containing all the files that are necessary for compilation of code that uses the library. This includes Ada specification files (*.ads), Ada body files (*.adb), Ada library information files (*.ali) and GNAT project files (*.gpr).
* Ada library packages '''MUST''' have a -devel subpackage containing all the files that are necessary for compilation of code that uses the library. This includes Ada specification files (*.ads), Ada body files (*.adb), Ada library information files (*.ali) and GNAT project files (*.gpr). (There is no requirement to include all body files. Typically only some body files are needed.)
* The -devel package '''MUST NOT''' contain all the source files of the library, only those that are necessary for compilation of code that uses the library.
* The -devel package '''MUST NOT''' contain any makefiles or other files that are only used for recompiling the library.
* The -devel package '''MUST NOT''' contain any makefiles or other files that are only used for recompiling the library.
* The -devel package '''MUST NOT''' contain any *.o files.
* The -devel package '''MUST NOT''' contain any *.o files.
Line 24: Line 27:
* The -devel package '''MUST''' contain one or more GNAT project files to be imported by other projects that use the library.
* The -devel package '''MUST''' contain one or more GNAT project files to be imported by other projects that use the library.
* Project files '''MUST''' be architecture-independent. This means that the same project file must point to libraries in /usr/lib or /usr/lib64 depending on what target architecture the compiler is currently compiling for. This '''SHOULD''' be done by importing the "directories" project (that is, the project file directories.gpr) and using the variable Directories.Libdir which is defined there. The value of Directories.Libdir is set to either "/usr/lib" or "/usr/lib64" depending on the hardware platform.
* Project files '''MUST''' be architecture-independent. This means that the same project file must point to libraries in /usr/lib or /usr/lib64 depending on what target architecture the compiler is currently compiling for. This '''SHOULD''' be done by importing the "directories" project (that is, the project file directories.gpr) and using the variable Directories.Libdir which is defined there. The value of Directories.Libdir is set to either "/usr/lib" or "/usr/lib64" depending on the hardware platform.
* Project files '''SHOULD NOT''' contain hard-coded directory names, neither absolute nor relative; they should get them from some source. The source '''MAY''' be an Autoconf-generated configuration script or other build system. Project files that aren't pre-processed by such a build system '''SHOULD''' use the variable Directories.Includedir rather than a hard-coded "/usr/include".
* Project files '''MUST NOT''' contain hard-coded directory names, neither absolute nor relative; they should get them from some source. The source may be an Autoconf-generated configuration script or other build system. Project files that aren't pre-processed by such a build system '''SHOULD''' use the variable Directories.Includedir rather than a hard-coded "/usr/include".
* If the "directories" project is used, then the -devel package '''MUST''' have an explicit "<code>Requires: fedora-gnat-project-common >= 2</code>".
* If the "directories" project is used, then the -devel package '''MUST''' have an explicit "<code>Requires: fedora-gnat-project-common</code>".
* Project files '''MUST''' have an Externally_Built attribute equal to "true".
* Project files '''MUST''' have an Externally_Built attribute equal to "true".
Here's an example of what a project file installed with a library may look like:
Here's an example of what a project file installed with a library may look like:
Line 42: Line 45:
== File placement ==
== File placement ==


* Ada source files in -devel packages (*.ads and *.adb) '''SHOULD''' be placed in the <code>%{_includedir}</code> directory or a subdirectory thereof. Placing them directly in <code>%{_includedir}</code> may be appropriate if there are very few of them in the package and their names include the name of the library. Otherwise they should usually be placed  in a subdirectory, for example <code>%{_includedir}/%{name}</code>.
* Ada source files in -devel packages (*.ads and *.adb) '''MUST''' be placed in the <code>%{_includedir}</code> directory or a subdirectory thereof. Placing them directly in <code>%{_includedir}</code> may be appropriate if there are very few of them in the package and their names include the name of the library. Otherwise they should usually be placed  in a subdirectory, for example <code>%{_includedir}/%{name}</code>.
* Ada library information files (*.ali) '''SHOULD''' be placed in a subdirectory of <code>%{_libdir}</code>, for example <code>%{_libdir}/%{name}</code>.
* Ada library information files (*.ali) '''MUST''' be placed in a subdirectory of <code>%{_libdir}</code>, for example <code>%{_libdir}/%{name}</code>.
* GNAT projects files (*.gpr) '''MUST''' be placed in the <code>%{_GNAT_project_dir}</code> directory or a subdirectory thereof. A subdirectory, for example <code>%{_GNAT_project_dir}/%{name}</code>, may be a good idea if there are lots of project files in the same package or if they have generic names. Otherwise they should usually be placed directly in <code>%{_GNAT_project_dir}</code>. The name of the library '''SHOULD''' be included either in the name of each project file or in the name of the subdirectory where the project files are placed.
* GNAT projects files (*.gpr) '''MUST''' be placed in the <code>%{_GNAT_project_dir}</code> directory or a subdirectory thereof. A subdirectory, for example <code>%{_GNAT_project_dir}/%{name}</code>, may be a good idea if there are lots of project files in the same package or if they have generic names. Otherwise they should usually be placed directly in <code>%{_GNAT_project_dir}</code>. The name of the library '''MUST''' be included either in the name of each project file or in the name of the subdirectory where the project files are placed.
{{Admon/note | Note| The current value of <code>%{_GNAT_project_dir}</code> is <code>/usr/lib/gnat</code>. We intend to change it to <code>/usr/share/gpr</code>, which is more in line with FHS, if we can get GNAT to use that directory.}}


== Rpmlint and Ada packages ==
== Rpmlint and Ada packages ==
Rpmlint is a program that checks packages for common problems. For Ada packages, some of the rpmlint messages, such as "executable-stack", can be disregarded, because GNAT uses trampolines for pointers to nested functions. (See for example [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355 this entry in the GCC Bugzilla].)
Rpmlint is a program that checks packages for common problems. For Ada packages, some of the rpmlint messages, such as "executable-stack", can be disregarded, because GNAT uses trampolines for pointers to nested functions. (See for example [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355 this entry in the GCC Bugzilla].)


[[ Category:Packaging guidelines drafts ]]
[[Category: Packaging guidelines]]

Revision as of 16:04, 25 April 2012

Packaging Ada programs and libraries

This document describes the current policies for packaging Ada programs and libraries for Fedora. These are Ada-specific amendments to the generic Packaging Guidelines. Ada packages must also conform to the Packaging Guidelines and the Review Guidelines.

Compilation

  • Ada code in Fedora MUST be compiled using GNAT, the default Ada compiler in Fedora. All packages that contain Ada code MUST have "BuildRequires: gcc-gnat" to ensure that the compiler is available.
  • The RPM macros Gnatmake_optflags and GPRbuild_optflags expand to Fedora's standard compiler and linker flags adapted for Gnatmake and GPRbuild respectively. The appropriate macro MUST be used in packages that are built with Gnatmake or GPRbuild. In case the package's build system invokes the underlying GNAT tools without using Gnatmake or GPRbuild, then the appropriate macro for each tool MUST be used. If for example Gnatlink is invoked directly, then the expansion of Gnatlink_flags shall be passed to it.
  • The macro GNAT_arches expands to a list of architectures where GNAT packages are available in Fedora. Starting with Fedora 18, when there is a need to prevent attempts to build an Ada package on secondary architectures where GNAT has not been bootstrapped, this MUST be done with "ExclusiveArch: %{GNAT_arches}".
  • All packages that contain Ada code MUST have "BuildRequires: fedora-gnat-project-common" to ensure that the necessary RPM macros are defined.
  • If the upstream source package comes with a build system, for example a GNAT project file or makefiles and a configuration script, then it's probably best to use that if possible. If not, it is recommended that the packager write a GNAT project file to control the compilation.

Devel packages

  • Ada library packages MUST have a -devel subpackage containing all the files that are necessary for compilation of code that uses the library. This includes Ada specification files (*.ads), Ada body files (*.adb), Ada library information files (*.ali) and GNAT project files (*.gpr). (There is no requirement to include all body files. Typically only some body files are needed.)
  • The -devel package MUST NOT contain any makefiles or other files that are only used for recompiling the library.
  • The -devel package MUST NOT contain any *.o files.

GNAT project files

  • The -devel package MUST contain one or more GNAT project files to be imported by other projects that use the library.
  • Project files MUST be architecture-independent. This means that the same project file must point to libraries in /usr/lib or /usr/lib64 depending on what target architecture the compiler is currently compiling for. This SHOULD be done by importing the "directories" project (that is, the project file directories.gpr) and using the variable Directories.Libdir which is defined there. The value of Directories.Libdir is set to either "/usr/lib" or "/usr/lib64" depending on the hardware platform.
  • Project files MUST NOT contain hard-coded directory names, neither absolute nor relative; they should get them from some source. The source may be an Autoconf-generated configuration script or other build system. Project files that aren't pre-processed by such a build system SHOULD use the variable Directories.Includedir rather than a hard-coded "/usr/include".
  • If the "directories" project is used, then the -devel package MUST have an explicit "Requires: fedora-gnat-project-common".
  • Project files MUST have an Externally_Built attribute equal to "true".

Here's an example of what a project file installed with a library may look like:

with "directories";
project Example is
   for Library_Name use "example";
   for Source_Dirs use (Directories.Includedir & "/example");
   for Library_Dir use Directories.Libdir;
   for Library_ALI_Dir use Directories.Libdir & "/example";
   for Externally_Built use "true";
end Example;

File placement

  • Ada source files in -devel packages (*.ads and *.adb) MUST be placed in the %{_includedir} directory or a subdirectory thereof. Placing them directly in %{_includedir} may be appropriate if there are very few of them in the package and their names include the name of the library. Otherwise they should usually be placed in a subdirectory, for example %{_includedir}/%{name}.
  • Ada library information files (*.ali) MUST be placed in a subdirectory of %{_libdir}, for example %{_libdir}/%{name}.
  • GNAT projects files (*.gpr) MUST be placed in the %{_GNAT_project_dir} directory or a subdirectory thereof. A subdirectory, for example %{_GNAT_project_dir}/%{name}, may be a good idea if there are lots of project files in the same package or if they have generic names. Otherwise they should usually be placed directly in %{_GNAT_project_dir}. The name of the library MUST be included either in the name of each project file or in the name of the subdirectory where the project files are placed.

Rpmlint and Ada packages

Rpmlint is a program that checks packages for common problems. For Ada packages, some of the rpmlint messages, such as "executable-stack", can be disregarded, because GNAT uses trampolines for pointers to nested functions. (See for example this entry in the GCC Bugzilla.)