www.delorie.com/gnu/docs/gcc/gnat_ug_61.html   search  
Buy the book!

Untitled Document

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Running gnatbind

The form of the gnatbind command is

$ gnatbind [switches] mainprog[.ali] [switches]

where mainprog.adb is the Ada file containing the main program unit body. If no switches are specified, gnatbind constructs an Ada package in two files which names are `b~ada_main.ads', and `b~ada_main.adb'. For example, if given the parameter `hello.ali', for a main program contained in file `hello.adb', the binder output files would be `b~hello.ads' and `b~hello.adb'.

When doing consistency checking, the binder takes into consideration any source files it can locate. For example, if the binder determines that the given main program requires the package Pack, whose `.ali' file is `pack.ali' and whose corresponding source spec file is `pack.ads', it attempts to locate the source file `pack.ads' (using the same search path conventions as previously described for the gcc command). If it can locate this source file, it checks that the time stamps or source checksums of the source and its references to in `ali' files match. In other words, any `ali' files that mentions this spec must have resulted from compiling this version of the source file (or in the case where the source checksums match, a version close enough that the difference does not matter).

The effect of this consistency checking, which includes source files, is that the binder ensures that the program is consistent with the latest version of the source files that can be located at bind time. Editing a source file without compiling files that depend on the source file cause error messages to be generated by the binder.

For example, suppose you have a main program `hello.adb' and a package P, from file `p.ads' and you perform the following steps:

  1. Enter gcc -c hello.adb to compile the main program.

  2. Enter gcc -c p.ads to compile package P.

  3. Edit file `p.ads'.

  4. Enter gnatbind hello.

At this point, the file `p.ali' contains an out-of-date time stamp because the file `p.ads' has been edited. The attempt at binding fails, and the binder generates the following error messages:

error: "hello.adb" must be recompiled ("p.ads" has been modified)
error: "p.ads" has been modified and must be recompiled

Now both files must be recompiled as indicated, and then the bind can succeed, generating a main program. You need not normally be concerned with the contents of this file, but it is similar to the following which is the binder file generated for a simple "hello world" program.

--  The package is called Ada_Main unless this name is actually used
--  as a unit name in the partition, in which case some other unique
--  name is used.

