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