### Example Directory Structure after Installing Multiple Library Versions

Source: https://github.com/alire-project/alire/blob/master/doc/AEPs/aep-0003.md

Illustrates the file system layout after installing different versions of static and dynamic libraries, showing how `gprinstall` organizes files by version.

```text
prefix/
├── bin
│   └── hello
├── include
│   ├── hello=1.0.2
│   │   └── hello
│   │       ├── hello.adb
│   │       └── hello_config.ads
│   ├── libhello=1.0.0
│   │   └── libhello
│   │       ├── libhello.adb
│   │       └── libhello.ads
│   └── libhello=1.0.1
│       └── libhello
│           ├── libhello.adb
│           ├── libhello.ads
│           └── hello_config.ads
├── lib
│   ├── libhello=1.0.0
│   │   └── libhello
│   │       ├── libhello.a
│   │       └── libhello.ali
│   ├── libhello=1.0.1
│   │   └── libhello
│   │       ├── libhello.ali
│   │       ├── libhello_config.ali
│   │       ├── Libhello.so.1.0.1
│   │       └── libLibhello.so -> ../libhello/Libhello.so.1.0.1
│   ├── Libhello.so.1.0.1 -> ../lib/libhello=1.0.1/libhello/Libhello.so.1.0.1
│   └── libLibhello.so -> ../lib/libhello=1.0.1/libhello/libLibhello.so
└── share
    └── gpr
        ├── hello.gpr
        ├── libhello.gpr
        └── manifests
            ├── hello=1.0.2
            ├── libhello=1.0.0
            └── libhello=1.0.1
```

--------------------------------

### Install Local Crate and Show Info

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Install the current crate using `alr install` without arguments. Use `--info` to display the contents of the installation prefix.

```bash
alr -n init --bin mycrate && cd mycrate
alr install
alr install --info
```

```bash
alr get hangman && cd hangman*
alr install
```

--------------------------------

### Test Artifact Placement and Installation

Source: https://github.com/alire-project/alire/blob/master/doc/AEPs/aep-0003.md

This sequence demonstrates initializing a project, creating an artifact, building, and then installing it using gprinstall with specific options to verify artifact placement.

```bash
$ alr init --bin hello
$ cd hello
$ touch share/hello/hello-artifact
$ alr build
$ rm -rf ../prefix/ ; alr exec -- gprinstall --install-name=hello=0.1.0-dev --link-lib-subdir=bin hello.gpr --prefix=../prefix -p --mode=usage -XLIBRARY_TYPE=relocatable -r
$ tree ../prefix/ -F
../prefix/
├── bin/
│   └── hello*
└── share/
    ├── gpr/
    │   └── manifests/
    │       └── hello=0.1.0-dev
    └── hello/
        └── hello-artifact

```

--------------------------------

### Install Indexed Crate Directly

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Install an indexed crate directly using `alr install`. This is similar to `alr get` followed by `alr install` in the crate's directory, but with automatic cleanup and the ability to install multiple crates at once.

```bash
alr install hello
```

```bash
alr install hello hangman
```

--------------------------------

### Relocatable Library Installation with `gprinstall`

Source: https://github.com/alire-project/alire/blob/master/doc/AEPs/aep-0003.md

Shows how to install libraries in a relocatable manner using `gprinstall` with specific modes and options, and the resulting directory structure.

```bash
$ rm -rf ../prefix/ ; alr exec -- gprinstall --install-name=hello=1.0.2 --link-lib-subdir=bin hello.gpr --prefix=../prefix -p --mode=usage -XLIBRARY_TYPE=relocatable -r
$ tree ../prefix/ -F
../prefix/
├── bin/
│   ├── hello*
│   ├── Libhello.so.1.0.1 -> ../lib/hello=1.0.2/libhello/Libhello.so.1.0.1*
│   └── libLibhello.so -> ../lib/hello=1.0.2/libhello/libLibhello.so*
├── lib/
│   └── hello=1.0.2/
│       └── libhello/
│           ├── Libhello.so.1.0.1*
│           └── libLibhello.so -> ../libhello/Libhello.so.1.0.1*
└── share/
    └── gpr/
        └── manifests/
            └── hello=1.0.2
```

--------------------------------

