gcc/ada/make.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                 M A K E                                  --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-2001 Free Software Foundation, Inc.          --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  19 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  20 -- MA 02111-1307, USA.                                                      --
  21 --                                                                          --
  22 -- GNAT was originally developed  by the GNAT team at  New York University. --
  23 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  24 --                                                                          --
  25 ------------------------------------------------------------------------------
  26
  27 --  The following package implements the facilities to recursively
  28 --  compile (a la make), bind and/or link a set of sources. This package
  29 --  gives the individual routines for performing such tasks as well as
  30 --  the routine gnatmake below that puts it all together.
  31
  32 with GNAT.OS_Lib; use GNAT.OS_Lib;  --  defines Argument_List
  33 with Table;
  34 with Types;       use Types;
  35
  36 package Make is
  37
  38    --  The 3 following packages are used to store gcc, gnatbind and gnatbl
  39    --  switches passed on the gnatmake or gnatdist command line.
  40    --  Note that the lower bounds definitely need to be 1 to match the
  41    --  requirement that the argument array prepared for Spawn must have
  42    --  a lower bound of 1.
  43
  44    package Gcc_Switches is new Table.Table (
  45      Table_Component_Type => String_Access,
  46      Table_Index_Type     => Integer,
  47      Table_Low_Bound      => 1,
  48      Table_Initial        => 20,
  49      Table_Increment      => 100,
  50      Table_Name           => "Make.Gcc_Switches");
  51
  52    package Binder_Switches is new Table.Table (
  53      Table_Component_Type => String_Access,
  54      Table_Index_Type     => Integer,
  55      Table_Low_Bound      => 1,
  56      Table_Initial        => 20,
  57      Table_Increment      => 100,
  58      Table_Name           => "Make.Binder_Switches");
  59
  60    package Linker_Switches is new Table.Table (
  61      Table_Component_Type => String_Access,
  62      Table_Index_Type     => Integer,
  63      Table_Low_Bound      => 1,
  64      Table_Initial        => 20,
  65      Table_Increment      => 100,
  66      Table_Name           => "Make.Linker_Switches");
  67
  68    procedure Display_Commands (Display : Boolean := True);
  69    --  The default behavior of Make commands (Compile_Sources, Bind, Link)
  70    --  is to display them on stderr. This behavior can be changed repeatedly
  71    --  by invoking this procedure.
  72
  73    --  If a compilation, bind or link failed one of the following 3 exceptions
  74    --  is raised. These need to be handled by the calling routines.
  75
  76    Compilation_Failed : exception;
  77    --  Raised by Compile_Sources if a compilation failed.
  78
  79    Bind_Failed : exception;
  80    --  Raised by Bind below if the bind failed.
  81
  82    Link_Failed : exception;
  83    --  Raised by Link below if the link failed.
  84
  85    procedure Bind (ALI_File : File_Name_Type; Args : Argument_List);
  86    --  Binds ALI_File. Args are the arguments to pass to the binder.
  87    --  Args must have a lower bound of 1.
  88
  89    procedure Link (ALI_File : File_Name_Type; Args : Argument_List);
  90    --  Links ALI_File. Args are the arguments to pass to the linker.
  91    --  Args must have a lower bound of 1.
  92
  93    procedure Initialize;
  94    --  Performs default and package initialization. Therefore,
  95    --  Compile_Sources can be called by an external unit.
  96
  97    procedure Scan_Make_Arg (Argv : String; And_Save : Boolean);
  98    --  Scan make arguments. Argv is a single argument to be processed.
  99
 100    procedure Extract_Failure
 101      (File  : out File_Name_Type;
 102       Unit  : out Unit_Name_Type;
 103       Found : out Boolean);
 104    --  Extracts the first failure report from Bad_Compilation table.
 105
 106    procedure Compile_Sources
 107      (Main_Source           : File_Name_Type;
 108       Args                  : Argument_List;
 109       First_Compiled_File   : out Name_Id;
 110       Most_Recent_Obj_File  : out Name_Id;
 111       Most_Recent_Obj_Stamp : out Time_Stamp_Type;
 112       Main_Unit             : out Boolean;
 113       Compilation_Failures  : out Natural;
 114       Check_Readonly_Files  : Boolean  := False;
 115       Do_Not_Execute        : Boolean  := False;
 116       Force_Compilations    : Boolean  := False;
 117       Keep_Going            : Boolean  := False;
 118       In_Place_Mode         : Boolean  := False;
 119       Initialize_ALI_Data   : Boolean  := True;
 120       Max_Process           : Positive := 1);
 121    --  Compile_Sources will recursively compile all the sources needed by
 122    --  Main_Source. Before calling this routine make sure Namet has been
 123    --  initialized. This routine can be called repeatedly with different
 124    --  Main_Source file as long as all the source (-I flags), library
 125    --  (-B flags) and ada library (-A flags) search paths between calls are
 126    --  *exactly* the same. The default directory must also be the same.
 127    --
 128    --    Args contains the arguments to use during the compilations.
 129    --    The lower bound of Args must be 1.
 130    --
 131    --    First_Compiled_File is set to the name of the first file that is
 132    --    compiled or that needs to be compiled. This is set to No_Name if no
 133    --    compilations were needed.
 134    --
 135    --    Most_Recent_Obj_File is set to the full name of the most recent
 136    --    object file found when no compilations are needed, that is when
 137    --    First_Compiled_File is set to No_Name. When First_Compiled_File
 138    --    is set then Most_Recent_Obj_File is set to No_Name.
 139    --
 140    --    Most_Recent_Obj_Stamp is the time stamp of Most_Recent_Obj_File.
 141    --
 142    --    Main_Unit is set to True if Main_Source can be a main unit.
 143    --    If Do_Not_Execute is False and First_Compiled_File /= No_Name
 144    --    the value of Main_Unit is always False.
 145    --    Is this used any more??? It is certainly not used by gnatmake???
 146    --
 147    --    Compilation_Failures is a count of compilation failures. This count
 148    --    is used to extract compilation failure reports with Extract_Failure.
 149    --
 150    --    Check_Readonly_Files set it to True to compile source files
 151    --    which library files are read-only. When compiling GNAT predefined
 152    --    files the "-gnatg" flag is used.
 153    --
 154    --    Do_Not_Execute set it to True to find out the first source that
 155    --    needs to be recompiled, but without recompiling it. This file is
 156    --    saved in First_Compiled_File.
 157    --
 158    --    Force_Compilations forces all compilations no matter what but
 159    --    recompiles read-only files only if Check_Readonly_Files
 160    --    is set.
 161    --
 162    --    Keep_Going when True keep compiling even in the presence of
 163    --    compilation errors.
 164    --
 165    --    In_Place_Mode when True save library/object files in their object
 166    --    directory if they already exist; otherwise, in the source directory.
 167    --
 168    --    Initialize_ALI_Data set it to True when you want to initialize ALI
 169    --    data-structures. This is what you should do most of the time.
 170    --    (especially the first time around when you call this routine).
 171    --    This parameter is set to False to preserve previously recorded
 172    --    ALI file data.
 173    --
 174    --    Max_Process is the maximum number of processes that should be spawned
 175    --    to carry out compilations.
 176    --
 177    --  Flags in Package Opt Affecting Compile_Sources
 178    --  -----------------------------------------------
 179    --
 180    --    Check_Object_Consistency set it to False to omit all consistency
 181    --      checks between an .ali file and its corresponding object file.
 182    --      When this flag is set to true, every time an .ali is read,
 183    --      package Osint checks that the corresponding object file
 184    --      exists and is more recent than the .ali.
 185    --
 186    --  Use of Name Table Info
 187    --  ----------------------
 188    --
 189    --  All file names manipulated by Compile_Sources are entered into the
 190    --  Names table. The Byte field of a source file is used to mark it.
 191    --
 192    --  Calling Compile_Sources Several Times
 193    --  -------------------------------------
 194    --
 195    --  Upon return from Compile_Sources all the ALI data structures are left
 196    --  intact for further browsing. HOWEVER upon entry to this routine ALI
 197    --  data structures are re-initialized if parameter Initialize_ALI_Data
 198    --  above is set to true. Typically this is what you want the first time
 199    --  you call Compile_Sources. You should not load an ali file, call this
 200    --  routine with flag Initialize_ALI_Data set to True and then expect
 201    --  that ALI information to be around after the call. Note that the first
 202    --  time you call Compile_Sources you better set Initialize_ALI_Data to
 203    --  True unless you have called Initialize_ALI yourself.
 204    --
 205    --  Compile_Sources ALGORITHM : Compile_Sources (Main_Source)
 206    --  -------------------------
 207    --
 208    --  1. Insert Main_Source in a Queue (Q) and mark it.
 209    --
 210    --  2. Let unit.adb be the file at the head of the Q. If unit.adb is
 211    --     missing but its corresponding ali file is in an Ada library directory
 212    --     (see below) then, remove unit.adb from the Q and goto step 4.
 213    --     Otherwise, look at the files under the D (dependency) section of
 214    --     unit.ali. If unit.ali does not exist or some of the time stamps do
 215    --     not match, (re)compile unit.adb.
 216    --
 217    --     An Ada library directory is a directory containing Ada specs, ali
 218    --     and object files but no source files for the bodies. An Ada library
 219    --     directory is communicated to gnatmake by means of some switch so that
 220    --     gnatmake can skip the sources whole ali are in that directory.
 221    --     There are two reasons for skipping the sources in this case. Firstly,
 222    --     Ada libraries typically come without full sources but binding and
 223    --     linking against those libraries is still possible. Secondly, it would
 224    --     be very wasteful for gnatmake to systematically check the consistency
 225    --     of every external Ada library used in a program. The binder is
 226    --     already in charge of catching any potential inconsistencies.
 227    --
 228    --  3. Look into the W section of unit.ali and insert into the Q all
 229    --     unmarked source files. Mark all files newly inserted in the Q.
 230    --     Specifically, assuming that the W section looks like
 231    --
 232    --     W types%s               types.adb               types.ali
 233    --     W unchecked_deallocation%s
 234    --     W xref_tab%s            xref_tab.adb            xref_tab.ali
 235    --
 236    --     Then xref_tab.adb and types.adb are inserted in the Q if they are not
 237    --     already marked.
 238    --     Note that there is no file listed under W unchecked_deallocation%s
 239    --     so no generic body should ever be explicitly compiled (unless the
 240    --     Main_Source at the start was a generic body).
 241    --
 242    --  4. Repeat steps 2 and 3 above until the Q is empty
 243    --
 244    --  Note that the above algorithm works because the units withed in
 245    --  subunits are transitively included in the W section (with section) of
 246    --  the main unit. Likewise the withed units in a generic body needed
 247    --  during a compilation are also transitively included in the W section
 248    --  of the originally compiled file.
 249
 250    procedure Gnatmake;
 251    --  The driver of gnatmake. This routine puts it all together.
 252    --  This utility can be used to automatically (re)compile (using
 253    --  Compile_Sources), bind (using Bind) and link (using Link) a set of
 254    --  ada sources. For more information on gnatmake and its precise usage
 255    --  please refer to the gnat documentation.
 256    --
 257    --  Flags in Package Opt Affecting Gnatmake
 258    --  ---------------------------------------
 259    --
 260    --    Check_Readonly_Files:     True  when -a present in command line
 261    --    Check_Object_Consistency: Set to True by Gnatmake
 262    --    Compile_Only:             True  when -c present in command line
 263    --    Force_Compilations:       True  when -f present in command line
 264    --    Maximum_Processes:        Number of processes given by -jnum
 265    --    Keep_Going:               True  when -k present in command line
 266    --    List_Dependencies:        True  when -l present in command line
 267    --    Do_Not_Execute            True  when -n present in command line
 268    --    Quiet_Output:             True  when -q present in command line
 269    --    Minimal_Recompilation:    True  when -m present in command line
 270    --    Verbose_Mode:             True  when -v present in command line
 271
 272 end Make;