diff --git a/docs/09-options.md b/docs/09-options.md new file mode 100644 index 000000000..da8eb472b --- /dev/null +++ b/docs/09-options.md @@ -0,0 +1,279 @@ +# 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: + + + + + + + + + + + + + + +
NameHas argumentAllow manyTypeDescription
searchYesYesstringPath where the AwesomeWM core libraries are located
no-argbNoNoN/ADisable built-in (real) transparency.
api-levelYesNointegerThe config API level.
screenYesNostringCreate the screen before executing `rc.lua` (`on` or `off`)
replaceNoNoN/AReplace 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 tipical +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 lineModelineShebang
YesNoNo
+ +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 lineModelineShebang
YesNoNo
+ +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 lineModelineShebang
YesNoNo
+ +Usually, modeslines 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 lineModelineShebang
YesYesYes
+ +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 lineModelineShebang
YesNoNo
+ +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 options 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 lineModelineShebang
YesYesYes
+ +This options disable 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 lineModelineShebang
YesYesYes
+ +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 lineModelineShebang
YesYesYes
+ +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 lineModelineShebang
YesYesYes
+ +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. diff --git a/docs/config.ld b/docs/config.ld index f06d603a7..62699984a 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -38,6 +38,7 @@ topics={ '05-awesomerc.md', '06-appearance.md', '07-my-first-awesome.md', + '09-options.md', '16-using-cairo.md', '17-porting-tips.md', '90-FAQ.md',