### Install Binaries with `alr install`

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Use the new `alr install` subcommand to install binaries to a user-accessible location, typically `$HOME/.alire/bin`. This is an experimental feature for installing releases like compilers and `gprbuild`.

```bash
$ alr install gnatprove
ⓘ Installing gnatprove=12.1.1...
ⓘ Installation complete.
```

```bash
$ alr install
Installation prefix found at /home/jano/.alire
Contents:
   gnatprove=12.1.1
```

```bash
PATH+=:$HOME/.alire/bin gnatprove --version
Usage: gnatprove -Pproj [switches] [-cargs switches]
...
```

```bash
$ alr install gnatprove^11
error: Requested release gnatprove=11.2.3 has another version already
installed: gnatprove=12.1.1. (This error can be overridden with --force.)
```

```bash
$ alr --force install gnatprove^11  # Downgrade installation
```

--------------------------------

### TOML Website Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of specifying the project's website URL in the manifest file.

```toml
website = "https://myproject.example.org/"
```

--------------------------------

### Pre-Build Action Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

A `pre-build` action command to be run immediately before the workspace build begins. This action applies to all releases in the solution.

```toml
[[actions]]
type = "pre-build"
command = <command>
```

--------------------------------

### Post-Build Action Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

A `post-build` action command to be run after a successful build. This action is executed for all releases in the solution.

```toml
[[actions]]
type = "post-build"
command = <command>
```

--------------------------------

### TOML Description Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of how to specify a one-line description for a package in the manifest file.

```toml
description = "Library to handle foobars"
```

--------------------------------

### TOML Depends-On Static and Dynamic Examples

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Examples demonstrating static and dynamic dependencies in the manifest file, including OS-specific dependencies.

```toml
[[depends-on]]  # A static dependency
libfoo = "^1.2"

[[depends-on]]  # A dynamic dependency
[depends-on.'case(os)'.linux]
libbar = "^2.0"

[depends-on.'case(os)'.windows]
libwinbar = "^3.0"
```

--------------------------------

### TOML Project Files Static and Dynamic Examples

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Examples of specifying project files, including static lists and dynamic lists based on word size.

```toml
project-files = ["my_project.gpr", "utils/utils_for_my_project.gpr"]

[project-files.'case(word-size)']
bits-64 = ["my_project.gpr"]
bits-32 = ["my_project32.gpr"]
```

--------------------------------

### Post-Fetch Action Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

A `post-fetch` action command to be run after new sources are deployed in the workspace. All releases' `post-fetch` actions are executed after deployment.

```toml
[[actions]]
type = "post-fetch"
command = <command>
```

--------------------------------

### Get and build a project in one step with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

A shorthand command to simultaneously download and build an Alire-cataloged project.

```bash
alr get --build hello
```

--------------------------------

### TOML Licenses Examples

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Examples of specifying licenses in the manifest file, including single, double, and custom licenses.

```toml
licenses = "MIT"
```

```toml
licenses = "GPL-3.0-only OR MIT"
```

```toml
licenses = "LicenseRef-my-license-1.2"
```

--------------------------------

### Setup Python Virtual Environment for Testsuite

Source: https://github.com/alire-project/alire/blob/master/testsuite/README.md

Creates and activates a Python virtual environment for installing testsuite dependencies. The exact virtualenv command may vary by distribution.

```sh
# Create a virtualenv (prefix to install packages)
# The exact command varies from one Linux distribution to another:
# virtualenv, virtualenv3, virtualenv-3.10, ...
$ virtualenv my-virtual-env

# Update your environment to use it
$ source my-virtual-env/bin/activate

# Install e3-testsuite and all its dependencies
$ pip install -r requirements.txt

# You should now be able to run the testsuite (make sure you built alr and
# made it available with your PATH):
$ ./run.py
```

--------------------------------

### Get, build, and run a project with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

A quick workflow to download, compile, and execute an Alire-cataloged project like 'hello'. The first run may prompt for toolchain selection.

```bash
alr get hello
```

```bash
cd hello*
```

```bash
alr run
```

--------------------------------

### Dependency Tree Example

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Example of the abbreviated dependency tree output, showing omitted repeated dependencies.

