From Fedora Project Wiki

(_GNAT_project_dir)
(various improvements all over the page)
Line 1: Line 1:
{{autolang|base=yes}}
{{autolang|base=yes}}


== Packaging of Ada programs ==
= Packaging Ada programs and libraries =


=== Introduсtion ===
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|Packaging Guidelines]] and the [[Packaging:ReviewGuidelines|Review Guidelines]].


This document describes all there is to know about Ada in Fedora.
== Compilation ==


=== Compilation ===
Ada code in Fedora '''MUST''' be compiled using GNAT, the default Ada compiler in Fedora. (The package is called gcc-gnat.) The RPM macro %{GNAT_optflags} '''MUST''' be used in the compilation. It contains the standard Fedora optimization flags adapted to GNAT.


Ada programs in Fedora '''MUST''' be compiled using the default Ada compiler in Fedora gcc-gnat. As usual, standard Fedora optimization flags <code>%{optflags}</code> '''MUST''' be used in the compilation.  
All packages that contain Ada code '''MUST''' build-require the fedora-gnat-project-common package to ensure that the necessary RPM macros are defined.
If possible project '''SHOULD''' have makefile and configure script


=== Files placing ===
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.


* All Ada include files '*.adband '*.ads' '''MUST''' be placed in the standard include directory: either directly in <code>%{_includedir}</code>, or if headers have general names or upstream recommends having an own directory, in e.g. <code>%{_includedir}/%{name}</code>.  
== Devel packages ==
* GNAT projects files '''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>.
 
{{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.}}
* 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 Information '*.ali' files SHOULD reside in %{libdir}/%{name}/*.ali.
* The -devel package '''SHOULD 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 '''SHOULD NOT''' contain any makefiles or other files that are only used for recompiling the library.
* The -devel package '''SHOULD 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 and using the variables defined there.
* If the "directories" project is used, then the -devel package '''MUST''' have an explicit "<code>Requires: fedora-gnat-project-common >= 2</code>".
* 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:


=== Rpmlint and Ada packages ===
<pre>
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. [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355 gcc] because Ada and Pascal nested functions do not use trampolines.
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;
</pre>


=== Devel packages ===
== File placement ==


* Ada packages '''MUST''' package Ada specification files (*.ads), Ada body files (*.adb), Ada Library information (*.ali) and GNAT project (*.gpr) files in '''-devel''' package.  
* 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>.
* The '''-devel''' package '''MUST''' depend on '''fedora-gnat-common''' package
* Ada library information files (*.ali) '''SHOULD''' be placed in a subdirectory of <code>%{_libdir}</code>, for example <code>%{_libdir}/%{name}</code>.
* The '''-devel''' package '''MUST''' provide all source files (specs and bodies) necessary for compilation of code that uses the library. The '''-devel''' package '''MUST''' depends on fedora-gnat-project-common package
* 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.
* The directory with all Ada source files '''MUST NOT''' contain any Makefiles or any other files that might be necessary to recompile the library.
{{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.}}
* The '''-devel''' package '''SHOULD NOT''' provide any *.o files.  
* Ada Library information
:The -devel package '''SHOULD''' provide Ada Library Information (*.ali) files that gcc-gnat creates when compiling the shared (relocatable, not static) library.  


* GNAT project file
== Rpmlint and Ada packages ==
: The -devel package for each library '''SHOULD''' provide a GNAT project file named <code>%{_GNAT_project_dir}/%{name}.gpr</code>.  
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. [http://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355 gcc] because Ada and Pascal nested functions do not use trampolines.
<!-- MACROS: You '''SHOULD''' point ADA_PROJECT_PATH="%{_datadir}/ada" to build in packages depends on %{name} -->
<!-- TODO CHECK IT: The project file SHALL have an Externally_Built attribute equal to ‘true’. :Example -->


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

Revision as of 23:21, 17 February 2011

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. (The package is called gcc-gnat.) The RPM macro %{GNAT_optflags} MUST be used in the compilation. It contains the standard Fedora optimization flags adapted to GNAT.

All packages that contain Ada code MUST build-require the fedora-gnat-project-common package 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).
  • The -devel package SHOULD 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 SHOULD NOT contain any makefiles or other files that are only used for recompiling the library.
  • The -devel package SHOULD 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 and using the variables defined there.
  • If the "directories" project is used, then the -devel package MUST have an explicit "Requires: fedora-gnat-project-common >= 2".
  • 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) SHOULD 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) SHOULD 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 SHOULD be included either in the name of each project file or in the name of the subdirectory where the project files are placed.
Note
The current value of %{_GNAT_project_dir} is /usr/lib/gnat. We intend to change it to /usr/share/gpr, which is more in line with FHS, if we can get GNAT to use that directory.

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. gcc because Ada and Pascal nested functions do not use trampolines.