# Startup options

This document explains how to control how AwesomeWM behaves before rc.lua is executed.

## Command line

AwesomeWM has the following command line options:

Usage: awesome [OPTION] -h, --help show help -v, --version show version -c, --config FILE configuration file to use -f --force ignore modelines and apply the command line arguments -s, --search DIR add a directory to the library search path -k, --check check configuration file syntax -a, --no-argb disable client transparency support -l --api-level LEVEL select a different API support level than the current version -m, --screen on|off enable or disable automatic screen creation (default: on) -r, --replace replace an existing window manager

## Modelines

Usually, AwesomeWM is started using a session manager rather than directly using the command line. On top of that, to make rc.lua more portable, it is possible to set many of those options directly in your config file. They will be interpreted before the Lua virtual machine is started. The keys are:

Name | Has argument | Allow many | Type | Description
--- | --- | --- | --- | ---
search | Yes | Yes | string | Path where the AwesomeWM core libraries are located
no-argb | No | No | N/A | Disable built-in (real) transparency.
api-level | Yes | No | integer | The config API level.
screen | Yes | No | string | Create the screen before executing rc.lua (`on` or `off`)
replace | No | No | N/A | Replace the current window manager.

A `modeline` must be near the top of rc.lua and start with `-- awesome_mode:`. The options are separated by `:`. If an option has a value, it is separated by `=`. The default modeline is:

-- awesome_mode: api-level=4:screen=on

To display more deprecation errors, you can increase the API level by 2:

-- awesome_mode: api-level=6:screen=on

## #! (shebang) support.

It is possible to make some `.lua` file executable and use the POSIX magic prefix (`#!`, often referred as the shebang operator). AwesomeWM will attempt to parse the header. Note that for now UTF-8 paths are not supported. A typical file header will look like:

#! /usr/bin/env awesome --replace -- If LuaRocks is installed, make sure that packages installed through it -- are found (e.g. lgi). If LuaRocks is not installed, do nothing. pcall(require, "luarocks.loader")

-- Standard awesome library local gears = require("gears") [... more rc.lua content ...]

Then you can make the script executable with `chmod +x` and run it.

## Options description

### version (-v)

Command line | Modeline | Shebang
--- | --- | ---
Yes | No | No

The typical output will look like:

awesome v4.3 (Too long) • Compiled against Lua 5.1.5 (running with Lua 5.1) • API level: 4 • D-Bus support: yes • xcb-errors support: no • execinfo support: yes • xcb-randr version: 1.6 • LGI version: 0.9.2 • Transparency enabled: yes • Custom search paths: no

The content is useful when reporting a bug.

### config (-c): Alternate config path.

Command line | Modeline | Shebang
--- | --- | ---
Yes | No | No

This option allows to pass an arbitrary Lua file to be used as a config rather than `~/.config/awesome/rc.lua` or `/etc/xdg/awesome/rc.lua`. It makes zero sense in the shebang since you invoke a script directly. It doesn't make sense in the modeline either since at that point the file is already being read.

### force (-f): Use the command line arguments even when the modeline disagree.

Command line | Modeline | Shebang
--- | --- | ---
Yes | No | No

Usually, modelines have the final say of which options to enable. This allows rc.lua to be portable between computers without have to modify `~/.xinitrc` or your session files. However, sometime, it is useful to override these parameters. The most common use case is the to bump the API level to see more deprecation warnings.

### search (-s): Add directories to the Lua search paths.

Command line | Modeline | Shebang
--- | --- | ---
Yes | Yes | Yes

This option allows to add more paths to the Lua search path. It can be used to set an alternate version of the core libraries such as `awful` to make upstream patches development easier. It can also be used to point to custom modules. It is usually recommended to place custom modules in `~/.config/awesome/` or `/usr/share/awesome/lib`. Again, this option is mostly useful for development.

### check (-k): Check the config **SYNTAX**.

Command line | Modeline | Shebang
--- | --- | ---
Yes | No | No

This option only check if the file is a valid Lua script. It will not check if your custom logic makes sense. Even when this option says your config is fine, it does **NOT** mean it can load properly. It only means it can be parsed and the interpreter can attempt to execute it.

### no-argb (-a): Mitigate buggy graphics drivers.

Command line | Modeline | Shebang
--- | --- | ---
Yes | Yes | Yes

This option disables the built-in real transparency support. This means titlebars and wiboxes can no longer be made fully transparent. If you don't use a compositing manager such as `compton` or `picom`, this will only improve reliability and portability. Transparency is enabled by default and this should only be used when your config misbehave with a popular graphics driver. If it does, please notify them. The bug is on their side.

### api-level (-l): Force your config to use a different API version.

Command line | Modeline | Shebang
--- | --- | ---
Yes | Yes | Yes

If you invested a lot of effort into a configuration and a new major version is AwesomeWM is released, you might want to postpone having to update everything until you are ready to begin using the new features. If the API level is set, AwesomeWM will try to honor the behavior and content of the previous APIs.

You can also set this value forward to get notified faster of your usage of newly deprecated API and enjoy cutting edge experimental features.

The default API level matches the first component of the AwesomeWM version. For example, AwesomeWM v4.3 API level is "4". This only goes back to AwesomeWM 4.0. The older 3.x APIs have been removed.

### screen (-m): Set the screen creation behavior.

Command line | Modeline | Shebang
--- | --- | ---
Yes | Yes | Yes

This option changes *when* screen objects are created. In AwesomeWM 4.x, by default, they are created before rc.lua is parsed. This is very convenient for setup where the number of screen never changes. By creating them before rc.lua, it is possible to make many assumptions such as mouse.screen and `awful.screen.focused()` to always point to a valid screen. This is the `on` behavior. The main downside is that when the number of screen changes or when the DPI must be modified, all the automatic magic becomes very inconvenient.

When set to `off`, the screens are created early when executing rc.lua. This has the advantages of sending multiple signals and giving a lot more configuration options for features like the DPI or ultra-wide monitor. It also make it easier to add and remove screens dynamically since they are fully. In the future, the default will be `off` to allow HiDPI support to be enabled by default. controllable by Lua code.

### replace (-r): Replace the current window manager with AwesomeWM.

Command line | Modeline | Shebang
--- | --- | ---
Yes | Yes | Yes

If this option is set, AwesomeWM will kill the current window manager (even if it is another awesome instance and replace it. This is disabled by default.

generated by LDoc 1.5.0