Template Tags¶

Makim config files are powered by the Jinja2 template engine, allowing you to use Jinja2 tags for added flexibility in your Makim config files.

This page focuses on explaining the options offered directly by Makim, rather than covering all the possibilities with Jinja2.

Makim provides three different variable options that can be combined: vars, env, and args.

Additionally, the env and vars option has three different scopes: global, group, and task. We will discuss each of them in the following sections.

Variables Scopes¶

Before delving into the different variable options, let's discuss env and vars scope, as it is essential for the subsequent sections. The args attribute just works in the task scope.

As mentioned earlier, Makim env and vars has three scopes: global, group, and task.

The order of their rendering is crucial. First, the global scope is processed. In the group scope, any variable defined globally is accessible via the env variable (e.g., ${{ env.my_global_env }}). However, any variable defined in the global scope will be overridden by a variable with the same name in the group scope. The same applies to the task scope, where any variable defined in the global or group scope will be overridden by a variable defined in the task scope.

Moreover, env is a bit more complex, as its value can be defined in two different ways: either through the env attribute in the .makim.yaml file or from an environment file specified in the env-file attribute. First, the env-file is loaded into memory, and then the variables defined in the env attribute are loaded. In other words, any variable defined in the file for the given env-file will be overridden by a variable of the same name defined in the env attribute. This process also respects the order of scopes.

PS: Makim utilizes system environment variables as the initial scope for the variables.

Different Variable Options¶

Makim offers three variable options within the makim config file: env, vars, and args.

args allows users to pass parameters via the CLI (command line interface). It can also be used for task dependencies when parameters need to be passed to the dependency. However, this option is not available in the system context (the commands executed defined by run attribute), it is only accessible within the Makim config file.
vars is a convenient way to define reusable variables in the code. For example, if you frequently use a command in the run section, you can define a variable inside vars to make the Makim file more readable. Like args, this option is not available in the system context; it is only accessible within the Makim config file.
env is used to define environment variables. Any environment variable can be accessed via the env variable in the template (e.g., ${{ env.myenvvar }}) or directly as an environment variable within the run section, as shown in the example below:

...
groups:
  group1:
    tasks:
      task1:
        ...
        env:
          MYVAR: 1
        run: |
          echo $MYENV

Order of Variable Rendering¶

One crucial point to keep in mind is the order of variable rendering within the Makim config file.

vars is primarily used for run section, so they have the lowest precedence. In another word, you can use env or arg to create vars, but not the opposite way.

env however, can be defined also in the system scope, so it has the highest rank in the precedence. So, you shouldn't define a env that depends on a variable defined by vars or args. If you need to set your environment variable with a value from a vars or args, you should do it in the run section.

In the following example, it shows a correct way to use all the different options of variables, respecting the scopes and rendering order:

---
env:
  MY_GLOBAL_ENV: 1
vars:
  MY_GLOBAL_VAR:
    "my global env is ${{ env.MY_GLOBAL_ENV }}"

groups:
  group1:
    help: "group"
    env:
      MY_GROUP_ENV: 2
    vars:
      MY_GROUP_VAR:
        "my group env is ${{ env.MY_GROUP_ENV }}"
    tasks:
      task1:
        help: "task 1"
        env:
          MY_TARGET_ENV: 3
        args:
          my-task-arg:
            help: "task arg"
            type: string
            default: "${{ env.MY_TARGET_ENV }}"
        vars:
          MY_TARGET_VAR:
            "my group env is ${{ env.MY_GROUP_ENV }}"
        run: |
          echo "${{ env.MY_GLOBAL_ENV}}"
          echo "${{ env.MY_GLOBAL_VAR}}"
          echo "${{ env.MY_GROUP_ENV}}"
          echo "${{ env.MY_GROUP_VAR}}"
          echo "${{ env.MY_TARGET_ENV}}"
          echo "${{ env.MY_TARGET_VAR}}"
          echo "${{ env.my_task_arg}}"