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