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:: Unit_Vectors

procedure Load_Project (Project_File : Standard.String; Scenario_Vars : GNATCOLL.Utils.Unbounded_String_Array; Target, RTS, Config_File : Standard.String; Project : GNATCOLL.Projects.Project_Tree_Access; Env : GNATCOLL.Projects.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.

function Project_To_Provider (Project : GNATCOLL.Projects.Project_Tree_Access) → 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_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. 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:

Kind (Source_Provider_Kind) –

Components:

Project (GNATCOLL.Projects.Project_Tree_Access) –
Dirs (Libadalang.Project_Provider.Filename_Vectors.Vector) –
Found_Files (Libadalang.Project_Provider.Filename_Vectors.Vector) –
GPR2_Project (access GPR2.Project.Tree.Object) –

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 job
App_Ctx (not null access constant 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).

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 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.

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.

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:: Charset

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:: Project_File

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:: Subprojects

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:: Process_Full_Project_Tree

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:: Process_Runtime

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:: Scenario_Vars

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:: Target

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:: RTS

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:: Config_File

package GPR2 is new Parse_Flag

package GPR2 is new Parse_Flag
           (Parser, Long => "--gpr2",
            Help         => "Internal option (will be removed without notice"
                            & " in the future). Use GPR2 to process project"
                            & " files (GNATCOLL.Projects is the default)");

Instantiated generic package:: GPR2

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:: Auto_Dirs

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:: Preprocessor_Data_File

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:: Preprocessor_Path

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:: Jobs

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:: No_Traceback

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:: Sym_Traceback

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:: Keep_Going_On_Missing_File

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:: Sort_By_Basename

package Files is new Parse_Positional_Arg_List

package Files is new Parse_Positional_Arg_List
           (Parser,
            Name        => "files",
            Arg_Type    => Unbounded_String,
            Help        => "Files to analyze",
            Allow_Empty => True);

Instantiated generic package:: Files

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).