blob: fbcec81adad929174c87a276916c3da7b4c6671a [file] [log] [blame]
Martin Minarikedc51c02013-01-18 18:44:29 +01001.\" 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
5weston.ini \- configuration file for
6.B Weston
7\- the reference Wayland
8compositor
9.SH INTRODUCTION
10.B Weston
11obtains configuration from its command line parameters and the configuration
12file described here.
13.SH DESCRIPTION
14.B Weston
15uses a configuration file called
16.I weston.ini
17for its setup.
18The
19.I weston.ini
20configuration file is searched for in one of the following places when the
21server 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 Othmana50e6e42013-05-14 09:48:26 -070027.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 Minarikedc51c02013-01-18 18:44:29 +010031.fi
32.RE
33.PP
34where environment variable
35.B $HOME
36is the user's home directory, and
37.B $XDG_CONFIG_HOME
Ossama Othmana50e6e42013-05-14 09:48:26 -070038is the user specific configuration directory, and
39.B $XDG_CONFIG_DIRS
40is a colon
41.B ':'
42delimited listed of configuration base directories, such as
43.BR /etc/xdg-foo:/etc/xdg .
Martin Minarikedc51c02013-01-18 18:44:29 +010044.PP
45The
46.I weston.ini
47file is composed of a number of sections which may be present in any order, or
48omitted 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
59The spaces are significant.
60Comment lines are ignored:
61.PP
62.RS 4
63.nf
64.IR "#comment"
65.fi
66.RE
67.PP
68The 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 Melnikau92de1442013-08-14 22:33:10 +030080.BR "xwayland " "XWayland options"
Martin Minarikedc51c02013-01-18 18:44:29 +010081.fi
82.RE
83.PP
84Possible value types are string, signed and unsigned 32-bit
85integer, and boolean. Strings must not be quoted, do not support any
86escape sequences, and run till the end of the line. Integers can
87be 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"
91The
92.B core
93section is used to select the startup compositor modules.
94.TP 7
Nobuhiko Tanibata88419172014-02-10 12:15:11 +090095.BI "shell=" desktop-shell.so
96specifies a shell to load (string). This can be used to load your own
97implemented shell or one with Weston as default. Available shells
98in the
Martin Minarikedc51c02013-01-18 18:44:29 +010099.IR "__weston_modules_dir__"
100directory are:
101.PP
102.RS 10
103.nf
104.BR desktop-shell.so
Nobuhiko Tanibata88419172014-02-10 12:15:11 +0900105.fi
106.RE
107.TP 7
108.TP 7
109.BI "modules=" xwayland.so,cms-colord.so
110specifies the modules to load (string). Available modules in the
111.IR "__weston_modules_dir__"
112directory are:
113.PP
114.RS 10
115.nf
Martin Minarikedc51c02013-01-18 18:44:29 +0100116.BR xwayland.so
Nobuhiko Tanibata88419172014-02-10 12:15:11 +0900117.BR cms-colord.so
Martin Minarikedc51c02013-01-18 18:44:29 +0100118.fi
119.RE
Kristian Høgsberg8e6f3762013-10-16 16:31:42 -0700120.TP 7
Lubomir Rintelba44c6b2013-11-15 14:18:15 +0100121.TP 7
122.BI "backend=" headless-backend.so
123overrides defaults backend. Available backend modules in the
124.IR "__weston_modules_dir__"
125directory 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øgsberg8e6f3762013-10-16 16:31:42 -0700138.BI "gbm-format="format
139sets the GBM format used for the framebuffer for the GBM backend. Can be
140.B xrgb8888,
141.B xrgb2101010,
142.B rgb565.
143By default, xrgb8888 is used.
Martin Minarikedc51c02013-01-18 18:44:29 +0100144.RS
145.PP
146
147.SH "SHELL SECTION"
148The
149.B shell
150section is used to customize the compositor. Some keys may not be handled by
151different shell plugins.
152.PP
153The entries that can appear in this section are:
154.TP 7
Emilio Pozuelo Monfort46ce7982013-11-20 13:22:29 +0100155.BI "client=" file
156sets the path for the shell client to run. If not specified
Emilio Pozuelo Monfort8a81b832013-12-02 12:53:32 +0100157.I __weston_shell_client__
158is launched (string).
Emilio Pozuelo Monfort46ce7982013-11-20 13:22:29 +0100159.TP 7
Martin Minarikedc51c02013-01-18 18:44:29 +0100160.BI "background-image=" file
161sets the path for the background image file (string).
162.TP 7
Emilio Pozuelo Monfortf12a0942013-04-22 11:00:07 +0200163.BI "background-type=" tile
Pekka Paalanena402b052013-05-22 18:03:10 +0300164determines how the background image is drawn (string). Can be
165.BR scale ", " scale-crop " or " tile " (default)."
166Scale means scaled to fit the output precisely, not preserving aspect ratio.
167Scale-crop preserves aspect ratio, scales the background image just big
168enough to cover the output, and centers it. The image ends up cropped from
169left and right, or top and bottom, if the aspect ratio does not match the
170output. Tile repeats the background image to fill the output.
Emilio Pozuelo Monfortf12a0942013-04-22 11:00:07 +0200171.TP 7
Martin Minarikedc51c02013-01-18 18:44:29 +0100172.BI "background-color=" 0xAARRGGBB
173sets the color of the background (unsigned integer). The hexadecimal
174digit pairs are in order alpha, red, green, and blue.
175.TP 7
176.BI "panel-color=" 0xAARRGGBB
177sets the color of the panel (unsigned integer). The hexadecimal
178digit 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 Lambe67118c2014-08-12 15:07:51 +0200189.BI "panel-location=" top
190sets the location of the panel (string). Can be
191.B top,
192.B none.
193.TP 7
Martin Minarikedc51c02013-01-18 18:44:29 +0100194.BI "locking=" true
195enables screen locking (boolean).
196.TP 7
197.BI "animation=" zoom
198sets the effect used for opening new windows (string). Can be
199.B zoom,
Kristian Høgsberg724c8d92013-10-16 11:38:24 -0700200.B fade,
201.B none.
202By default, no animation is used.
203.TP 7
Jonny Lambf322f8e2014-08-12 15:13:30 +0200204.BI "close-animation=" fade
205sets the effect used when closing windows (string). Can be
206.B fade,
207.B none.
208By default, the fade animation is used.
209.TP 7
Kristian Høgsberg724c8d92013-10-16 11:38:24 -0700210.BI "startup-animation=" fade
211sets the effect used for opening new windows (string). Can be
212.B fade,
213.B none.
214By default, the fade animation is used.
Martin Minarikedc51c02013-01-18 18:44:29 +0100215.TP 7
Emilio Pozuelo Monfortbb835b42013-11-20 13:22:30 +0100216.BI "focus-animation=" dim-layer
217sets the effect used with the focused and unfocused windows. Can be
218.B dim-layer,
219.B none.
220By default, no animation is used.
221.TP 7
Martin Minarikedc51c02013-01-18 18:44:29 +0100222.BI "binding-modifier=" ctrl
223sets the modifier key used for common bindings (string), such as moving
224surfaces, resizing, rotating, switching, closing and setting the transparency
225for windows, controlling the backlight and zooming the desktop. Possible values:
226ctrl, alt, super (default)
227.TP 7
228.BI "num-workspaces=" 6
229defines the number of workspaces (unsigned integer). The user can switch
230workspaces by using the
231binding+F1, F2 keys. If this key is not set, fall back to one workspace.
232.TP 7
Emilio Pozuelo Monfort57ac4062013-03-14 17:23:38 +0100233.BI "cursor-theme=" theme
234sets the cursor theme (string).
235.TP 7
236.BI "cursor-size=" 24
237sets the cursor size (unsigned integer).
238.TP 7
Martin Minarikedc51c02013-01-18 18:44:29 +0100239.BI "lockscreen-icon=" path
240sets the path to lock screen icon image (string). (tablet shell only)
241.TP 7
242.BI "lockscreen=" path
243sets the path to lock screen background image (string). (tablet shell only)
244.TP 7
245.BI "homescreen=" path
246sets the path to home screen background image (string). (tablet shell only)
247.RE
248.SH "LAUNCHER SECTION"
249There can be multiple launcher sections, one for each launcher.
250.TP 7
251.BI "icon=" icon
252sets the path to icon image (string). Svg images are not currently supported.
253.TP 7
254.BI "path=" program
255sets the path to the program that is run by clicking on this launcher (string).
256It is possible to pass arguments and environment variables to the program. For
257example:
258.nf
259.in +4n
260
261path=GDK_BACKEND=wayland gnome-terminal --full-screen
262.in
263.fi
264.PP
265.RE
266.SH "SCREENSAVER SECTION"
267The
268.B screensaver
269section is used to select and schedule a screensaver.
270The
271.B screensaver
272section is optional, as are all of the entries that may be specified in
273it.
274.TP 7
275.BI "path=" /usr/libexec/weston-screensaver
276This instructs the compositor to use the selected screensaver client on a given
277path (string). If this line is missing or commented out, the screensaver in
278.B "weston(1)"
279is disabled.
280.RE
281.TP 7
282.BI "duration=" 600
283The idle time in seconds until the screensaver disappears in order to save power
284(unsigned integer).
285.SH "OUTPUT SECTION"
286There can be multiple output sections, each corresponding to one output. It is
287currently only recognized by the drm and x11 backends.
288.TP 7
289.BI "name=" name
290sets a name for the output (string). The backend uses the name to
Jason Ekstrand48ce4212013-10-27 22:25:02 -0500291identify the output. All X11 output names start with a letter X. All
292Wayland output names start with the letters WL. The available
Martin Minarikedc51c02013-01-18 18:44:29 +0100293output names for DRM backend are listed in the
294.B "weston-launch(1)"
295output.
296Examples 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 Ekstrand48ce4212013-10-27 22:25:02 -0500303.BR "WL1 " "Wayland backend, Wayland window no.1"
Martin Minarikedc51c02013-01-18 18:44:29 +0100304.fi
305.RE
306.RS
307.PP
308See
309.B "weston-drm(7)"
310for more details.
311.RE
312.TP 7
313.BI "mode=" mode
314sets the output mode (string). The mode parameter is handled differently
315depending on the backend. On the X11 backend, it just sets the WIDTHxHEIGHT of
316the weston window.
317The 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
329Optionally, an user may specify a modeline, such as:
330.PP
331.nf
332.in +4n
333.nf
334173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
335.fi
336.in
337.PP
338It consists of the refresh rate in Hz, horizontal and vertical resolution,
339options for horizontal and vertical synchronisation. The program
340.B "cvt(1)"
341can provide suitable modeline string.
342.RE
343.TP 7
344.BI "transform=" normal
345The transformation applied to screen output (string). The transform key can
346be 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 Bradford14494622013-06-25 18:56:43 +0100360.TP 7
361.BI "seat=" name
362The logical seat name that that this output should be associated with. If this
363is set then the seat's input will be confined to the output that has the seat
364set on it. The expectation is that this functionality will be used in a
365multiheaded environment with a single compositor for multiple output and input
366configurations. The default seat is called "default" and will always be
367present. This seat can be constrained like any other.
368.RE
Martin Minarikedc51c02013-01-18 18:44:29 +0100369.SH "INPUT-METHOD SECTION"
370.TP 7
371.BI "path=" "/usr/libexec/weston-keyboard"
372sets the path of the on screen keyboard input method (string).
373.RE
374.RE
375.SH "KEYBOARD SECTION"
376This section contains the following keys:
377.TP 7
378.BI "keymap_rules=" "evdev"
379sets the keymap rules file (string). Used to map layout and model to input
380device.
381.RE
382.RE
383.TP 7
384.BI "keymap_model=" "pc105"
385sets 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"
391sets the comma separated list of keyboard layout codes (string). See the
392Layouts section in
393.B "xkeyboard-config(7)."
394.RE
395.RE
396.TP 7
397.BI "keymap_variant=" "euro,,intl"
398sets the comma separated list of keyboard layout variants (string). The number
399of variants must be the same as the number of layouts above. See the Layouts
400section in
401.B "xkeyboard-config(7)."
402.RE
403.RE
404.TP 7
405.BI "keymap_options=" "grp:alt_shift_toggle,grp_led:scroll"
406sets the keymap options (string). See the Options section in
407.B "xkeyboard-config(7)."
408.RE
409.RE
Jonny Lamb66a41a02014-08-12 14:58:25 +0200410.TP 7
411.BI "repeat-rate=" "40"
412sets the rate of repeating keys in characters per second (unsigned integer)
413.RE
414.RE
415.TP 7
416.BI "repeat-delay=" "400"
417sets the delay in milliseconds since key down until repeating starts (unsigned
418integer)
419.RE
420.RE
Martin Minarikedc51c02013-01-18 18:44:29 +0100421.SH "TERMINAL SECTION"
422Contains settings for the weston terminal application (weston-terminal). It
423allows to customize the font and shell of the command line interface.
424.TP 7
425.BI "font=" "DejaVu Sans Mono"
Wieland Hoffmannad0704a2014-01-10 22:23:12 +0100426sets the font of the terminal (string). For a good experience it is recommended
Martin Minarikedc51c02013-01-18 18:44:29 +0100427to 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"
432sets the size of the terminal font (unsigned integer).
433.RE
434.RE
435.TP 7
436.BI "term=" "xterm-256color"
437The terminal shell (string). Sets the $TERM variable.
438.RE
439.RE
Maksim Melnikau92de1442013-08-14 22:33:10 +0300440.SH "XWAYLAND SECTION"
441.TP 7
442.BI "path=" "/usr/bin/Xorg"
443sets the path to the xserver to run (string).
444.RE
445.RE
Martin Minarikedc51c02013-01-18 18:44:29 +0100446.SH "SEE ALSO"
447.BR weston (1),
448.BR weston-launch (1),
449.BR weston-drm (7),
450.BR xkeyboard-config (7)