with System;
package ada_main is

   Elab_Final_Code : Integer;
   pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code");

   --  The main program saves the parameters (argument count,
   --  argument values, environment pointer) in global variables
   --  for later access by other units including
   --  Ada.Command_Line.

   gnat_argc : Integer;
   gnat_argv : System.Address;
   gnat_envp : System.Address;

   --  The actual variables are stored in a library routine. This
   --  is useful for some shared library situations, where there
   --  are problems if variables are not in the library.

   pragma Import (C, gnat_argc);
   pragma Import (C, gnat_argv);
   pragma Import (C, gnat_envp);

   --  The exit status is similarly an external location

   gnat_exit_status : Integer;
   pragma Import (C, gnat_exit_status);

   GNAT_Version : constant String :=
                    "GNAT Version: 3.15w (20010315)";
   pragma Export (C, GNAT_Version, "__gnat_version");

   --  This is the generated adafinal routine that performs
   --  finalization at the end of execution. In the case where
   --  Ada is the main program, this main program makes a call
   --  to adafinal at program termination.

   procedure adafinal;
   pragma Export (C, adafinal, "adafinal");

   --  This is the generated adainit routine that performs
   --  initialization at the start of execution. In the case
   --  where Ada is the main program, this main program makes
   --  a call to adainit at program startup.

   procedure adainit;
   pragma Export (C, adainit, "adainit");

   --  This routine is called at the start of execution. It is
   --  a dummy routine that is used by the debugger to breakpoint
   --  at the start of execution.

   procedure Break_Start;
   pragma Import (C, Break_Start, "__gnat_break_start");

   --  This is the actual generated main program (it would be
   --  suppressed if the no main program switch were used). As
   --  required by standard system conventions, this program has
   --  the external name main.

   function main
     (argc : Integer;
      argv : System.Address;
      envp : System.Address)
      return Integer;
   pragma Export (C, main, "main");

   --  The following set of constants give the version
   --  identification values for every unit in the bound
   --  partition. This identification is computed from all
   --  dependent semantic units, and corresponds to the
   --  string that would be returned by use of the
   --  Body_Version or Version attributes.

   type Version_32 is mod 2 ** 32;
   u00001 : constant Version_32 := 16#7880BEB3#;
   u00002 : constant Version_32 := 16#0D24CBD0#;
   u00003 : constant Version_32 := 16#3283DBEB#;
   u00004 : constant Version_32 := 16#2359F9ED#;
   u00005 : constant Version_32 := 16#664FB847#;
   u00006 : constant Version_32 := 16#68E803DF#;
   u00007 : constant Version_32 := 16#5572E604#;
   u00008 : constant Version_32 := 16#46B173D8#;
   u00009 : constant Version_32 := 16#156A40CF#;
   u00010 : constant Version_32 := 16#033DABE0#;
   u00011 : constant Version_32 := 16#6AB38FEA#;
   u00012 : constant Version_32 := 16#22B6217D#;
   u00013 : constant Version_32 := 16#68A22947#;
   u00014 : constant Version_32 := 16#18CC4A56#;
   u00015 : constant Version_32 := 16#08258E1B#;
   u00016 : constant Version_32 := 16#367D5222#;
   u00017 : constant Version_32 := 16#20C9ECA4#;
   u00018 : constant Version_32 := 16#50D32CB6#;
   u00019 : constant Version_32 := 16#39A8BB77#;
   u00020 : constant Version_32 := 16#5CF8FA2B#;
   u00021 : constant Version_32 := 16#2F1EB794#;
   u00022 : constant Version_32 := 16#31AB6444#;
   u00023 : constant Version_32 := 16#1574B6E9#;
   u00024 : constant Version_32 := 16#5109C189#;
   u00025 : constant Version_32 := 16#56D770CD#;
   u00026 : constant Version_32 := 16#02F9DE3D#;
   u00027 : constant Version_32 := 16#08AB6B2C#;
   u00028 : constant Version_32 := 16#3FA37670#;
   u00029 : constant Version_32 := 16#476457A0#;
   u00030 : constant Version_32 := 16#731E1B6E#;
   u00031 : constant Version_32 := 16#23C2E789#;
   u00032 : constant Version_32 := 16#0F1BD6A1#;
   u00033 : constant Version_32 := 16#7C25DE96#;
   u00034 : constant Version_32 := 16#39ADFFA2#;
   u00035 : constant Version_32 := 16#571DE3E7#;
   u00036 : constant Version_32 := 16#5EB646AB#;
   u00037 : constant Version_32 := 16#4249379B#;
   u00038 : constant Version_32 := 16#0357E00A#;
   u00039 : constant Version_32 := 16#3784FB72#;
   u00040 : constant Version_32 := 16#2E723019#;
   u00041 : constant Version_32 := 16#623358EA#;
   u00042 : constant Version_32 := 16#107F9465#;
   u00043 : constant Version_32 := 16#6843F68A#;
   u00044 : constant Version_32 := 16#63305874#;
   u00045 : constant Version_32 := 16#31E56CE1#;
   u00046 : constant Version_32 := 16#02917970#;
   u00047 : constant Version_32 := 16#6CCBA70E#;
   u00048 : constant Version_32 := 16#41CD4204#;
   u00049 : constant Version_32 := 16#572E3F58#;
   u00050 : constant Version_32 := 16#20729FF5#;
   u00051 : constant Version_32 := 16#1D4F93E8#;
   u00052 : constant Version_32 := 16#30B2EC3D#;
   u00053 : constant Version_32 := 16#34054F96#;
   u00054 : constant Version_32 := 16#5A199860#;
   u00055 : constant Version_32 := 16#0E7F912B#;
   u00056 : constant Version_32 := 16#5760634A#;
   u00057 : constant Version_32 := 16#5D851835#;

   --  The following Export pragmas export the version numbers
   --  with symbolic names ending in B (for body) or S
   --  (for spec) so that they can be located in a link. The
   --  information provided here is sufficient to track down
   --  the exact versions of units used in a given build.

   pragma Export (C, u00001, "helloB");
   pragma Export (C, u00002, "system__standard_libraryB");
   pragma Export (C, u00003, "system__standard_libraryS");
   pragma Export (C, u00004, "adaS");
   pragma Export (C, u00005, "ada__text_ioB");
   pragma Export (C, u00006, "ada__text_ioS");
   pragma Export (C, u00007, "ada__exceptionsB");
   pragma Export (C, u00008, "ada__exceptionsS");
   pragma Export (C, u00009, "gnatS");
   pragma Export (C, u00010, "gnat__heap_sort_aB");
   pragma Export (C, u00011, "gnat__heap_sort_aS");
   pragma Export (C, u00012, "systemS");
   pragma Export (C, u00013, "system__exception_tableB");
   pragma Export (C, u00014, "system__exception_tableS");
   pragma Export (C, u00015, "gnat__htableB");
   pragma Export (C, u00016, "gnat__htableS");
   pragma Export (C, u00017, "system__exceptionsS");
   pragma Export (C, u00018, "system__machine_state_operationsB");
   pragma Export (C, u00019, "system__machine_state_operationsS");
   pragma Export (C, u00020, "system__machine_codeS");
   pragma Export (C, u00021, "system__storage_elementsB");
   pragma Export (C, u00022, "system__storage_elementsS");
   pragma Export (C, u00023, "system__secondary_stackB");
   pragma Export (C, u00024, "system__secondary_stackS");
   pragma Export (C, u00025, "system__parametersB");
   pragma Export (C, u00026, "system__parametersS");
   pragma Export (C, u00027, "system__soft_linksB");
   pragma Export (C, u00028, "system__soft_linksS");
   pragma Export (C, u00029, "system__stack_checkingB");
   pragma Export (C, u00030, "system__stack_checkingS");
   pragma Export (C, u00031, "system__tracebackB");
   pragma Export (C, u00032, "system__tracebackS");
   pragma Export (C, u00033, "ada__streamsS");
   pragma Export (C, u00034, "ada__tagsB");
   pragma Export (C, u00035, "ada__tagsS");
   pragma Export (C, u00036, "system__string_opsB");
   pragma Export (C, u00037, "system__string_opsS");
   pragma Export (C, u00038, "interfacesS");
   pragma Export (C, u00039, "interfaces__c_streamsB");
   pragma Export (C, u00040, "interfaces__c_streamsS");
   pragma Export (C, u00041, "system__file_ioB");
   pragma Export (C, u00042, "system__file_ioS");
   pragma Export (C, u00043, "ada__finalizationB");
   pragma Export (C, u00044, "ada__finalizationS");
   pragma Export (C, u00045, "system__finalization_rootB");
   pragma Export (C, u00046, "system__finalization_rootS");
   pragma Export (C, u00047, "system__finalization_implementationB");
   pragma Export (C, u00048, "system__finalization_implementationS");
   pragma Export (C, u00049, "system__string_ops_concat_3B");
   pragma Export (C, u00050, "system__string_ops_concat_3S");
   pragma Export (C, u00051, "system__stream_attributesB");
   pragma Export (C, u00052, "system__stream_attributesS");
   pragma Export (C, u00053, "ada__io_exceptionsS");
   pragma Export (C, u00054, "system__unsigned_typesS");
   pragma Export (C, u00055, "system__file_control_blockS");
   pragma Export (C, u00056, "ada__finalization__list_controllerB");
   pragma Export (C, u00057, "ada__finalization__list_controllerS");

   -- ada (spec)
   -- gnat (spec)
   -- gnat.heap_sort_a (spec)
   -- gnat.heap_sort_a (body)
   -- gnat.htable (spec)
   -- gnat.htable (body)
   -- interfaces (spec)
   -- system (spec)
   -- system.machine_code (spec)
   -- system.parameters (spec)
   -- system.parameters (body)
   -- interfaces.c_streams (spec)
   -- interfaces.c_streams (body)
   -- system.standard_library (spec)
   -- ada.exceptions (spec)
   -- system.exception_table (spec)
   -- system.exception_table (body)
   -- ada.io_exceptions (spec)
   -- system.exceptions (spec)
   -- system.storage_elements (spec)
   -- system.storage_elements (body)
   -- system.machine_state_operations (spec)
   -- system.machine_state_operations (body)
   -- system.secondary_stack (spec)
   -- system.stack_checking (spec)
   -- system.soft_links (spec)
   -- system.soft_links (body)
   -- system.stack_checking (body)
   -- system.secondary_stack (body)
   -- system.standard_library (body)
   -- system.string_ops (spec)
   -- system.string_ops (body)
   -- ada.tags (spec)
   -- ada.tags (body)
   -- ada.streams (spec)
   -- system.finalization_root (spec)
   -- system.finalization_root (body)
   -- system.string_ops_concat_3 (spec)
   -- system.string_ops_concat_3 (body)
   -- system.traceback (spec)
   -- system.traceback (body)
   -- ada.exceptions (body)
   -- system.unsigned_types (spec)
   -- system.stream_attributes (spec)
   -- system.stream_attributes (body)
   -- system.finalization_implementation (spec)
   -- system.finalization_implementation (body)
   -- ada.finalization (spec)
   -- ada.finalization (body)
   -- ada.finalization.list_controller (spec)
   -- ada.finalization.list_controller (body)
   -- system.file_control_block (spec)
   -- system.file_io (spec)
   -- system.file_io (body)
   -- ada.text_io (spec)
   -- ada.text_io (body)
   -- hello (body)

