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-2003 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 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       Check_Readonly_Files  : Boolean  := False;
 116       Do_Not_Execute        : Boolean  := False;
 117       Force_Compilations    : Boolean  := False;
 118       Keep_Going            : Boolean  := False;
 119       In_Place_Mode         : Boolean  := False;
 120       Initialize_ALI_Data   : Boolean  := True;
 121       Max_Process           : Positive := 1);
 122    --  Compile_Sources will recursively compile all the sources needed by
 123    --  Main_Source. Before calling this routine make sure Namet has been
 124    --  initialized. This routine can be called repeatedly with different
 125    --  Main_Source file as long as all the source (-I flags), library
 126    --  (-B flags) and ada library (-A flags) search paths between calls are
 127    --  *exactly* the same. The default directory must also be the same.
 128    --
 129    --    Args contains the arguments to use during the compilations.
 130    --    The lower bound of Args must be 1.
 131    --
 132    --    First_Compiled_File is set to the name of the first file that is
 133    --    compiled or that needs to be compiled. This is set to No_Name if no
 134    --    compilations were needed.
 135    --
 136    --    Most_Recent_Obj_File is set to the full name of the most recent
 137    --    object file found when no compilations are needed, that is when
 138    --    First_Compiled_File is set to No_Name. When First_Compiled_File
 139    --    is set then Most_Recent_Obj_File is set to No_Name.
 140    --
 141    --    Most_Recent_Obj_Stamp is the time stamp of Most_Recent_Obj_File.
 142    --
 143    --    Main_Unit is set to True if Main_Source can be a main unit.
 144    --    If Do_Not_Execute is False and First_Compiled_File /= No_Name
 145    --    the value of Main_Unit is always False.
 146    --    Is this used any more??? It is certainly not used by gnatmake???
 147    --
 148    --    Compilation_Failures is a count of compilation failures. This count
 149    --    is used to extract compilation failure reports with Extract_Failure.
 150    --
 151    --    Check_Readonly_Files set it to True to compile source files
 152    --    which library files are read-only. When compiling GNAT predefined
 153    --    files the "-gnatg" flag is used.
 154    --
 155    --    Do_Not_Execute set it to True to find out the first source that
 156    --    needs to be recompiled, but without recompiling it. This file is
 157    --    saved in First_Compiled_File.
 158    --
 159    --    Force_Compilations forces all compilations no matter what but
 160    --    recompiles read-only files only if Check_Readonly_Files
 161    --    is set.
 162    --
 163    --    Keep_Going when True keep compiling even in the presence of
 164    --    compilation errors.
 165    --
 166    --    In_Place_Mode when True save library/object files in their object
 167    --    directory if they already exist; otherwise, in the source directory.
 168    --
 169    --    Initialize_ALI_Data set it to True when you want to initialize ALI
 170    --    data-structures. This is what you should do most of the time.
 171    --    (especially the first time around when you call this routine).
 172    --    This parameter is set to False to preserve previously recorded
 173    --    ALI file data.
 174    --
 175    --    Max_Process is the maximum number of processes that should be spawned
 176    --    to carry out compilations.
 177    --
 178    --  Flags in Package Opt Affecting Compile_Sources
 179    --  -----------------------------------------------
 180    --
 181    --    Check_Object_Consistency set it to False to omit all consistency
 182    --      checks between an .ali file and its corresponding object file.
 183    --      When this flag is set to true, every time an .ali is read,
 184    --      package Osint checks that the corresponding object file
 185    --      exists and is more recent than the .ali.
 186    --
 187    --  Use of Name Table Info
 188    --  ----------------------
 189    --
 190    --  All file names manipulated by Compile_Sources are entered into the
 191    --  Names table. The Byte field of a source file is used to mark it.
 192    --
 193    --  Calling Compile_Sources Several Times
 194    --  -------------------------------------
 195    --
 196    --  Upon return from Compile_Sources all the ALI data structures are left
 197    --  intact for further browsing. HOWEVER upon entry to this routine ALI
 198    --  data structures are re-initialized if parameter Initialize_ALI_Data
 199    --  above is set to true. Typically this is what you want the first time
 200    --  you call Compile_Sources. You should not load an ali file, call this
 201    --  routine with flag Initialize_ALI_Data set to True and then expect
 202    --  that ALI information to be around after the call. Note that the first
 203    --  time you call Compile_Sources you better set Initialize_ALI_Data to
 204    --  True unless you have called Initialize_ALI yourself.
 205    --
 206    --  Compile_Sources ALGORITHM : Compile_Sources (Main_Source)
 207    --  -------------------------
 208    --
 209    --  1. Insert Main_Source in a Queue (Q) and mark it.
 210    --
 211    --  2. Let unit.adb be the file at the head of the Q. If unit.adb is
 212    --     missing but its corresponding ali file is in an Ada library directory
 213    --     (see below) then, remove unit.adb from the Q and goto step 4.
 214    --     Otherwise, look at the files under the D (dependency) section of
 215    --     unit.ali. If unit.ali does not exist or some of the time stamps do
 216    --     not match, (re)compile unit.adb.
 217    --
 218    --     An Ada library directory is a directory containing Ada specs, ali
 219    --     and object files but no source files for the bodies. An Ada library
 220    --     directory is communicated to gnatmake by means of some switch so that
 221    --     gnatmake can skip the sources whole ali are in that directory.
 222    --     There are two reasons for skipping the sources in this case. Firstly,
 223    --     Ada libraries typically come without full sources but binding and
 224    --     linking against those libraries is still possible. Secondly, it would
 225    --     be very wasteful for gnatmake to systematically check the consistency
 226    --     of every external Ada library used in a program. The binder is
 227    --     already in charge of catching any potential inconsistencies.
 228    --
 229    --  3. Look into the W section of unit.ali and insert into the Q all
 230    --     unmarked source files. Mark all files newly inserted in the Q.
 231    --     Specifically, assuming that the W section looks like
 232    --
 233    --     W types%s               types.adb               types.ali
 234    --     W unchecked_deallocation%s
 235    --     W xref_tab%s            xref_tab.adb            xref_tab.ali
 236    --
 237    --     Then xref_tab.adb and types.adb are inserted in the Q if they are not
 238    --     already marked.
 239    --     Note that there is no file listed under W unchecked_deallocation%s
 240    --     so no generic body should ever be explicitly compiled (unless the
 241    --     Main_Source at the start was a generic body).
 242    --
 243    --  4. Repeat steps 2 and 3 above until the Q is empty
 244    --
 245    --  Note that the above algorithm works because the units withed in
 246    --  subunits are transitively included in the W section (with section) of
 247    --  the main unit. Likewise the withed units in a generic body needed
 248    --  during a compilation are also transitively included in the W section
 249    --  of the originally compiled file.
 250
 251    procedure Gnatmake;
 252    --  The driver of gnatmake. This routine puts it all together.
 253    --  This utility can be used to automatically (re)compile (using
 254    --  Compile_Sources), bind (using Bind) and link (using Link) a set of
 255    --  ada sources. For more information on gnatmake and its precise usage
 256    --  please refer to the gnat documentation.
 257    --
 258    --  Flags in Package Opt Affecting Gnatmake
 259    --  ---------------------------------------
 260    --
 261    --    Check_Readonly_Files:     True  when -a present in command line
 262    --    Check_Object_Consistency: Set to True by Gnatmake
 263    --    Compile_Only:             True  when -c present in command line
 264    --    Force_Compilations:       True  when -f present in command line
 265    --    Maximum_Processes:        Number of processes given by -jnum
 266    --    Keep_Going:               True  when -k present in command line
 267    --    List_Dependencies:        True  when -l present in command line
 268    --    Do_Not_Execute            True  when -n present in command line
 269    --    Quiet_Output:             True  when -q present in command line
 270    --    Minimal_Recompilation:    True  when -m present in command line
 271    --    Verbose_Mode:             True  when -v present in command line
 272
 273 end Make;