82 lines
4.3 KiB
Markdown
82 lines
4.3 KiB
Markdown
#  Firestarter
|
|
|
|
## Overview
|
|
|
|
**Firestarter** is a desktop environment startup script. Its job is to abstract out the startup and configuration of basic X session components. By default, it will attempt to piece together a fully functional desktop environment based on currently available programs and configuration files found in `~/.config/firestarter`.
|
|
|
|
## Installation
|
|
|
|
Execute `firestarter` in your `.xinitrc`, either by replacing the file or by `exec`ing it after performing your own basic setup. You do not need the rest of the files in the repository, but a `git clone` and a regular `git pull` *is* an effective way of keeping the script up-to-date.
|
|
|
|
## Configuration
|
|
|
|
On first run and when invoked with `firestarter -g`, Firestarter will generate a series of configuration files in `~/.config/firestarter`. These files consist of several lines that look somewhat like the following:
|
|
|
|
```bash
|
|
command -v i3
|
|
i3
|
|
```
|
|
|
|
Every odd line is a command that must succeed in order for the following even line to be executed. Once an even command is executed, parsing stops. When Firestarter is invoked with no arguments, every configuration file is parsed this way.
|
|
|
|
This approach allows for a single file to contain very many alternatives while still being readable and supporting arbitrary launch requirements (such as in the case of Polybar, which requires a `launch.sh` script by default).
|
|
|
|
By setting a dummy execution line, one can effectively prevent an entire configuration file from being parsed in certain environments. As an example, the following configuration file will only attempt to start an X infobar in an X environment:
|
|
|
|
```bash
|
|
[ -z "$DISPLAY" ]
|
|
:
|
|
command -v polybar
|
|
polybar bar
|
|
command -v lemonbar
|
|
~/.bin/lemonbar.sh | lemonbar
|
|
```
|
|
|
|
After all these programs have been started, firestarter starts XDG autostart applications and executes `~/.firestarterrc` if it exists.
|
|
|
|
## Logging
|
|
|
|
All STDOUT and STDERR messages from these commands are saved to a logfile in `~/.local/share/firestarter/logs` under the same name as the configuration file. By default, these logfiles are rotated every time you log in.
|
|
|
|
If you set the variable `FS_NOLOG` to a nonempty value, firestarter will not keep logs.
|
|
|
|
## Integration
|
|
|
|
Firestarter, in addition to spawning the programs in the default configs, also integrates with the following utilities if they are installed:
|
|
|
|
* dbus: A dbus socket is either created or hooked into, depending on the environment, and the relevant variables are exposed to child processes.
|
|
|
|
* loginctl: When firestarter dies, loginctl will be called to eliminate the remainder of the session. If loginctl is not available, firestarter will kill off *only* the processes that it spawned.
|
|
|
|
* Plasma: If `kcminit` is installed, it will be invoked to configure device and theme settings. When this is the case, `XDG_CURRENT_DESKTOP` is changed to `KDE` in order for themes to actually take.
|
|
|
|
* Qt5ct: Assuming Plasma is *not* installed, qt5ct will be used as a fallback for Qt theming.
|
|
|
|
* xhost: Firestarter will open up the current session to other sessions by your user, allowing you to open a TTY and spawn your WM back in if you have to.
|
|
|
|
* xset: Firestarter will disable that annoying goddamn X bell. Re-enable it in `.firestarterrc` if you enjoy pain.
|
|
|
|
## Exit Codes
|
|
|
|
| code | meaning |
|
|
| --: | --- |
|
|
| 0 | Success |
|
|
| 40 | Firestarter is already running |
|
|
| 50 | Unrecognized argument |
|
|
| 51 | Invalid option for an argument |
|
|
| 52 | Failed to create configuration directory |
|
|
| 53 | Failed to create logging directory (and logging is enabled) |
|
|
| 54 | `HOME` does not exist or is unreadable |
|
|
|
|
## Idiosyncracies
|
|
|
|
* The `wm` config file is special; if it exists and a target can be found for it, firestarter will watch the `_NET_WM_NAME` atom on the root window, waiting for it to initialize before starting XDG autostarts. This prevents applications from being started before the WM is ready to manage them. You can disable this by setting `FS_NOWAITWM`.
|
|
|
|
* In addition to this, setting the `FS_DIEONWM` variable makes firestarter automatically end the session if the WM were to die for any reason.
|
|
|
|
## Contribution
|
|
|
|
Firestarter by no means contains an exhaustive list of all possible programs. If you know of or have created a program that should be added, *please* open an issue about it. The script should be light but its choices massive.
|
|
|
|
Bug reports are also more than welcome.
|