gcc/ada/prj-conf.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                              P R J . C O N F                             --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --            Copyright (C) 2006-2017, 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 3,  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 COPYING3.  If not, go to --
  19 -- http://www.gnu.org/licenses for a complete copy of the license.          --
  20 --                                                                          --
  21 -- GNAT was originally developed  by the GNAT team at  New York University. --
  22 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  23 --                                                                          --
  24 ------------------------------------------------------------------------------
  25
  26 --  The following package manipulates the configuration files
  27
  28 with Prj.Tree;
  29 with Prj.Proc;
  30
  31 package Prj.Conf is
  32
  33    type Config_File_Hook is access procedure
  34      (Config_File       : in out Prj.Tree.Project_Node_Id;
  35       Project_Node_Tree : Prj.Tree.Project_Node_Tree_Ref);
  36    --  Hook called after the config file has been parsed. This lets the
  37    --  application do last minute changes to it (GPS uses this to add the
  38    --  default naming schemes for instance). At that point, the config file
  39    --  has not been applied to the project yet. When no config file was found,
  40    --  and automatic generation is disabled, it is possible that Config_File
  41    --  is set to Empty_Node when this procedure is called. You can then decide
  42    --  to create a new config file if you need.
  43
  44    No_Configuration_File : constant String := "/";
  45    --  When specified as a parameter Config_File_Name in the procedures below,
  46    --  no existing configuration project file is parsed. This is used by
  47    --  gnatmake, gnatclean and the GNAT driver to avoid parsing an existing
  48    --  default configuration project file.
  49
  50    procedure Parse_Project_And_Apply_Config
  51      (Main_Project               : out Prj.Project_Id;
  52       User_Project_Node          : out Prj.Tree.Project_Node_Id;
  53       Config_File_Name           : String                        := "";
  54       Autoconf_Specified         : Boolean;
  55       Project_File_Name          : String;
  56       Project_Tree               : Prj.Project_Tree_Ref;
  57       Project_Node_Tree          : Prj.Tree.Project_Node_Tree_Ref;
  58       Env                        : in out Prj.Tree.Environment;
  59       Packages_To_Check          : String_List_Access;
  60       Allow_Automatic_Generation : Boolean                       := True;
  61       Automatically_Generated    : out Boolean;
  62       Config_File_Path           : out String_Access;
  63       Target_Name                : String                        := "";
  64       Normalized_Hostname        : String;
  65       On_Load_Config             : Config_File_Hook              := null;
  66       Implicit_Project           : Boolean                       := False;
  67       On_New_Tree_Loaded         : Prj.Proc.Tree_Loaded_Callback := null);
  68    --  Find the main configuration project and parse the project tree rooted at
  69    --  this configuration project.
  70    --
  71    --  Project_Node_Tree must have been initialized first (and possibly the
  72    --  value for external references and project path should also have been
  73    --  set).
  74    --
  75    --  If the processing fails, Main_Project is set to No_Project. If the error
  76    --  happened while parsing the project itself (i.e. creating the tree),
  77    --  User_Project_Node is also set to Empty_Node.
  78    --
  79    --  If Config_File_Name is No_Configuration_File, then no configuration
  80    --  project file is parsed. Normally, in this case On_Load_Config is not
  81    --  null, and it is used to create a configuration project file in memory.
  82    --
  83    --  Autoconf_Specified indicates whether the user has specified --autoconf.
  84    --  If this is the case, the config file might be (re)generated, as
  85    --  appropriate, to match languages and target if the one specified doesn't
  86    --  already match.
  87    --
  88    --  Normalized_Hostname is the host on which gprbuild is returned,
  89    --  normalized so that we can more easily compare it with what is stored in
  90    --  configuration files. It is used when the target is unspecified, although
  91    --  we need to know the target specified by the user (Target_Name) when
  92    --  computing the name of the default config file that should be used.
  93    --
  94    --  If specified, On_Load_Config is called just after the config file has
  95    --  been created/loaded. You can then modify it before it is later applied
  96    --  to the project itself.
  97    --
  98    --  Any error in generating or parsing the config file is reported via the
  99    --  Invalid_Config exception, with an appropriate message. Any error while
 100    --  parsing the project file results in No_Project.
 101    --
 102    --  If Implicit_Project is True, the main project file being parsed is
 103    --  deemed to be in the current working directory, even if it is not the
 104    --  case. Implicit_Project is set to True when a tool such as gprbuild is
 105    --  invoked without a project file and is using an implicit project file
 106    --  that is virtually in the current working directory, but is physically
 107    --  in another directory.
 108    --
 109    --  If specified, On_New_Tree_Loaded is called after each aggregated project
 110    --  has been processed successfully.
 111
 112    procedure Process_Project_And_Apply_Config
 113      (Main_Project               : out Prj.Project_Id;
 114       User_Project_Node          : Prj.Tree.Project_Node_Id;
 115       Config_File_Name           : String                        := "";
 116       Autoconf_Specified         : Boolean;
 117       Project_Tree               : Prj.Project_Tree_Ref;
 118       Project_Node_Tree          : Prj.Tree.Project_Node_Tree_Ref;
 119       Env                        : in out Prj.Tree.Environment;
 120       Packages_To_Check          : String_List_Access;
 121       Allow_Automatic_Generation : Boolean                       := True;
 122       Automatically_Generated    : out Boolean;
 123       Config_File_Path           : out String_Access;
 124       Target_Name                : String                        := "";
 125       Normalized_Hostname        : String;
 126       On_Load_Config             : Config_File_Hook              := null;
 127       Reset_Tree                 : Boolean                       := True;
 128       On_New_Tree_Loaded         : Prj.Proc.Tree_Loaded_Callback := null;
 129       Do_Phase_1                 : Boolean                       := True);
 130    --  Same as above, except the project must already have been parsed through
 131    --  Prj.Part.Parse, and only the processing of the project and the
 132    --  configuration is done at this level.
 133    --
 134    --  If Reset_Tree is true, all projects are first removed from the tree.
 135    --  When_No_Sources indicates what should be done when no sources are found
 136    --  for one of the languages of the project.
 137    --
 138    --  If Require_Sources_Other_Lang is true, then all languages must have at
 139    --  least one source file, or an error is reported via When_No_Sources. If
 140    --  it is false, this is only required for Ada (and only if it is a language
 141    --  of the project).
 142    --
 143    --  If Do_Phase_1 is False, then Prj.Proc.Process_Project_Tree_Phase_1
 144    --  should not be called, as it has already been invoked successfully.
 145
 146    Invalid_Config : exception;
 147
 148    procedure Get_Or_Create_Configuration_File
 149      (Project                    : Prj.Project_Id;
 150       Conf_Project               : Project_Id;
 151       Project_Tree               : Prj.Project_Tree_Ref;
 152       Project_Node_Tree          : Prj.Tree.Project_Node_Tree_Ref;
 153       Env                        : in out Prj.Tree.Environment;
 154       Allow_Automatic_Generation : Boolean;
 155       Config_File_Name           : String             := "";
 156       Autoconf_Specified         : Boolean;
 157       Target_Name                : String             := "";
 158       Normalized_Hostname        : String;
 159       Packages_To_Check          : String_List_Access := null;
 160       Config                     : out Prj.Project_Id;
 161       Config_File_Path           : out String_Access;
 162       Automatically_Generated    : out Boolean;
 163       On_Load_Config             : Config_File_Hook   := null);
 164    --  Compute the name of the configuration file that should be used. If no
 165    --  default configuration file is found, a new one will be automatically
 166    --  generated if Allow_Automatic_Generation is true. This configuration
 167    --  project file will be generated in the object directory of project
 168    --  Conf_Project.
 169    --
 170    --  Any error in generating or parsing the config file is reported via the
 171    --  Invalid_Config exception, with an appropriate message.
 172    --
 173    --  On exit, Configuration_Project_Path is never null (if none could be
 174    --  found, Os.Fail was called and the program exited anyway).
 175    --
 176    --  The choice and generation of a configuration file depends on several
 177    --  attributes of the user's project file (given by the Project argument),
 178    --  e.g. list of languages that must be supported. Project must therefore
 179    --  have been partially processed (phase one of the processing only).
 180    --
 181    --  Config_File_Name should be set to the name of the config file specified
 182    --  by the user (either through gprbuild's --config or --autoconf switches).
 183    --  In the latter case, Autoconf_Specified should be set to true to indicate
 184    --  that the configuration file can be regenerated to match target and
 185    --  languages. This name can either be an absolute path, or the base name
 186    --  that will be searched in the default config file directories (which
 187    --  depends on the installation path for the tools).
 188    --
 189    --  Target_Name is used to chose the configuration file that will be used
 190    --  from among several possibilities.
 191    --
 192    --  If a project file could be found, it is automatically parsed and
 193    --  processed (and Packages_To_Check is used to indicate which packages
 194    --  should be processed).
 195
 196    procedure Add_Default_GNAT_Naming_Scheme
 197      (Config_File  : in out Prj.Tree.Project_Node_Id;
 198       Project_Tree : Prj.Tree.Project_Node_Tree_Ref);
 199    --  A hook that will create a new config file (in memory), used for
 200    --  Get_Or_Create_Configuration_File and Process_Project_And_Apply_Config
 201    --  and add the default GNAT naming scheme to it. Nothing is done if the
 202    --  config_file already exists, to avoid overriding what the user might
 203    --  have put in there.
 204
 205    --------------
 206    -- Runtimes --
 207    --------------
 208
 209    procedure Set_Runtime_For (Language : Name_Id; RTS_Name : String);
 210    --  Specifies the runtime to use for a specific language. Most of the time
 211    --  this should be used for Ada, but other languages can also specify their
 212    --  own runtime. This is in general specified via the --RTS command line
 213    --  switch, and results in a specific component passed to gprconfig's
 214    --  --config switch then automatically generating a configuration file.
 215
 216    function Runtime_Name_For (Language : Name_Id) return String;
 217    --  Returns the runtime name for a language. Returns an empty string if no
 218    --  runtime was specified for the language using option --RTS.
 219
 220    function Runtime_Name_Set_For (Language : Name_Id) return Boolean;
 221    --  Returns True only if Set_Runtime_For has been called for the Language
 222
 223 end Prj.Conf;