```text
Dependencies (tree):
   gnat=14.1.3 (gnat_native) (>=14)
   gnatcoll=25.0.0 (~25.0.0)
   ├── gnat=14.1.3 (gnat_native) (>=13)
   └── libgpr=25.0.0 (~25.0.0)
       ├── gnat=14.1.3 (gnat_native) (/=2020)
       └── xmlada=25.0.0 (~25.0.0)
           └── gnat=14.1.3 (gnat_native) (>=11)
   gnatcoll_gmp=25.0.0 (~25.0.0)
   ├── gnatcoll=25.0.0 (~25.0.0)
   │   └── ...
   └── libgmp=6.3.0 (*)
   gnatcoll_iconv=25.0.0 (~25.0.0)
   └── gnatcoll=25.0.0 (~25.0.0)
       └── ...
```

--------------------------------

### TOML Array Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Illustrates a simple TOML array of strings.

```toml
["A", "B"]
```

--------------------------------

### TOML Tags Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of specifying tags for a crate in the manifest file to aid in discovery.

```toml
tags = ["spark", "security"]
```

--------------------------------

### Install toolchains with `alr install`

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Use `alr install` to manage toolchain installations outside of Alire's direct management. This command replaces the deprecated `toolchain --install` options. Specify a prefix to install to a custom location.

```bash
# Install to the default location, <user home>/.alire/bin
alr install gnat_native gprbuild

# Install elsewhere
alr install --prefix=/path/to/installation gnat_native gprbuild
```

--------------------------------

### Add 'Hello, world!' to a new crate

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Example Ada code for a simple 'Hello, world!' executable. Place this in `src/myproj.adb` after initializing a project.

```ada
with Ada.Text_IO;
procedure Myproj is
begin
   Ada.Text_IO.Put_Line ("Hello, world!");
end Myproj;

```

--------------------------------

### TOML Authors Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of specifying package authors in the manifest file.

```toml
authors = ["Alice Example",
           "Bob For Instance <bob@example.com>"]
```

--------------------------------

### Example Notes Field

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

The 'notes' field provides miscellaneous information about a release. It is an optional string.

```json
notes = "Experimental version"
```

--------------------------------

### Install GNAT and GPRBuild with Alire

Source: https://github.com/alire-project/alire/blob/master/testsuite/README.md

Installs GNAT and GPRBuild using Alire, specifying versions and a prefix directory. Ensure the bin directory is added to your PATH.

```sh
alr install gnat_native=<version_x> gprbuild=<version_y> --prefix=<dir>
```

--------------------------------

### Initialize Alire Crate (No Skeleton)

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use `alr init` with `--no-skel` to initialize an Alire crate without creating a project skeleton, preserving your existing GPR files. This is recommended for projects with complex GPR setups.

```bash
$ alr init --in-place --no-skel --lib my_crate
```

```bash
$ alr init --in-place --no-skel --bin my_crate
```

--------------------------------

### Multiple Conditional Actions

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Illustrates how to define multiple conditional actions, where each action can have its own set of platform-specific configurations. This allows for more complex build or setup logic.

```toml
[[actions]]
[actions.'case(os)'.linux]
# Regular contents of an action, applying to the Linux case
[actions.'case(os)'.macos]
# macOS case

[[actions]]
# Another action, that needs not be also conditional (but could be).
```

--------------------------------

### Configure Build Switches for Release Profile

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Customize build switch categories like runtime checks for specific profiles. This example enables all run-time checks in the release profile.

```toml
[build-switches]
release.runtime_checks = "Everything"
```

--------------------------------

### Example ALR Badge

Source: https://github.com/alire-project/alire/blob/master/doc/publishing.md

This is an example of the ALR badge markdown, demonstrating how to link to a specific crate (hal) on the Alire website.

```markdown
[![Alire](https://img.shields.io/endpoint?url=https://alire.ada.dev/badges/hal.json)](https://alire.ada.dev/crates/hal.html)
```

--------------------------------

### TOML Mapping Example with Version Constraints

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Shows a TOML mapping representing dependencies with version constraints, including excluding specific versions.

```toml
libfoo = "^1.2"
libbar = "^2.0 & /=2.1.3" # Excluding a known bad version
```

--------------------------------

