.. _RM_Introduction:

.. index:: GPR, project file

************
Introduction
************

This manual is the reference for the **GNAT Project** (GPR) system: the
project file language and the tools that use it.


What is GPR?
============

A GPR project file (``.gpr``) describes a software component: where its
sources live, how they should be compiled, what libraries or executables
are produced, and how it relates to other components. The project file
language is declarative - it specifies *what* to build, not *how* - and the
GPR tools translate those declarations into concrete build, install, inspect,
or clean operations.

GPR is multi-language: a single project tree may combine Ada, C, C++, and
other languages. The active :term:`configuration project` (generated by
GPRconfig from the :term:`Knowledge base (KB)`) supplies the toolchain-specific
details - compiler drivers, default switches, library conventions - for each
language.


Tools covered
=============

This manual covers the following tools:

**GPRbuild** (:ref:`RM_GPRbuild`)
  Multi-language build tool. Compiles sources, binds Ada programs,
  builds libraries, and links executables using a DAG-based incremental
  build engine.

**GPRclean** (:ref:`RM_GPRclean`)
  Removes build results produced by GPRbuild.

**GPRinstall** (:ref:`RM_GPRinstall`)
  Installs build results into a prefix directory and maintains
  manifests for later uninstallation.

**GPRls** (:ref:`RM_GPRls`)
  Lists the sources, units, objects, and dependencies of a project
  tree, with up-to-date status.

**GPRname** (:ref:`RM_GPRname`)
  Scans source directories and generates a project file with a
  ``Naming`` package for non-standard file naming conventions.

**GPRconfig** (:ref:`RM_GPRconfig`)
  Probes the host for available compilers and generates a configuration
  project (``.cgpr``) describing the selected toolchains.

**GPRinspect** (:ref:`RM_GPRinspect`)
  Displays the resolved structure and attributes of a loaded project
  tree, in human-readable or JSON format.


Document structure
==================

This manual is divided into two parts:

**GPR Project Language**
  Covers the project file language itself: project kinds and qualifiers,
  project extension, the project file syntax, source resolution rules,
  and the attribute reference.

**GPR Tools**
  Covers the knowledge base and each tool's command-line interface,
  project packages, and behavior.

Two appendices complete the manual: an :ref:`RM_Environment_Variables`
reference and a :ref:`RM_Glossary`.


LibGPR2
=======

The GPR tools described in this manual are built on top of **LibGPR2**, an Ada
library that implements the GPR project model - parsing project files,
resolving sources and dependencies, and exposing the result as a queryable
object model.
It also provides a build infrastructure that can be used to implement custom
incremental builders. Developers who need to integrate GPR project loading or
build orchestration into their own tools work directly with LibGPR2.


Related documents
=================

**GPR User Guide**
  Task-oriented companion to this manual. Where this manual specifies the
  project file language and tool options precisely, the User Guide explains
  how to apply them: setting up a project from scratch, organizing sources,
  handling scenarios, working with libraries, and more. Readers new to GPR
  should start there.

**GPR2 Quick Start**
  Introduction to LibGPR2 for developers who want to load and query project
  trees programmatically. Covers the main entry points with worked examples.

**GPR2 Library Reference**
  Comprehensive presentation of the main elements of the LibGPR2 API.