Ada Packaging Guidelines

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 GNAT tools are usually invoked through the builder GPRbuild, so Ada packages typically need “BuildRequires: gprbuild”.

  • There are a number of RPM macros that contain Fedora’s standard compiler and linker flags adapted for GNAT. The appropriate macro MUST be used in the build stage. The right macro to use depends on what build tools the package uses.

    • For packages that are built with GPRbuild or Gnatmake but without Comfignat there are the macros GPRbuild_flags and Gnatmake_flags, which contain builder, compiler and linker flags.

    • In case a package’s build system invokes the underlying GNAT tools without using GPRbuild or Gnatmake, 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.

    • For packages whose build systems use Comfignat there is the macro Comfignat_make. It expands to a Make command with appropriate values for Comfignat’s configuration variables, including builder, compiler and linker flags, directory variables and the directories project. Use it alone to build the default target:

      %build
%{Comfignat_make}

      If needed, a different target and/or additional variables may be appended:

      %{Comfignat_make} demo_programs atomic_doodads=true

      For the installation stage of Comfignat-using packages, the macro make_install (not makeinstall) is recommended.

  • The macros GPRbuild_arches and GNAT_arches expand to a list of architectures where GNAT packages are available in Fedora. 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 either “ExclusiveArch: %{GPRbuild_arches}” or “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 and use GPRbuild to control the compilation.

Trampolines

An executable stack has been made a linker error in Fedora. This can affect Ada packages because GCC uses trampolines to implement some language constructs. The compiler’s usage of trampolines has been greatly reduced, but some cases remain. One case that occurs is when a nested subprogram in Ada is passed as a callback routine to a function written in C – which means that the executable stack is also exposed to C code that may contain buffer overflows. In such cases the options are to explicitly allow an executable stack by passing “-largs -Wl,--no-warn-execstack” to GPRbuild, or restructure the code to eliminate the need for trampolines. Which option is best may depend on how exposed the program is to potentially hostile input.

Correct usage of the RPM macros should result in a warning message from the compiler that points out where in the code a trampoline is needed.

Runpaths

GPRbuild adds a runpath to the built binaries by default. Fedora’s builder flags normally include an option to disable the automatic runpath. There are however cases where it would be advantageous to allow a runpath. Libraries can have test suites or auxiliary programs that aren’t installed but run during the build and need to link to the library in the build directory, and they may rely on an automatic runpath for this. In those cases the spec file may define a macro named GNAT_add_rpath. The builder will then be allowed to add a runpath in those parts of the spec file where GNAT_add_rpath is defined.

GNAT_add_rpath does not exempt a package from the Packaging Guidelines. The policy on runpaths still applies.

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.

Packages that use GPRinstall in the installation phase can use the macro GPRinstall_flags to pass the correct pathnames and other parameters to GPRinstall.

Want to help? Learn how to contribute to Fedora Docs ›