### Global switches placement

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Global switches for Alire commands are now only allowed before the sub-command name. This example shows the correct placement.

```bash
$ alr -f show # Is OK
$ alr show -f # Is not OK (unrecognized option '-f' for 'show')
```

--------------------------------

### Publish from Remote Source Archive

Source: https://github.com/alire-project/alire/blob/master/doc/publishing.md

Use this command when starting from a remote source archive (tarball/zipball). The archive must contain a single directory with your sources and an `alire.toml` manifest at its top level. This method is suitable for projects not using git or without an online repository.

```bash
alr publish <URL>
```

--------------------------------

### Get Setting Option

Source: https://github.com/alire-project/alire/blob/master/doc/settings.md

Retrieves and prints the value of a specified setting option. The command will fail if the option is not defined.

```bash
alr settings --get my_option
```

--------------------------------

### Example TOML Manifest with Origin and Mirrors

Source: https://github.com/alire-project/alire/blob/master/doc/AEPs/aep-0005.md

This TOML snippet demonstrates how to configure a primary origin and multiple mirror sources within an Alire index manifest. The `[origin]` table specifies the main URL and commit hash, while the `[[mirror]]` tables list alternative URLs for fetching the release.

```toml
[origin]
url = "git+https://example.com/upstream/project.git"
commit = "0123456789abcdef0123456789abcdef01234567"

[[mirror]]
url = "git+https://mirror.example.com/project.git"

[[mirror]]
url = "git+https://other.example.com/project.git"

```

--------------------------------

### Local testing setup with relative path pin

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

This TOML configuration demonstrates how to set up a local testing crate that depends on the main crate. It uses a relative path pin to override the main crate with its latest local sources, suitable for testing without publishing.

```toml
# tests/alire.toml
[[depends-on]]
my_crate = "*"              # Any version of the main crate
aunit = "*"                 # We can have dependencies for testing only
[[pins]]
my_crate = { path = ".." }  # Overridden by the latest sources
```

--------------------------------

### TOML Available Platform Expression

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of a dynamic boolean expression to determine package availability based on the platform.

```toml
[available.'case(distribution)']
'debian|ubuntu' = true
'...' = false
```

--------------------------------

### Example of Automatically Added GPR With Statements

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

This section shows how Alire automatically adds 'with' statements for dependency project files to the root project file.

```ada
-- begin auto-gpr-with --
--  This section was automatically added by Alire
with "libhello.gpr";
-- end auto-gpr-with --

project Test is
...
```

--------------------------------

### Use an external dependency in Ada code

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Example Ada code demonstrating how to use a function from an added dependency (`libhello`). Ensure the dependency is added via `alr with`.

```ada
with Libhello;
procedure Myproj is
begin
   libhello.Hello_World;
end Myproj;

```

--------------------------------

### Binary Origin with Dynamic Expression

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Tags an origin as 'binary', meaning it's not compiled. This example uses a dynamic expression to apply the binary origin only to specific platforms, requiring the origin to be tagged as binary.

```toml
origin = {
  url = "https://example.com/binaries/my_tool",
  binary = true,
  'case(os)' = {
    linux = { subdir = "linux" },
    windows = { subdir = "windows" }
  }
}
```

--------------------------------

### JSON Output with --format Switch

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Use the --format switch with commands like 'search' to get structured JSON output. This is useful for programmatic parsing of Alire results.

```bash
$ alr --format=TOML search --crates hello
```

--------------------------------

### Deprecated Test Action Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

A deprecated `test` action command, run on demand for crate testing. This action only runs for the root crate being tested and does not build the crate beforehand.

```toml
[[actions]]
type = "test"
command = <command>
```

--------------------------------

### TOML Maintainers Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of specifying maintainers with contact emails in the manifest file.

```toml
maintainers = ["alice@example.com",
                 "Bob For Instance <bob@athome.com>"]
```

--------------------------------

### Initialize Alire Crate (Application)

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use `alr init` with `--in-place` and `--bin` to create a new Alire skeleton for an application crate. This is recommended for most projects.

```bash
$ alr init --in-place --bin my_crate
```

--------------------------------

### Create a new binary crate

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Initializes a new binary project. Alire will prompt for crate metadata on the first run. Use `--lib` for library projects.

