Configuration¶
The Astrality configuration directory¶
The configuration directory for astrality is determined in the following way:
- If
$ASTRALITY_CONFIG_HOME
is set, use that path as the configuration directory, else… - If
$XDG_CONFIG_HOME
is set, use$XDG_CONFIG_HOME/astrality
, otherwise… - Use
~/.config/astrality
.
The resulting directory path can be displayed by running:
$ astrality --help
usage: Astrality ...
...
The location of Astralitys configuration directory is:
"/home/jakobgm/.dotfiles/config/astrality".
...
This directory path will be referred to as $ASTRALITY_CONFIG_HOME
in the
rest of the documentation.
The Astrality configuration files¶
There are three configuration files of importance in $ASTRALITY_CONFIG_HOME
:
astrality.yml
- Global configuration options for Astrality.
modules.yml
- Here you define modules you want to use.
context.yml
- Context values used for placeholder substitution in compiled templates.
If $ASTRALITY_CONFIG_HOME/astrality.yml
does not exist, an
example configuration directory
will be used instead.
You can also copy over this example configuration directory as a starting point for your configuration by running:
$ astrality --create-example-config
Copying over example config directory to "/home/example_username/.config/astrality".
You should now edit astrality.yml
, modules.yml
, and context.yml
to
fit your needs.
The configuration file syntax¶
Astrality’s configuration files uses the YAML
format.
The syntax should be relatively self-explanatory when looking at the example
configuration.
If you still want a basic overview, take a look at the Ansible YAML syntax
documentation for
a quick primer.
Command substitution in configuration files¶
Astrality’s configuration files are themselves templates that are compiled and interpreted at startup. Using templating features in astrality configuration files is usually unnecessary.
But sometimes it is useful to insert the result of a shell command within a configuration file, such as “context.yml”. You can use command substitutions in order to achieve this:
- Command substitution:
{{ 'some_shell_command' | shell }}
is replaced with the standard output resulting from runningsome_shell_command
in abash
shell.You can set a timeout and/or fallback value for command substitutions. See the documentation for the shell filter.
Note
Shell commands are always executed from the same directory as the file which contains the command substitution.
If you need to refer to paths outside this
directory, you can use absolute paths, e.g.
{{ 'cat ~/.home_directory_file' | shell }}
.
Astrality configuration options¶
Global Astrality configuration options are specified in astrality.yml
within a dictionary named astrality
, i.e.:
# Source file: $ASTRALITY_CONFIG_HOME/astrality.yml
astrality:
hot_reload_config: true
startup_delay: 10
Avalable configuration options:
hot_reload_config:
Default:
false
If enabled, Astrality will watch for modifications to
astrality.yml
,modules.yml
, andcontext.yml
.When one of these are modified, Astrality will perform all exit actions in the old configuration, and then all startup actions from the new configuration.
Ironically requires restart if enabled.
Useful for quick feedback when editing your configuration.
startup_delay:
Default:
0
Delay Astrality on startup, given in seconds.
Useful when you depend on other startup scripts before Astrality startup, such as reordering displays.
Where to go from here¶
What you should read of the documentation from here on depends on what you intend to solve by using Astrality. The most central concepts are:
- Templating explains how to write configuration file templates.
- Modules specify which templates to compile, when to compile them, and which commands to run after they have been compiled.
- Event listeners define types of events which modules can listen to and change their behaviour accordingly.
These concepts are relatively interdependent, and each documentation section assumes knowledge of concepts explained in earlier sections. If this is the first time you are reading this documentation, you should probably just continue reading the documentation in chronological order.