From 18475c2cebc059273d9ea57a1ddb8abef9d38a57 Mon Sep 17 00:00:00 2001 From: Björn Persson Date: Nov 18 2018 11:01:39 +0000 Subject: Switced to typographical quotation marks and apostrophes, because ASCII quotation marks and apostrophes seem to make Asciidoctor very confused. --- diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc index 4edce2e..c22685e 100644 --- a/guidelines/modules/ROOT/pages/Ada.adoc +++ b/guidelines/modules/ROOT/pages/Ada.adoc @@ -4,11 +4,19 @@ This document describes the current policies for packaging Ada programs and libr == 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. -* 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. +* 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. +* 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 `+Gnatmake+` or `+GPRbuild+` but without `+Comfignat+` there are the macros `+%Gnatmake_optflags+` and `+%GPRbuild_optflags+`, which contain builder, compiler and linker flags. -** In case a 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. -** 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: +** In case a 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. +** 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 @@ -18,13 +26,25 @@ This document describes the current policies for packaging Ada programs and libr .... + For the installation stage of Comfignat-using packages, the macro `+%make_install+` (*not* `+%makeinstall+`) is recommended. -* 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. +* 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. == Runpaths -Gnatmake and GPRbuild both add 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 builders will then be allowed to add a runpath in those parts of the spec file where GNAT_add_rpath is defined. +Gnatmake and GPRbuild both add 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 builders will then be allowed to add a runpath in those parts of the spec file where GNAT_add_rpath is defined. Packages that contain Ada code *SHOULD* run `+%{_rpmconfigdir}/check-rpaths+` as the last thing in the `+%check+` section. This is a precaution against packaging bugs and toolchain bugs that would cause binaries with runpaths to end up in packages. All packages that use GNAT_add_rpath *MUST* do this (and must therefore have a `+%check+` section). @@ -43,12 +63,20 @@ Typically only some body files are needed.) === 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: +* 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"; @@ -77,4 +105,9 @@ The name of the library *MUST* be included either in the name of each project fi == 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].)