```bash
alr init --bin myproj
```

--------------------------------

### Initialize Alire Crate (Library)

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use `alr init` with `--in-place` and `--lib` to create a new Alire skeleton for a library crate. This is recommended for most projects.

```bash
$ alr init --in-place --lib my_crate
```

--------------------------------

### TOML Maintainers Logins Example

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of specifying GitHub login usernames for maintainers in the manifest file.

```toml
maintainers-logins = ["alicehacks", "bobcoder"]
```

--------------------------------

### Show Crate Information with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use the `show` command to display generic information about a crate. For platform-specific details, use the `--system` flag.

```bash
alr show <crate>
```

```bash
alr show --system <crate>
```

--------------------------------

### List All Settings Options

Source: https://github.com/alire-project/alire/blob/master/doc/settings.md

Displays all currently active settings options, including their values and origins if the `--show-origin` flag is used.

```bash
alr settings --list
```

--------------------------------

### Create Source Archive for Publishing

Source: https://github.com/alire-project/alire/blob/master/doc/publishing.md

Use this command to create a source archive of your Alire project. This archive must then be manually uploaded to a hosting service.

```bash
alr publish --tar
```

--------------------------------

### Automated Project Publishing with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/publishing.md

Use this command at the root of your workspace when it's an up-to-date clone of a git repository for the simplest publishing experience. Alire will assist with the submission process.

```bash
alr publish
```

--------------------------------

### Build Alire with Bash

Source: https://github.com/alire-project/alire/blob/master/README.md

Use the provided build script for systems with Bash to compile the Alire executable.

```bash
dev/build.sh
```

--------------------------------

### Conditional Boolean Value (Inline TOML)

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Example of a conditional boolean value using inline TOML tables for environment-specific cases.

```toml
key.'case(var)'.var_value = "value"
```

--------------------------------

### Get GNAT and GPRBuild with Alire

Source: https://github.com/alire-project/alire/blob/master/testsuite/README.md

Retrieves GNAT and GPRBuild using Alire. Remember to add the respective bin directories to your PATH.

```sh
cd <dir>
alr get gnat_native=<version_x> gprbuild=<version_y>
```

--------------------------------

### Build and run a crate

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Commands to build and execute the current Alire project. The console output shows the build process and the program's result.

```bash
cd myproj
alr build
alr run
```

```console
$ alr run
# Building myproj/myproj.gpr...
Compile
   [Ada]          myproj.adb
Bind
   [gprbind]      myproj.bexch
   [Ada]          myproj.ali
Link
   [link]         myproj.adb
Build finished successfully in 0.35 seconds.
Hello, world!

```

--------------------------------

### Pass switches to gprbuild

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Pass switches and arguments for 'alr build' to the underlying 'gprbuild' execution using the '--' delimiter. This example forces recompilation.

```bash
$ alr build -- -f
```

--------------------------------

### Get Alire Identifier Rules

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use this command to view the naming conventions for Alire crate identifiers. This helps in choosing a valid crate name.

```bash
$ alr help identifiers
```

--------------------------------

### Clone Project Repository

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Clone your project's Git repository and navigate into the project directory to begin the migration process.

```bash
$ git clone https://github.com/github_login/my_crate.git
$ cd my_crate
```

--------------------------------

### Build Crate with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

After initializing the Alire crate and potentially editing the GPR file, use `alr build` to compile your project.

```bash
$ alr build
```

--------------------------------

### Define user command aliases

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Define aliases for 'alr' commands in local or global configuration. This example creates an alias 'graph' for 'show --graph'.

```bash
$ alr config --set --global alias.graph 'show --graph'
$ alr graph
```

--------------------------------

### Build and run with a new dependency

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Builds and runs the project after adding a new dependency. The output shows that the dependency's sources are automatically compiled and linked.

```console
$ alr run
# Building myproj/myproj.gpr...
Setup
   [mkdir]        object directory for project Libhello
   [mkdir]        library directory for project Libhello
Compile
   [Ada]          myproj.adb
   [Ada]          libhello.adb
Build Libraries
   [gprlib]       hello.lexch
   [archive]      libhello.a
   [index]        libhello.a
Bind
   [gprbind]      myproj.bexch
   [Ada]          myproj.ali
Link
   [link]         myproj.adb
Build finished successfully in 0.34 seconds.
Hello, world!

```

