6.4. Helper packages
6.4.1. Libadalang.Helpers
This package provides various helpers to build applications based on Libadalang.
- package Unit_Vectors is new Ada.Containers.Vectors
package Unit_Vectors is new Ada.Containers.Vectors (Positive, Analysis_Unit);
- Instantiated generic package:
- procedure Load_Project (Project_File : Standard.String; Scenario_Vars : GNATCOLL.Utils.Unbounded_String_Array; Target, RTS, Config_File : Standard.String; Project : GPR2.Project.Tree.Object; Absent_Dir_Error : GPR2.Error_Level)
Load
Project_File
intoProject
using scenario variables given inScenario_Vars
, and givenTarget
,RTS` and ``Config_File
.Scenario_Vars
should be an array of strings of the format<Var>=<Val>
. If the format is incorrect,Abort_App
will be called.If
Config_File
is not empty, thenTarget
andRTS
should be empty.See
GPR2.Options
as well as for more details about the use ofTarget
,RTS
andConfig_File
.Absent_Dir_Error
controls how missing output directories should be reported.
- function Project_To_Provider (Project : GPR2.Project.Tree.Object) Unit_Provider_Reference
Try to create a unit provider out of
Project
. If not possible, callAbort_App
.
- function Command_Line_Event_Handler (Keep_Going_On_Missing_File : Standard.Boolean) Event_Handler_Reference
Create an event handler with default callbacks for command line applications.
When a dependency is not found, a warning or error will be emitted on the standard error stream.
Keep_Going_On_Missing_File
will determine the behavior when encountering a missing dependency. IfTrue
, a warning will be shown but resolution will continue. IfFalse
, application will exit.
- procedure Abort_App (Message : Standard.String)
If provided, print Message to the standard error output and abort the current App. This will set the process exit status to Failure (see Ada.Command_Line).
- type Source_Provider_Kind
- type Source_Provider
- Discriminants:
Kind (
Source_Provider_Kind
) –
- Components:
Project (
GPR2.Project.Tree.Object
) –Dirs (
Libadalang.Project_Provider.Filename_Vectors.Vector
) –Found_Files (
Libadalang.Project_Provider.Filename_Vectors.Vector
) –
- type App_Context
- Components:
Provider (
Source_Provider
) –
- type Job_ID
Identifier for a job in App. Unless Enable_Parallelism is False, there is only one job, whose ID is 1. If there are multiple jobs, their IDs go from 1 up to the number of jobs.
- type App_Job_Context
- Components:
ID (
Job_ID
) – Identifier for this jobApp_Ctx (
not null access constant App_Context
) – Reference to the app-wide contextAnalysis_Ctx (
Analysis_Context
) – Context to analyze source file (each job gets its own context)Units_Processed (
Libadalang.Helpers.Unit_Vectors.Vector
) – List of analysis units that this job processed so farAborted (
Standard.Boolean
) – Whether this jobs was aborted (see the Abort_App_Exception/Abort_App entities above).
Whether this jobs was aborted (see the Abort_App_Exception/Abort_App entities above).
- type App_Job_Context_Array
- generic package Libadalang.Helpers.App
This package is a convenient and easy way to create an application based on Libadalang, with out of the box facilities such as:
Automatic handling of project files, including an option to process all the files of the project, and handling of scenario variables.
Automatic command line option parser, with descriptive help.
As an application author, all you have to do is to provide a
Process_Unit
procedure, that will process one unit out of the set of units to process. Users then have several options in order to run applications:Run it with project-related options (at least
-P
): by default, the app will process all units that belong to the root project that is passed. If the user passes at least one file name as additional command-line arguments, the app will process only these units.Run it with one or several
--auto-dir
options. In this case, the app will consider all Ada sources present in the given directories, and will callProcess_Unit
on all of them, unless the user passes one file name as additional command-line arguments: the app will process only these units.Just pass at least one file name on the command-line. In this case, the app will consider only Ada sources in the current directory and process only files passed on the command-line.
Note that name resolution in Ada units requires the app to know where the sources are located: this is automatic when loading a project file, but just passing files on the command-line is not enough if all source files are not in the current directory.
- Formals:
- Name : String
Name for the application. Used to create the GNATCOLL trace.
- Description : String
Description for the application. Will be used in the help string.
- Enable_Parallelism : Boolean
If True, add a -j/–jobs command line option to allow multiple jobs to run in parallel. In this mode, we create one analysis context per job, and the files to process are distributed on each job. All the callbacks below are called concurrently in all jobs:
First, the main task calls App_Setup. Then all jobs start:
Job 1 calls Job_Setup, then several Process_Units, then Job_Post_Process.
Job 2 calls Job_Setup, then several Process_Units, then Job_Post_Process.
Job 3 calls …
Finally, once all jobs are done, the main task calls App_Post_Process.
- GPR_Absent_Dir_Warning : Boolean
Whether missing directories in loaded GPR projects should be reported as warnings, or ignored.
- procedure App_Setup (Context : App_Context; Jobs : App_Job_Context_Array)
This procedure is called right after command line options are parsed, the project is loaded (if present) and the list of files to process is computed.
- procedure Job_Setup (Context : App_Job_Context)
This procedure will be called right before going through units. If a project was loaded, Project refers to it, otherwise it is null.
- procedure Process_Unit (Context : App_Job_Context; Unit : Analysis_Unit)
This procedure will be called once right after a unit is parsed
- procedure Job_Post_Process (Context : App_Job_Context)
This procedure will be called once after all units have been parsed. Note it will be called once per job.
- procedure App_Post_Process (Context : App_Context; Jobs : App_Job_Context_Array)
This procedure is called once all jobs are done
- Trace : constant GNATCOLL.Traces.Trace_Handle
- Object type:
GNATCOLL.Traces.Trace_Handle
- Default value:
GNATCOLL.Traces.Create ("LIBADALANG.APP." & Name, GNATCOLL.Traces.From_Config)
- package Libadalang.Helpers.App.Args
This package contains the arguments parser for your app. It contains the instantiation of the parser, and the set of default arguments, so that you can also use their values in your app if needed.
- Parser : Argument_Parser
- Object type:
GNATCOLL.Opt_Parse.Argument_Parser
- Default value:
Create_Argument_Parser (Help => Description)
Argument parser for your application. Supports a set of default options. You can add your own on this parser.
- package Charset is new Parse_Option
package Charset is new Parse_Option (Parser, "-C", "--charset", "Charset to use for source decoding", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String);
- Instantiated generic package:
- package Project_File is new Parse_Option
package Project_File is new Parse_Option (Parser, "-P", "--project", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Project file to use");
- Instantiated generic package:
- package Subprojects is new Parse_Option_List
package Subprojects is new Parse_Option_List (Parser, Long => "--subproject", Arg_Type => Unbounded_String, Accumulate => True, Help => "If passed, list of subprojects in which to look for source" & " files. If not passed, start from the root project only.");
- Instantiated generic package:
- package Process_Full_Project_Tree is new Parse_Flag
package Process_Full_Project_Tree is new Parse_Flag (Parser, "-U", "--recursive", Help => "Process all units in the project tree, excluding externally" & " built projects unless the --process-runtime option is also" & " passed.");
- Instantiated generic package:
- package Process_Runtime is new Parse_Flag
package Process_Runtime is new Parse_Flag (Parser, Long => "--process-runtime", Help => "Process the runtime files, and any other" & " predefined sources");
- Instantiated generic package:
- package Scenario_Vars is new Parse_Option_List
package Scenario_Vars is new Parse_Option_List (Parser, Short => "-X", Long => "--scenario-variable", Arg_Type => Unbounded_String, Accumulate => True, Help => "Scenario variables to pass to the project file");
- Instantiated generic package:
- package Target is new Parse_Option
package Target is new Parse_Option (Parser, Long => "--target", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Name of the target to use when loading the" & " project");
- Instantiated generic package:
- package RTS is new Parse_Option
package RTS is new Parse_Option (Parser, Long => "--RTS", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Name of the runtime (RTS) to use when loading" & " the project");
- Instantiated generic package:
- package Config_File is new Parse_Option
package Config_File is new Parse_Option (Parser, Long => "--config", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Name of the configuration project file. If" & " passed, this file must exist and neither" & " --target nor --RTS must be passed.");
- Instantiated generic package:
- package Auto_Dirs is new Parse_Option_List
package Auto_Dirs is new Parse_Option_List (Parser, "-A", "--auto-dir", Arg_Type => Unbounded_String, Accumulate => True, Help => "Directories to use for the auto provider. If at least one is" & " passed, the auto provider will be used, and project options" & " ignored");
- Instantiated generic package:
- package Preprocessor_Data_File is new Parse_Option
package Preprocessor_Data_File is new Parse_Option (Parser, Long => "--preprocessor-data-file", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Filename for the preprocessor data file (enables" & " preprocessing).");
- Instantiated generic package:
- package Preprocessor_Path is new Parse_Option_List
package Preprocessor_Path is new Parse_Option_List (Parser, Long => "--preprocessor-path", Arg_Type => Unbounded_String, Accumulate => True, Help => "Directory name to consider when looking for preprocessor" & " definition files.");
- Instantiated generic package:
- package Jobs is new Parse_Option
package Jobs is new Parse_Option (Parser, "-j", "--jobs", Arg_Type => Natural, Default_Val => 1, Help => "Number of parallel jobs to use. If zero, use" & " maximal parallelism: create one job per CPU.", Enabled => Enable_Parallelism);
- Instantiated generic package:
- package No_Traceback is new Parse_Flag
package No_Traceback is new Parse_Flag (Parser, Long => "--no-traceback", Help => "Do not display traceback for exceptions");
- Instantiated generic package:
- package Sym_Traceback is new Parse_Flag
package Sym_Traceback is new Parse_Flag (Parser, Long => "--symbolic-traceback", Help => "Show symbolic tracebacks for exceptions");
- Instantiated generic package:
- package Keep_Going_On_Missing_File is new Parse_Flag
package Keep_Going_On_Missing_File is new Parse_Flag (Parser, Short => "-k", Long => "--keep-going-on-missing-file", Help => "Behavior when encountering missing files. By default," & " exit with an error on the first missing dependency." & " Continue with a warning in the option is passed.");
- Instantiated generic package:
- package Sort_By_Basename is new Parse_Flag
package Sort_By_Basename is new Parse_Flag (Parser, Long => "--sort-by-basename", Help => "Process source files sorted by basename. This is useful" & " in order to get outputs that do not vary depending on" & " where the source files are installed on the file" & " system.");
- Instantiated generic package:
- procedure Run ()
Run the app. You should just call this from your main procedure for your project.
- procedure Dump_Exception (E : Ada.Exceptions.Exception_Occurrence)
Dump the exception
E
, honoring theArgs.No_Traceback
flag (i.e. don’t show tracebacks when asked not to).