# Variables

## Introduction

Variables in VyBuild allow for rapid changes of the build pipeline parameters and can be used almost anywhere.

## Overview

In VyBuild, there are two types of variables:
- user-defined variables (also called global variables): these are defined as pairs of string in the `global_vars` field of every root module. They are usables in all parts of the build pipeline without restriction.
- systems variables: these are special variables defined by VyBuild containing specific values. Some are usable globally and some are only usables in some fields. For more information about these ones, see [actions docs](actions.md)

## Using a global variable

To define a global variable with a custom value, simply add a pair of string inside the `global_vars` field of the root module of your pipeline.

To define a global variable with an automated UUID v4 that changes at each build, simply add a string inside the `global_uuid` field of the root module of your pipeline.

You can use variables in almost every fields that are either a string or a list of strings. You know if a field support variables if there is a boolean field in the same action with the name `<field name>_variables`. These variables fields are mandatory and indicate if VyBuild will attempt to detect and replace variables in any field where the corresponding variable field is set to `true`.

To use global variables in a field that support it, just put your variable name between `$`.

Example with `SOME_VARIABLE` containing `somes informations`:
``` json
{
  "field_variables":true,
  "field":"hey$SOME_VARIABLE$hey"
}
```

In this example, the value that VyBuild sees after replacing the variable is `heysomes informationshey`.

Variable names are usually in uppercases letters to avoid any confusion with others parts of a field. This is to follow the same C macros style.

### Specials global variables

Some global variables are a way for some parts of VyBuild to let the user add features to them. Here is a exhaustive list of these special global variables
- `__VYBUILD_COMPILER_HASH_`: any global variables starting with this prefix will be used by actions that compile C/CPP code to include optional information on the used toolchain. These actions will consider the content of these variables as already-formated commands that they can execute and include the output of these commands into the cache keys of each cached objects. That way, any change to the toolchain can be detected and trigger a recompilation

## Using systems variables

Systems variables are variables created by VyBuild, usable in certain contexts. This file will only cover systems variables that aren't specific to certains actions.

Systems variables can be used in almost any fields with some limitations. When used, they are framed with `%`. Here is a complete list:

Name | Content | Behaviour
-----|---------|----------
`%rootcallerfolder%` | The full path of the parent folder of the root module of every build pipeline | Usable in every action fields that support it. Can also be used in the `root_folder` field of every module but alone (can't be combined in a path for this field).
`%filefolder%` | The absolute path of the directory containing the current module's JSON file | Can only be used alone (can't be combined in a path for this field) in the `root_folder` of every module.

Command line arguments that aren't VyBuild parameters will be exposed as systems variables under the index of the argument in the command line.

Example: 

``` bash
vybuild <path to root module> img
```

In this example, the system variable `1` will be created by VyBuild with the value `img`, and can be used in any action fields that support variables using the syntax `%1%`.
