Firestarter

Overview

Firestarter is a desktop environment startup script/service manager. Its job is to abstract out the startup and configuration of basic X session components. 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, ideally by execing it after performing your own basic setup.

Additionally, you will need to configure Firestarter. See the section below on how to do that.

Lastly, make sure you're not executing a bunch of stuff from your WM's config. That's Firestarter's job; let it do it.

Configuration

In the contrib directory of this repository is a series of example configuration files. These files consist of several lines that look somewhat like the following:

#.fsdefaults
command -v i3
i3
command -v openbox
openbox

Every first uncommented line is a "check" command that must succeed in order for the following "target" line to be executed. Once a target command is selected, parsing stops and the target is executed. When Firestarter is invoked with no arguments, any file with a first line of #.fsdefaults is parsed this way. This allows for quick and easy conditional execution (i.e. to fall back to your second-favorite compositor, or only start an application after it's been configured for the first time).

Any file that does not have the initial "crunchdot" is executed normally. You can keep shell scripts or symlinks in here and they will be executed without issue.

After all these programs have been started, Firestarter executes ~/.firestarterrc if it exists and then starts XDG autostart applications.

Usage

If firestarter is invoked without any arguments, it will attempt to start a session. However, there are a series of subcommands you can use to manage your session and configuration:

init: Starts a new Firestarter session. Firestarter defaults to this action if none is specified.
list, ls: List all configuration files and, if they are fsdefaults files, resolve them. Useful for debugging.
start: Start a configuration file, redirecting output to the proper logs and dropping its PID in /run for existing Firestarter instances to use.
status, st, stat: Prints information about the running Firestarter session, including PID, display, and the state of all services.
stop: Kill Firestarter, if it's running.

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.

Integration

Firestarter, in addition to spawning the programs in the default configs, also integrates with the following utilities, should the requirements be installed:

$PATH: ~/.bin and ~/.local/bin are added to $PATH at the lowest priority.
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.
xrdb: Xresources are loaded in.
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
41	Failed to initialize
50	Unrecognized argument
51	Invalid option for an argument
52	Failed to create configuration directory
53	Failed to create logging directory
54	`HOME` does not exist or is unreadable
55	Firestarter is already running
56	Firestarter is not running
70	No configuration files available

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. This requires that the target not contain any environment variable declarations; TERMINAL=urxvt i3 would not work. Arguments are okay (i.e. ksmserver -w i3).

Contribution

There's a very good chance Firestarter doesn't cover all the bases it can. If there's a common session component that you find yourself sourcing in before Firestarter, it might be worth rolling in. File an issue if that's the case.

Bug reports are also more than welcome.

If you can't reach me on this instance, feel free to reach out via email. It's listed in the header of the script.

5.4 KiB Raw Blame History