end ada_main;

--  The following source file name pragmas allow the generated file
--  names to be unique for different main programs. They are needed
--  since the package name will always be Ada_Main.

pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");

--  Generated package body for Ada_Main starts here

package body ada_main is

   --  The actual finalization is performed by calling the
   --  library routine in System.Standard_Library.Adafinal

   procedure Do_Finalize;
   pragma Import (C, Do_Finalize, "system__standard_library__adafinal");

   -- adainit --

   procedure adainit is

      --  These booleans are set to True once the associated unit has
      --  been elaborated. It is also used to avoid elaborating the
      --  same unit twice.

      E040 : Boolean; pragma Import (Ada, E040, "interfaces__c_streams_E");
      E008 : Boolean; pragma Import (Ada, E008, "ada__exceptions_E");
      E014 : Boolean; pragma Import (Ada, E014, "system__exception_table_E");
      E053 : Boolean; pragma Import (Ada, E053, "ada__io_exceptions_E");
      E017 : Boolean; pragma Import (Ada, E017, "system__exceptions_E");
      E024 : Boolean; pragma Import (Ada, E024, "system__secondary_stack_E");
      E030 : Boolean; pragma Import (Ada, E030, "system__stack_checking_E");
      E028 : Boolean; pragma Import (Ada, E028, "system__soft_links_E");
      E035 : Boolean; pragma Import (Ada, E035, "ada__tags_E");
      E033 : Boolean; pragma Import (Ada, E033, "ada__streams_E");
      E046 : Boolean; pragma Import (Ada, E046, "system__finalization_root_E");
      E048 : Boolean; pragma Import (Ada, E048, "system__finalization_implementation_E");
      E044 : Boolean; pragma Import (Ada, E044, "ada__finalization_E");
      E057 : Boolean; pragma Import (Ada, E057, "ada__finalization__list_controller_E");
      E055 : Boolean; pragma Import (Ada, E055, "system__file_control_block_E");
      E042 : Boolean; pragma Import (Ada, E042, "system__file_io_E");
      E006 : Boolean; pragma Import (Ada, E006, "ada__text_io_E");

      --  Set_Globals is a library routine that stores away the
      --  value of the indicated set of global values in global
      --  variables within the library.

      procedure Set_Globals
        (Main_Priority            : Integer;
         Time_Slice_Value         : Integer;
         WC_Encoding              : Character;
         Locking_Policy           : Character;
         Queuing_Policy           : Character;
         Task_Dispatching_Policy  : Character;
         Adafinal                 : System.Address;
         Unreserve_All_Interrupts : Integer;
         Exception_Tracebacks     : Integer);
      pragma Import (C, Set_Globals, "__gnat_set_globals");

      --  SDP_Table_Build is a library routine used to build the
      --  exception tables. See unit Ada.Exceptions in files
      --  a-except.ads/adb for full details of how zero cost
      --  exception handling works. This procedure, the call to
      --  it, and the two following tables are all omitted if the
      --  build is in longjmp/setjump exception mode.

      procedure SDP_Table_Build
        (SDP_Addresses   : System.Address;
         SDP_Count       : Natural;
         Elab_Addresses  : System.Address;
         Elab_Addr_Count : Natural);
      pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build");

      --  Table of Unit_Exception_Table addresses. Used for zero
      --  cost exception handling to build the top level table.

      ST : aliased constant array (1 .. 23) of System.Address := (

      --  Table of addresses of elaboration routines. Used for
      --  zero cost exception handling to make sure these
      --  addresses are included in the top level procedure
      --  address table.

      EA : aliased constant array (1 .. 23) of System.Address := (

   --  Start of processing for adainit


      --  Call SDP_Table_Build to build the top level procedure
      --  table for zero cost exception handling (omitted in
      --  longjmp/setjump mode).

      SDP_Table_Build (ST'Address, 23, EA'Address, 23);

      --  Call Set_Globals to record various information for
      --  this partition.  The values are derived by the binder
      --  from information stored in the ali files by the compiler.

        (Main_Priority            => -1,
         --  Priority of main program, -1 if no pragma Priority used

         Time_Slice_Value         => -1,
         --  Time slice from Time_Slice pragma, -1 if none used

         WC_Encoding              => 'b',
         --  Wide_Character encoding used, default is brackets

         Locking_Policy           => ' ',
         --  Locking_Policy used, default of space means not
         --  specified, otherwise it is the first character of
         --  the policy name.

         Queuing_Policy           => ' ',
         --  Queuing_Policy used, default of space means not
         --  specified, otherwise it is the first character of
         --  the policy name.

         Task_Dispatching_Policy  => ' ',
         --  Task_Dispatching_Policy used, default of space means
         --  not specified, otherwise first character of the
         --  policy name.

         Adafinal                 => System.Null_Address,
         --  Address of Adafinal routine, not used anymore

         Unreserve_All_Interrupts => 0,
         --  Set true if pragma Unreserve_All_Interrupts was used

         Exception_Tracebacks     => 0);
         --  Indicates if exception tracebacks are enabled

      Elab_Final_Code := 1;

      --  Now we have the elaboration calls for all units in the partition.
      --  The Elab_Spec and Elab_Body attributes generate references to the
      --  implicit elaboration procedures generated by the compiler for
      --  each unit that requires elaboration.

      if not E040 then
      end if;
      E040 := True;
      if not E008 then
      end if;
      if not E014 then
         E014 := True;
      end if;
      if not E053 then
         E053 := True;
      end if;
      if not E017 then
         E017 := True;
      end if;
      if not E030 then
      end if;
      if not E028 then
         E028 := True;
      end if;
      E030 := True;
      if not E024 then
         E024 := True;
      end if;
      if not E035 then
      end if;
      if not E035 then
         E035 := True;
      end if;
      if not E033 then
         E033 := True;
      end if;
      if not E046 then
      end if;
      E046 := True;
      if not E008 then
         E008 := True;
      end if;
      if not E048 then
      end if;
      if not E048 then
         E048 := True;
      end if;
      if not E044 then
      end if;
      E044 := True;
      if not E057 then
      end if;
      E057 := True;
      if not E055 then
         E055 := True;
      end if;
      if not E042 then
         E042 := True;
      end if;
      if not E006 then
      end if;
      if not E006 then
         E006 := True;
      end if;

      Elab_Final_Code := 0;
   end adainit;

   -- adafinal --

   procedure adafinal is
   end adafinal;

   -- main --

   --  main is actually a function, as in the ANSI C standard,
   --  defined to return the exit status. The three parameters
   --  are the argument count, argument values and environment
   --  pointer.

   function main
     (argc : Integer;
      argv : System.Address;
      envp : System.Address)
      return Integer
      --  The initialize routine performs low level system
      --  initialization using a standard library routine which
      --  sets up signal handling and performs any other
      --  required setup. The routine can be found in file
      --  a-init.c.

      procedure initialize;
      pragma Import (C, initialize, "__gnat_initialize");

      --  The finalize routine performs low level system
      --  finalization using a standard library routine. The
      --  routine is found in file a-final.c and in the standard
      --  distribution is a dummy routine that does nothing, so
      --  really this is a hook for special user finalization.

      procedure finalize;
      pragma Import (C, finalize, "__gnat_finalize");

      --  We get to the main program of the partition by using
      --  pragma Import because if we try to with the unit and
      --  call it Ada style, then not only do we waste time
      --  recompiling it, but also, we don't really know the right
      --  switches (e.g. identifier character set) to be used
      --  to compile it.

      procedure Ada_Main_Program;
      pragma Import (Ada, Ada_Main_Program, "_ada_hello");

   --  Start of processing for main

      --  Save global variables

      gnat_argc := argc;
      gnat_argv := argv;
      gnat_envp := envp;

      --  Call low level system initialization


      --  Call our generated Ada initialization routine


      --  This is the point at which we want the debugger to get
      --  control


      --  Now we call the main program of the partition


      --  Perform Ada finalization


      --  Perform low level system finalization


      --  Return the proper exit status
      return (gnat_exit_status);

--  This section is entirely comments, so it has no effect on the
--  compilation of the Ada_Main package. It provides the list of
--  object files and linker options, as well as some standard
--  libraries needed for the link. The gnatlink utility parses
--  this b~hello.adb file to read these comment lines to generate
--  the appropriate command line arguments for the call to the
--  system linker. The BEGIN/END lines are used for sentinels for
--  this parsing operation.

--  The exact file names will of course depend on the environment,
--  host/target and location of files on the host system.

-- BEGIN Object file/option list
   --   ./hello.o
   --   -L./
   --   -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
   --   /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
-- END Object file/option list

end ada_main;

The Ada code in the above example is exactly what is generated by the binder. We have added comments to more clearly indicate the function of each part of the generated Ada_Main package.

The code is standard Ada in all respects, and can be processed by any tools that handle Ada. In particular, it is possible to use the debugger in Ada mode to debug the generated Ada_Main package. For example, suppose that for reasons that you do not understand, your program is blowing up during elaboration of the body of Ada.Text_IO. To chase this bug down, you can place a breakpoint on the call:


and trace the elaboration routine for this package to find out where the problem might be (more usually of course you would be debugging elaboration code in your own application).

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003