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