Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 1 | .\" shorthand for double quote that works everywhere. |
| 2 | .ds q \N'34' |
| 3 | .TH weston.ini 5 "2013-01-17" "Weston __version__" |
| 4 | .SH NAME |
| 5 | weston.ini \- configuration file for |
| 6 | .B Weston |
| 7 | \- the reference Wayland |
| 8 | compositor |
| 9 | .SH INTRODUCTION |
| 10 | .B Weston |
| 11 | obtains configuration from its command line parameters and the configuration |
| 12 | file described here. |
| 13 | .SH DESCRIPTION |
| 14 | .B Weston |
| 15 | uses a configuration file called |
| 16 | .I weston.ini |
| 17 | for its setup. |
| 18 | The |
| 19 | .I weston.ini |
| 20 | configuration file is searched for in one of the following places when the |
| 21 | server is started: |
| 22 | .PP |
| 23 | .RS 4 |
| 24 | .nf |
| 25 | .BR "$XDG_CONFIG_HOME/weston.ini " "(if $XDG_CONFIG_HOME is set)" |
| 26 | .BR "$HOME/.config/weston.ini " "(if $HOME is set)" |
Ossama Othman | a50e6e4 | 2013-05-14 09:48:26 -0700 | [diff] [blame] | 27 | .B "weston/weston.ini in each" |
| 28 | .BR "\ \ \ \ $XDG_CONFIG_DIR " "(if $XDG_CONFIG_DIRS is set)" |
| 29 | .BR "/etc/xdg/weston/weston.ini " "(if $XDG_CONFIG_DIRS is not set)" |
| 30 | .BR "<current dir>/weston.ini " "(if no variables were set)" |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 31 | .fi |
| 32 | .RE |
| 33 | .PP |
| 34 | where environment variable |
| 35 | .B $HOME |
| 36 | is the user's home directory, and |
| 37 | .B $XDG_CONFIG_HOME |
Ossama Othman | a50e6e4 | 2013-05-14 09:48:26 -0700 | [diff] [blame] | 38 | is the user specific configuration directory, and |
| 39 | .B $XDG_CONFIG_DIRS |
| 40 | is a colon |
| 41 | .B ':' |
| 42 | delimited listed of configuration base directories, such as |
| 43 | .BR /etc/xdg-foo:/etc/xdg . |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 44 | .PP |
| 45 | The |
| 46 | .I weston.ini |
| 47 | file is composed of a number of sections which may be present in any order, or |
| 48 | omitted to use default configuration values. Each section has the form: |
| 49 | .PP |
| 50 | .RS 4 |
| 51 | .nf |
| 52 | .BI [ SectionHeader ] |
| 53 | .RI Key1=Value1 |
| 54 | .RI Key2=Value2 |
| 55 | ... |
| 56 | .fi |
| 57 | .RE |
| 58 | .PP |
| 59 | The spaces are significant. |
| 60 | Comment lines are ignored: |
| 61 | .PP |
| 62 | .RS 4 |
| 63 | .nf |
| 64 | .IR "#comment" |
| 65 | .fi |
| 66 | .RE |
| 67 | .PP |
| 68 | The section headers are: |
| 69 | .PP |
| 70 | .RS 4 |
| 71 | .nf |
| 72 | .BR "core " "The core modules" |
| 73 | .BR "shell " "Desktop customization" |
| 74 | .BR "launcher " "Add launcher to the panel" |
| 75 | .BR "screensaver " "Screensaver selection" |
| 76 | .BR "output " "Output configuration" |
| 77 | .BR "input-method " "Onscreen keyboard input" |
| 78 | .BR "keyboard " "Keyboard layouts" |
| 79 | .BR "terminal " "Terminal application options" |
Maksim Melnikau | 92de144 | 2013-08-14 22:33:10 +0300 | [diff] [blame] | 80 | .BR "xwayland " "XWayland options" |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 81 | .fi |
| 82 | .RE |
| 83 | .PP |
| 84 | Possible value types are string, signed and unsigned 32-bit |
| 85 | integer, and boolean. Strings must not be quoted, do not support any |
| 86 | escape sequences, and run till the end of the line. Integers can |
| 87 | be given in decimal (e.g. 123), octal (e.g. 0173), and hexadecimal |
| 88 | (e.g. 0x7b) form. Boolean values can be only 'true' or 'false'. |
| 89 | .RE |
| 90 | .SH "CORE SECTION" |
| 91 | The |
| 92 | .B core |
| 93 | section is used to select the startup compositor modules. |
| 94 | .TP 7 |
Nobuhiko Tanibata | 8841917 | 2014-02-10 12:15:11 +0900 | [diff] [blame] | 95 | .BI "shell=" desktop-shell.so |
| 96 | specifies a shell to load (string). This can be used to load your own |
| 97 | implemented shell or one with Weston as default. Available shells |
| 98 | in the |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 99 | .IR "__weston_modules_dir__" |
| 100 | directory are: |
| 101 | .PP |
| 102 | .RS 10 |
| 103 | .nf |
| 104 | .BR desktop-shell.so |
Nobuhiko Tanibata | 8841917 | 2014-02-10 12:15:11 +0900 | [diff] [blame] | 105 | .fi |
| 106 | .RE |
| 107 | .TP 7 |
| 108 | .TP 7 |
| 109 | .BI "modules=" xwayland.so,cms-colord.so |
| 110 | specifies the modules to load (string). Available modules in the |
| 111 | .IR "__weston_modules_dir__" |
| 112 | directory are: |
| 113 | .PP |
| 114 | .RS 10 |
| 115 | .nf |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 116 | .BR xwayland.so |
Nobuhiko Tanibata | 8841917 | 2014-02-10 12:15:11 +0900 | [diff] [blame] | 117 | .BR cms-colord.so |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 118 | .fi |
| 119 | .RE |
Kristian Høgsberg | 8e6f376 | 2013-10-16 16:31:42 -0700 | [diff] [blame] | 120 | .TP 7 |
Lubomir Rintel | ba44c6b | 2013-11-15 14:18:15 +0100 | [diff] [blame] | 121 | .TP 7 |
| 122 | .BI "backend=" headless-backend.so |
| 123 | overrides defaults backend. Available backend modules in the |
| 124 | .IR "__weston_modules_dir__" |
| 125 | directory are: |
| 126 | .PP |
| 127 | .RS 10 |
| 128 | .nf |
| 129 | .BR drm-backend.so |
| 130 | .BR fbdev-backend.so |
| 131 | .BR headless-backend.so |
| 132 | .BR rdp-backend.so |
| 133 | .BR rpi-backend.so |
| 134 | .BR wayland-backend.so |
| 135 | .BR x11-backend.so |
| 136 | .fi |
| 137 | .RE |
Kristian Høgsberg | 8e6f376 | 2013-10-16 16:31:42 -0700 | [diff] [blame] | 138 | .BI "gbm-format="format |
| 139 | sets the GBM format used for the framebuffer for the GBM backend. Can be |
| 140 | .B xrgb8888, |
| 141 | .B xrgb2101010, |
| 142 | .B rgb565. |
| 143 | By default, xrgb8888 is used. |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 144 | .RS |
| 145 | .PP |
| 146 | |
| 147 | .SH "SHELL SECTION" |
| 148 | The |
| 149 | .B shell |
| 150 | section is used to customize the compositor. Some keys may not be handled by |
| 151 | different shell plugins. |
| 152 | .PP |
| 153 | The entries that can appear in this section are: |
| 154 | .TP 7 |
Emilio Pozuelo Monfort | 46ce798 | 2013-11-20 13:22:29 +0100 | [diff] [blame] | 155 | .BI "client=" file |
| 156 | sets the path for the shell client to run. If not specified |
Emilio Pozuelo Monfort | 8a81b83 | 2013-12-02 12:53:32 +0100 | [diff] [blame] | 157 | .I __weston_shell_client__ |
| 158 | is launched (string). |
Emilio Pozuelo Monfort | 46ce798 | 2013-11-20 13:22:29 +0100 | [diff] [blame] | 159 | .TP 7 |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 160 | .BI "background-image=" file |
| 161 | sets the path for the background image file (string). |
| 162 | .TP 7 |
Emilio Pozuelo Monfort | f12a094 | 2013-04-22 11:00:07 +0200 | [diff] [blame] | 163 | .BI "background-type=" tile |
Pekka Paalanen | a402b05 | 2013-05-22 18:03:10 +0300 | [diff] [blame] | 164 | determines how the background image is drawn (string). Can be |
| 165 | .BR scale ", " scale-crop " or " tile " (default)." |
| 166 | Scale means scaled to fit the output precisely, not preserving aspect ratio. |
| 167 | Scale-crop preserves aspect ratio, scales the background image just big |
| 168 | enough to cover the output, and centers it. The image ends up cropped from |
| 169 | left and right, or top and bottom, if the aspect ratio does not match the |
| 170 | output. Tile repeats the background image to fill the output. |
Emilio Pozuelo Monfort | f12a094 | 2013-04-22 11:00:07 +0200 | [diff] [blame] | 171 | .TP 7 |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 172 | .BI "background-color=" 0xAARRGGBB |
| 173 | sets the color of the background (unsigned integer). The hexadecimal |
| 174 | digit pairs are in order alpha, red, green, and blue. |
| 175 | .TP 7 |
| 176 | .BI "panel-color=" 0xAARRGGBB |
| 177 | sets the color of the panel (unsigned integer). The hexadecimal |
| 178 | digit pairs are in order transparency, red, green, and blue. Examples: |
| 179 | .PP |
| 180 | .RS 10 |
| 181 | .nf |
| 182 | .BR "0xffff0000 " "Red" |
| 183 | .BR "0xff00ff00 " "Green" |
| 184 | .BR "0xff0000ff " "Blue" |
| 185 | .BR "0x00ffffff " "Fully transparent" |
| 186 | .fi |
| 187 | .RE |
| 188 | .TP 7 |
Jonny Lamb | e67118c | 2014-08-12 15:07:51 +0200 | [diff] [blame] | 189 | .BI "panel-location=" top |
| 190 | sets the location of the panel (string). Can be |
| 191 | .B top, |
| 192 | .B none. |
| 193 | .TP 7 |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 194 | .BI "locking=" true |
| 195 | enables screen locking (boolean). |
| 196 | .TP 7 |
| 197 | .BI "animation=" zoom |
| 198 | sets the effect used for opening new windows (string). Can be |
| 199 | .B zoom, |
Kristian Høgsberg | 724c8d9 | 2013-10-16 11:38:24 -0700 | [diff] [blame] | 200 | .B fade, |
| 201 | .B none. |
| 202 | By default, no animation is used. |
| 203 | .TP 7 |
Jonny Lamb | f322f8e | 2014-08-12 15:13:30 +0200 | [diff] [blame^] | 204 | .BI "close-animation=" fade |
| 205 | sets the effect used when closing windows (string). Can be |
| 206 | .B fade, |
| 207 | .B none. |
| 208 | By default, the fade animation is used. |
| 209 | .TP 7 |
Kristian Høgsberg | 724c8d9 | 2013-10-16 11:38:24 -0700 | [diff] [blame] | 210 | .BI "startup-animation=" fade |
| 211 | sets the effect used for opening new windows (string). Can be |
| 212 | .B fade, |
| 213 | .B none. |
| 214 | By default, the fade animation is used. |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 215 | .TP 7 |
Emilio Pozuelo Monfort | bb835b4 | 2013-11-20 13:22:30 +0100 | [diff] [blame] | 216 | .BI "focus-animation=" dim-layer |
| 217 | sets the effect used with the focused and unfocused windows. Can be |
| 218 | .B dim-layer, |
| 219 | .B none. |
| 220 | By default, no animation is used. |
| 221 | .TP 7 |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 222 | .BI "binding-modifier=" ctrl |
| 223 | sets the modifier key used for common bindings (string), such as moving |
| 224 | surfaces, resizing, rotating, switching, closing and setting the transparency |
| 225 | for windows, controlling the backlight and zooming the desktop. Possible values: |
| 226 | ctrl, alt, super (default) |
| 227 | .TP 7 |
| 228 | .BI "num-workspaces=" 6 |
| 229 | defines the number of workspaces (unsigned integer). The user can switch |
| 230 | workspaces by using the |
| 231 | binding+F1, F2 keys. If this key is not set, fall back to one workspace. |
| 232 | .TP 7 |
Emilio Pozuelo Monfort | 57ac406 | 2013-03-14 17:23:38 +0100 | [diff] [blame] | 233 | .BI "cursor-theme=" theme |
| 234 | sets the cursor theme (string). |
| 235 | .TP 7 |
| 236 | .BI "cursor-size=" 24 |
| 237 | sets the cursor size (unsigned integer). |
| 238 | .TP 7 |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 239 | .BI "lockscreen-icon=" path |
| 240 | sets the path to lock screen icon image (string). (tablet shell only) |
| 241 | .TP 7 |
| 242 | .BI "lockscreen=" path |
| 243 | sets the path to lock screen background image (string). (tablet shell only) |
| 244 | .TP 7 |
| 245 | .BI "homescreen=" path |
| 246 | sets the path to home screen background image (string). (tablet shell only) |
| 247 | .RE |
| 248 | .SH "LAUNCHER SECTION" |
| 249 | There can be multiple launcher sections, one for each launcher. |
| 250 | .TP 7 |
| 251 | .BI "icon=" icon |
| 252 | sets the path to icon image (string). Svg images are not currently supported. |
| 253 | .TP 7 |
| 254 | .BI "path=" program |
| 255 | sets the path to the program that is run by clicking on this launcher (string). |
| 256 | It is possible to pass arguments and environment variables to the program. For |
| 257 | example: |
| 258 | .nf |
| 259 | .in +4n |
| 260 | |
| 261 | path=GDK_BACKEND=wayland gnome-terminal --full-screen |
| 262 | .in |
| 263 | .fi |
| 264 | .PP |
| 265 | .RE |
| 266 | .SH "SCREENSAVER SECTION" |
| 267 | The |
| 268 | .B screensaver |
| 269 | section is used to select and schedule a screensaver. |
| 270 | The |
| 271 | .B screensaver |
| 272 | section is optional, as are all of the entries that may be specified in |
| 273 | it. |
| 274 | .TP 7 |
| 275 | .BI "path=" /usr/libexec/weston-screensaver |
| 276 | This instructs the compositor to use the selected screensaver client on a given |
| 277 | path (string). If this line is missing or commented out, the screensaver in |
| 278 | .B "weston(1)" |
| 279 | is disabled. |
| 280 | .RE |
| 281 | .TP 7 |
| 282 | .BI "duration=" 600 |
| 283 | The idle time in seconds until the screensaver disappears in order to save power |
| 284 | (unsigned integer). |
| 285 | .SH "OUTPUT SECTION" |
| 286 | There can be multiple output sections, each corresponding to one output. It is |
| 287 | currently only recognized by the drm and x11 backends. |
| 288 | .TP 7 |
| 289 | .BI "name=" name |
| 290 | sets a name for the output (string). The backend uses the name to |
Jason Ekstrand | 48ce421 | 2013-10-27 22:25:02 -0500 | [diff] [blame] | 291 | identify the output. All X11 output names start with a letter X. All |
| 292 | Wayland output names start with the letters WL. The available |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 293 | output names for DRM backend are listed in the |
| 294 | .B "weston-launch(1)" |
| 295 | output. |
| 296 | Examples of usage: |
| 297 | .PP |
| 298 | .RS 10 |
| 299 | .nf |
| 300 | .BR "LVDS1 " "DRM backend, Laptop internal panel no.1" |
| 301 | .BR "VGA1 " "DRM backend, VGA connector no.1" |
| 302 | .BR "X1 " "X11 backend, X window no.1" |
Jason Ekstrand | 48ce421 | 2013-10-27 22:25:02 -0500 | [diff] [blame] | 303 | .BR "WL1 " "Wayland backend, Wayland window no.1" |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 304 | .fi |
| 305 | .RE |
| 306 | .RS |
| 307 | .PP |
| 308 | See |
| 309 | .B "weston-drm(7)" |
| 310 | for more details. |
| 311 | .RE |
| 312 | .TP 7 |
| 313 | .BI "mode=" mode |
| 314 | sets the output mode (string). The mode parameter is handled differently |
| 315 | depending on the backend. On the X11 backend, it just sets the WIDTHxHEIGHT of |
| 316 | the weston window. |
| 317 | The DRM backend accepts different modes: |
| 318 | .PP |
| 319 | .RS 10 |
| 320 | .nf |
| 321 | .BR "WIDTHxHEIGHT " "Resolution size width and height in pixels" |
| 322 | .BR "preferred " "Uses the preferred mode" |
| 323 | .BR "current " "Uses the current crt controller mode" |
| 324 | .BR "off " "Disables the output" |
| 325 | .fi |
| 326 | .RE |
| 327 | .RS |
| 328 | .PP |
| 329 | Optionally, an user may specify a modeline, such as: |
| 330 | .PP |
| 331 | .nf |
| 332 | .in +4n |
| 333 | .nf |
| 334 | 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync |
| 335 | .fi |
| 336 | .in |
| 337 | .PP |
| 338 | It consists of the refresh rate in Hz, horizontal and vertical resolution, |
| 339 | options for horizontal and vertical synchronisation. The program |
| 340 | .B "cvt(1)" |
| 341 | can provide suitable modeline string. |
| 342 | .RE |
| 343 | .TP 7 |
| 344 | .BI "transform=" normal |
| 345 | The transformation applied to screen output (string). The transform key can |
| 346 | be one of the following 8 strings: |
| 347 | .PP |
| 348 | .RS 10 |
| 349 | .nf |
| 350 | .BR "normal " "Normal output." |
| 351 | .BR "90 " "90 degrees clockwise." |
| 352 | .BR "180 " "Upside down." |
| 353 | .BR "270 " "90 degrees counter clockwise." |
| 354 | .BR "flipped " "Horizontally flipped" |
| 355 | .BR "flipped-90 " "Flipped and 90 degrees clockwise" |
| 356 | .BR "flipped-180 " "Flipped upside down" |
| 357 | .BR "flipped-270 " "Flipped and 90 degrees counter clockwise" |
| 358 | .fi |
| 359 | .RE |
Rob Bradford | 1449462 | 2013-06-25 18:56:43 +0100 | [diff] [blame] | 360 | .TP 7 |
| 361 | .BI "seat=" name |
| 362 | The logical seat name that that this output should be associated with. If this |
| 363 | is set then the seat's input will be confined to the output that has the seat |
| 364 | set on it. The expectation is that this functionality will be used in a |
| 365 | multiheaded environment with a single compositor for multiple output and input |
| 366 | configurations. The default seat is called "default" and will always be |
| 367 | present. This seat can be constrained like any other. |
| 368 | .RE |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 369 | .SH "INPUT-METHOD SECTION" |
| 370 | .TP 7 |
| 371 | .BI "path=" "/usr/libexec/weston-keyboard" |
| 372 | sets the path of the on screen keyboard input method (string). |
| 373 | .RE |
| 374 | .RE |
| 375 | .SH "KEYBOARD SECTION" |
| 376 | This section contains the following keys: |
| 377 | .TP 7 |
| 378 | .BI "keymap_rules=" "evdev" |
| 379 | sets the keymap rules file (string). Used to map layout and model to input |
| 380 | device. |
| 381 | .RE |
| 382 | .RE |
| 383 | .TP 7 |
| 384 | .BI "keymap_model=" "pc105" |
| 385 | sets the keymap model (string). See the Models section in |
| 386 | .B "xkeyboard-config(7)." |
| 387 | .RE |
| 388 | .RE |
| 389 | .TP 7 |
| 390 | .BI "keymap_layout=" "us,de,gb" |
| 391 | sets the comma separated list of keyboard layout codes (string). See the |
| 392 | Layouts section in |
| 393 | .B "xkeyboard-config(7)." |
| 394 | .RE |
| 395 | .RE |
| 396 | .TP 7 |
| 397 | .BI "keymap_variant=" "euro,,intl" |
| 398 | sets the comma separated list of keyboard layout variants (string). The number |
| 399 | of variants must be the same as the number of layouts above. See the Layouts |
| 400 | section in |
| 401 | .B "xkeyboard-config(7)." |
| 402 | .RE |
| 403 | .RE |
| 404 | .TP 7 |
| 405 | .BI "keymap_options=" "grp:alt_shift_toggle,grp_led:scroll" |
| 406 | sets the keymap options (string). See the Options section in |
| 407 | .B "xkeyboard-config(7)." |
| 408 | .RE |
| 409 | .RE |
Jonny Lamb | 66a41a0 | 2014-08-12 14:58:25 +0200 | [diff] [blame] | 410 | .TP 7 |
| 411 | .BI "repeat-rate=" "40" |
| 412 | sets the rate of repeating keys in characters per second (unsigned integer) |
| 413 | .RE |
| 414 | .RE |
| 415 | .TP 7 |
| 416 | .BI "repeat-delay=" "400" |
| 417 | sets the delay in milliseconds since key down until repeating starts (unsigned |
| 418 | integer) |
| 419 | .RE |
| 420 | .RE |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 421 | .SH "TERMINAL SECTION" |
| 422 | Contains settings for the weston terminal application (weston-terminal). It |
| 423 | allows to customize the font and shell of the command line interface. |
| 424 | .TP 7 |
| 425 | .BI "font=" "DejaVu Sans Mono" |
Wieland Hoffmann | ad0704a | 2014-01-10 22:23:12 +0100 | [diff] [blame] | 426 | sets the font of the terminal (string). For a good experience it is recommended |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 427 | to use monospace fonts. In case the font is not found, the default one is used. |
| 428 | .RE |
| 429 | .RE |
| 430 | .TP 7 |
| 431 | .BI "font-size=" "14" |
| 432 | sets the size of the terminal font (unsigned integer). |
| 433 | .RE |
| 434 | .RE |
| 435 | .TP 7 |
| 436 | .BI "term=" "xterm-256color" |
| 437 | The terminal shell (string). Sets the $TERM variable. |
| 438 | .RE |
| 439 | .RE |
Maksim Melnikau | 92de144 | 2013-08-14 22:33:10 +0300 | [diff] [blame] | 440 | .SH "XWAYLAND SECTION" |
| 441 | .TP 7 |
| 442 | .BI "path=" "/usr/bin/Xorg" |
| 443 | sets the path to the xserver to run (string). |
| 444 | .RE |
| 445 | .RE |
Martin Minarik | edc51c0 | 2013-01-18 18:44:29 +0100 | [diff] [blame] | 446 | .SH "SEE ALSO" |
| 447 | .BR weston (1), |
| 448 | .BR weston-launch (1), |
| 449 | .BR weston-drm (7), |
| 450 | .BR xkeyboard-config (7) |