--------------------------------

### Environment-Dependent Dependencies (Idiomatic TOML)

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Illustrates environment-dependent dependencies using idiomatic TOML syntax with nested tables for different OS cases.

```toml
libfoo = "^1.2"

['case(os)'.linux]
libbar = "^2.0"

['case(os)'.windows]
libwinbar = "^3.0"

['case(os)'.'...']
```

--------------------------------

### Prefix GPR Scenario Variables

Source: https://github.com/alire-project/alire/blob/master/doc/policies.md

Prefix GPR scenario variables with the name of your crate to avoid naming conflicts. This example shows how to define a build mode variable.

```gpr
Build_Mode := External ("MY_CRATE_BUILD_MODE", "release");
```

--------------------------------

### Search for Crates and Releases with Alire

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Use the `search` command to find available crates and their descriptions. The `--crates` switch lists crates, while a general search looks into releases. Use `--list` to see all releases.

```bash
alr search --crates [substring]
```

```bash
alr search <substring>
```

```bash
alr search --list
```

```bash
alr search --list --full
```

--------------------------------

### Pin to a git repository (default branch)

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Use this to pin a dependency to a git repository. The repository will be cloned locally. This example pins to the default branch, which can be updated with `alr update`.

```toml
crate_name = { url = "https://my/repo.git" } # Updatable pin to default branch
```

--------------------------------

### Conditionally Set Environment Variables

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Environment variables can be conditionally set based on distribution using the `environment.'case(distribution)'` syntax. This example appends to `C_INCLUDE_PATH` for `msys2` distributions.

```toml
[environment.'case(distribution)']
msys2 = { C_INCLUDE_PATH.append = "${DISTRIB_ROOT}/mingw64/include/SDL2" }
```

--------------------------------

### Configure Alire Auto GPR With

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Set the global configuration for automatically adding 'with' statements for dependency project files. This can be enabled or disabled.

```bash
alr config --global --set auto-gpr-with false
```

--------------------------------

### Increase Alire Verbosity for Troubleshooting

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Increase the verbosity of Alire commands using `-v` or `-vv` to get more detailed output for troubleshooting. Use `-d` to show exception tracebacks.

```bash
alr -v
```

```bash
alr -vv
```

```bash
alr -d
```

--------------------------------

### Add a Remote Git Repository as an Index

Source: https://github.com/alire-project/alire/blob/master/doc/private-crates.md

Configure Alire to use a remote Git repository as a crate index. Replace `<URL>` with the repository URL and `<name>` with a human-friendly label. No local clone is required.

```sh
alr index --add=<URL> --name=<name>
```

--------------------------------

### Alire Dependency Graph Visualization

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Generate an ASCII art dependency graph using graph-easy. A fallback tree visualization is provided if graph-easy is unavailable.

```bash
alr with --graph
```

--------------------------------

### Build Alire with Alr

Source: https://github.com/alire-project/alire/blob/master/README.md

If a recent 'alr' binary is available, you can build Alire itself by running 'alr build' from the repository root. This command handles dependency retrieval and build configuration.

```bash
alr build
```

--------------------------------

### Execute commands in Alire environment

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Use 'alr exec' to run an executable and its arguments within the Alire environment of the current crate. This example shows how to echo the ALIRE environment variable.

```bash
$ alr exec -- sh -c 'echo ${ALIRE}'
True
```

--------------------------------

### Clone Alire Repository

Source: https://github.com/alire-project/alire/blob/master/README.md

Clone the Alire repository including all submodules. This is the first step for building from sources.

```bash
git clone --recurse-submodules https://github.com/alire-project/alire.git
```

--------------------------------

### Wrap LIBRARY_TYPE External for GPR

Source: https://github.com/alire-project/alire/blob/master/doc/policies.md

For library projects, wrap the standard LIBRARY_TYPE external in a crate-specific external to allow overriding it for individual crates. This example defines a custom Library_Type_Type and a Library_Type variable.

