7.3. Helper packages

7.3.1. Libadalang.Helpers

This package provides various helpers to build applications based on Libadalang.

package Unit_Vectors is new Ada.Containers.Vectors (Positive, Analysis_Unit)
package String_Vectors is new Ada.Containers.Vectors (Positive, Unbounded_String)
procedure Load_Project (Project_File : String; Scenario_Vars : Unbounded_String_Array; Target, RTS, Config_File : String; Project : Project_Tree_Access; Env : Project_Environment_Access)

Load Project_File using scenario variables given in Scenario_Vars, and given Target, RTS` and ``Config_File. Populate Project and Env accordingly.

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 GNATCOLL.Projects.Set_Target_And_Runtime as well as GNATCOLL.Projects.Set_Config_File for more details about the use of Target, RTS and Config_File.

procedure List_Sources_From_Project (Project : Project_Tree'Class; Include_Subprojects : Boolean; Files : String_Vectors.Vector)

Append the list of all source files in Project‘s root project to Files. If Include_Subprojects is True, include all source files in the imported projects, excluding those that are externally built.

function Project_To_Provider (Project : Project_Tree_Access) return Unit_Provider_Reference

Try to create a unit provider out of Project. If not possible, call Abort_App.

procedure Abort_App (Message : 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
type App_Context

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

Context information for a single job

type App_Job_Context_Array

7.3.1.1.1. 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
Value: GNATCOLL.Traces.Create (“LIBADALANG.APP.” & Name, GNATCOLL.Traces.From_Config)

7.3.1.1.1. 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
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 (Parser, "-C", "--charset", "Charset to use for source decoding", Unbounded_String, Default_Val => To_Unbounded_String ("iso-8859-1"))
package Project_File is new Parse_Option (Parser, "-P", "--project", Arg_Type => Unbounded_String, Default_Val => Null_Unbounded_String, Help => "Project file to use")
package Process_Full_Project_Tree is new Parse_Flag (Parser, "-U", "--recursive", Help => "Process all units in the project tree, " & "excluding externally built projects")
package Process_Runtime is new Parse_Flag (Parser, Long => "--process-runtime", Help => "Process the runtime files, and any other" & " predefined sources")
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")
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")
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")
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.")
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")
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)
package No_Traceback is new Parse_Flag (Parser, Long => "--no-traceback", Help => "Do not display traceback for exceptions")
package Sym_Traceback is new Parse_Flag (Parser, Long => "--symbolic-traceback", Help => "Show symbolic tracebacks for exceptions")
package Files is new Parse_Positional_Arg_List (Parser, Name => "files", Arg_Type => Unbounded_String, Help => "Files to analyze", Allow_Empty => True)
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).