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
Instantiated generic package:

Ada.Containers.Vectors

package String_Vectors
Renames:

Filename_Vectors

procedure Load_Project (Project_File : Standard.String; Scenario_Vars : GNATCOLL.Utils.Unbounded_String_Array; Target : Standard.String; RTS : Standard.String; Config_File : Standard.String; Project : GPR2.Project.Tree.Object; Absent_Dir_Error : GPR2.Error_Level)

Load Project_File into Project using scenario variables given in Scenario_Vars, and given Target, 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, then Target and RTS should be empty.

See GPR2.Options as well as for more details about the use of Target, RTS and Config_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, call Abort_App.

function Command_Line_Event_Handler (Keep_Going_On_Missing_Dependency : 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_Dependency will determine the behavior when encountering a missing dependency. If True, a warning will be shown but resolution will continue. If False, 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:
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:

Context information for the whole application

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 job

  • App_Ctx (not null access constant Libadalang.Helpers.App_Context) – Reference to the app-wide context

  • Analysis_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 far

  • Aborted (Standard.Boolean) – Whether this jobs was aborted (see the Abort_App_Exception/Abort_App entities above).

Context information for a single job

type App_Job_Context_Array

6.4.2. 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 call Process_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.

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 : GNATCOLL.Opt_Parse.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
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package Project_File is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package Subprojects is new Parse_Option_List
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option_List

package Process_Full_Project_Tree is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Process_Runtime is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Scenario_Vars is new Parse_Option_List
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option_List

package Target is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package RTS is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package Config_File is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package Auto_Dirs is new Parse_Option_List
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option_List

package Preprocessor_Data_File is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package Preprocessor_Path is new Parse_Option_List
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option_List

package Jobs is new Parse_Option
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Option

package No_Traceback is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Sym_Traceback is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Keep_Going_On_Missing_Dependency is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Sort_By_Basename is new Parse_Flag
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Flag

package Files is new Parse_Positional_Arg_List
Instantiated generic package:

GNATCOLL.Opt_Parse.Parse_Positional_Arg_List

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 the Args.No_Traceback flag (i.e. don’t show tracebacks when asked not to).