```gpr
type Library_Type_Type is ("relocatable", "static", "static-pic");

Library_Type : Library_Type_Type := 
  external ("MY_CRATE_LIBRARY_TYPE", external ("LIBRARY_TYPE", "static"));

for Library_Kind use Library_Type;
```

--------------------------------

### Dynamic Library Dependencies using `ldd`

Source: https://github.com/alire-project/alire/blob/master/doc/AEPs/aep-0003.md

Demonstrates how to check the shared library dependencies of an executable using the `ldd` command, showing that it correctly identifies versioned `.so` files.

```bash
$ ldd prefix/bin/hello
	linux-vdso.so.1 (0x00007fffa772f000)
	Libhello.so.1.0.1 => not found
	libgnat-12.so => /path/to/compiler/.../libgnat-12.so (0x00007fda1ca0e000)
	libgcc_s.so.1 => /path/to/compiler/.../libgcc_s.so.1 (0x00007fda1c7ef000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fda1c5c5000)
	libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fda1c5c0000)
	libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fda1c4d9000)
	/lib64/ld-linux-x86-64.so.2 (0x00007fda1d0b4000)
```

--------------------------------

### Add a Local Index to Alire

Source: https://github.com/alire-project/alire/blob/master/doc/private-crates.md

Configure Alire to use a local directory as a crate index. Replace `<path>` with the directory path and `<name>` with a human-friendly label.

```sh
alr index --add=<path> --name=<name>
```

--------------------------------

### Configure Project Dependencies in Alire Manifest

Source: https://github.com/alire-project/alire/blob/master/doc/getting-started.md

Define dependencies and pins for your Alire project in the `alire.toml` manifest file. Use `[[depends-on]]` for regular dependencies and `[[pins]]` for local path dependencies.

```toml
[[depends-on]]
mycrate = '*'

[[pins]]
mycrate = { path = '..' }
```

--------------------------------

### Alire Dependency Tree Visualization

Source: https://github.com/alire-project/alire/blob/master/doc/user-changes.md

Generate a tree visualization of dependencies. This can be used as a fallback when graph-easy is unavailable or when explicitly requested.

```bash
alr with --tree
```

--------------------------------

### Latin-1 String Literal with -gnatW8

Source: https://github.com/alire-project/alire/blob/master/doc/unicode.md

This example shows a proper Latin-1 string literal for files compiled without -gnatW8. With -gnatW8 and UTF-8 files, it works and remains a 5-byte Latin-1 string. However, with -gnatW8 and Latin-1 files, it fails due to improper UTF-8 sequences. Without -gnatW8 and UTF-8 files, it fails due to a 6-byte sequence.

```ada
Bye : constant String (1 .. 5) := "Adiós";
--  This is proper for a Latin-1-encoded file and compiling without -gnatW8.
--  With -gnatW8 and an UTF-8 file, it will work properly and also end as a 5-byte Latin-1 string.
--  With -gnatW8 but with Latin-1-encoded file, it will fail as the sequence won't be proper UTF-8.
--  Without -gnatW8 but with an UTF-8 file it will fail as the sequence will be 6 bytes long.
```

--------------------------------

### Build Alire without Bash

Source: https://github.com/alire-project/alire/blob/master/README.md

Build the Alire executable using GPRbuild for systems without Bash. Ensure the ALIRE_OS environment variable is set correctly.

```bash
ALIRE_OS=<one of: freebsd, openbsd, linux, macos, windows> gprbuild -j0 -p -P alr_env
```

--------------------------------

### Conditional Actions by OS

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

Defines post-fetch actions that vary based on the operating system. Use this to specify different build commands for different platforms.

```toml
[[actions.'case(os)'.linux]]
type = "post-fetch"
command = ["make"]

[[actions.'case(os)'.windows]]
type = "post-fetch"
command = ["cmd", "build"]

[[actions.'case(os)'.'...']]
# An explicit empty case alternative, which is not mandatory
```

--------------------------------

### Use GPR Configuration in Main Project File

Source: https://github.com/alire-project/alire/blob/master/doc/catalog-format-spec.md

The generated GPR configuration can be used in the main GPR file to dynamically select implementation units based on the configured algorithm.

```gpr
   package Naming is
      for Body ("Test.Sort") use "test-sort__" & Test_Config.Sort_Algorithm;
   end Naming;
```