Move new lxsession with built-in settings daemon to trunk.
[lxde/lxsession.git] / README
CommitLineData
f8d2bceb 1LXSession is the default session manager of LXDE.
dd69beb8 2(LXDE: Lightweight X11 Desktop Environment)
a2d20055 3http://lxde.org/
dd69beb8
FC
4
5What's LXSession and who needs this?
6A session manager is used to automatically start a set of applications and
644fd872 7set up a working desktop environment.
f8d2bceb
HJYP
8Besides, LXSession has a built-in lightweight Xsettings daemon, which can
9configure gtk+ themes, keyboard, and mouse for you on session startup.
10In gnome the Xsettings part is provided by gnome-settings-daemon.
dd69beb8 11
644fd872 12Gnome is bundled with its own gnome-session, KDE brings its own session
dd69beb8
FC
13manager, too. XFCE and ROX desktop also have their own session managers,
14xfce4-session and rox-session.
15
644fd872
HJYP
16LXSession can start a set of programs specified by the distribution
17makers or users. Furthermore, LXSession is more advanced than
18some of the other ones because it can ``guard'' the specified
19programs, and get them restarted if crashes happened.
20
21Besides, the major difference between LXSession and the preceding programs
df011ff6 22is that LXSession is lightweight, and it's not tighted to "any" desktop environment.
dd69beb8
FC
23It's desktop-independent and can be used with any window manager.
24With proper configuration, you can make your own desktop environment with
25LXSession. This is very useful to the users and developers of non-mainstream
df011ff6 26window managers and desktop environments.
dd69beb8 27
644fd872 28Here we use our own desktop environment LXDE as a working example
dd69beb8
FC
29to tell you, step by step, how to create your own new desktop environment.
30
31Create a startup script for your desktop, and put it to /usr/bin.
32For example, we create a script '/usr/bin/startlxde'.
33
644fd872 34Then, add the commands you want to execute *before* LXSession,
dd69beb8
FC
35such as setting up locales or others, and put "exec lxsession" in the last line.
36
37For example, our startlxde script looks like this:
38
39#!/bin/sh
40exec /usr/bin/lxsession -s LXDE
41
42Apparently, LXDE is the name of our desktop.
43Replace it with the name of your desktop.
44
45Then, make a desktop entry file for it under '/usr/share/xsessions'.
46With this, you can select this desktop session from menu in GDM.
47For example, this is the content of our LXDE.desktop:
48
49[Desktop Entry]
50Encoding=UTF-8
51Name=LXDE
52Comment=LXDE - Lightweight X11 desktop environment
53Exec=/usr/bin/startlxde
54Type=Application
55
df011ff6 56Apparently, you can replace the name and description with your own.
dd69beb8
FC
57Exec should points to the startup script created in previous step.
58
59Now you get an item 'LXDE' in the list of available sessions in gdm.
60NOTE: Restart of gdm might be needed. ( On Debian: sudo /etc/init.d/gdm restart )
61
df011ff6 62So, what programs will be executed when LXSession starts?
644fd872
HJYP
63The window manager, of course, should be the most important one.
64It should be specified in this file:
f8d2bceb
HJYP
65/etc/xdg/lxsession/<Name of Your Desktop>/desktop.conf
66The file is a plain ini file, like the desktop.conf.example
67bundled in this package.
dd69beb8 68
644fd872
HJYP
69Then, list the other programs you want to execute in this file:
70/etc/xdg/lxsession/<Name of Your Desktop>/autostart
dd69beb8 71
644fd872
HJYP
72For example, our /etc/xdg/lxsession/LXDE/default looks like this:
73@lxde-settings
74@lxpanel -p LXDE
75@pcmanfm -d
dd69beb8 76
644fd872 77lxpanel is our desktop panel, you can replace it with anything you like,
dd69beb8 78such as avant window manager or others.
dd69beb8 79List other applications you want to launch, one command per line.
dd69beb8
FC
80Note that there is no '&' at the end of every line since this is not a
81shell script. Don't append & at the end of any line.
644fd872
HJYP
82Since this is not a shell script, shell expansion like ~ or $HOME won't
83work. If you need this, write a script and do the shell things there,
84than list the script here in the autostart file.
85
86If a line starts with @, the program will be guarded by lxsession.
87That means: If the program crashes, it should be automatically restarted.
88If the program is terminated normally, or is terminated because it
89receives SIGTERM or SIGKILL, then the reload won't happen.
90
91The default system-wide config files under /etc/xdg/lxsession, can be
92overriden by user-specific ones. If the user specific config files are
93found in ~/.config/lxsession, the ones in /etc/xdg/lxsession will be overriden.
94So this leave some flexibility for the users.
95
96Another way to start programs on session startup is to add their *.desktop
97files in ~/.config/autostart. Please refer to the Autostart spec.
98http://www.freedesktop.org/wiki/Specifications/autostart-spec
dd69beb8
FC
99
100OK, it's time to login to your desktop environment. Please try it out.
101Wait! How to logout from LXSession?
102
103Simply executing this command:
104lxsession-logout
105
df011ff6 106This will give you a good-looking logout dialog.
dd69beb8
FC
107If gdm is installed, lxsession can do shutdown/reboot/suspend via gdm.
108(These options are not available if gdm is not running.)
109
110If you want to customize this logout box further, try this:
111lxsession-logout --prompt "Your custom message" --banner "Your logo" \
112--side "left | top | right | bottom (The position of the logo)"
113
114We create a script '/usr/bin/lxde-logut' to do this:
115#!/bin/sh
116/usr/bin/lxsession-logout --banner "/usr/share/lxde/images/logout-banner.png" --side top
117
118You can put this logout script in the menu of your window manager or desktop panel.
119Then, you can logout via clicking from the menu.
120
121Have fun!