Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 177 insertions, 0 deletions

diff --git a/ksmserver/README b/ksmserver/README
new file mode 100644
index 000000000..1c74111ae
--- /dev/null
+++ b/ksmserver/README
@@ -0,0 +1,177 @@
+KDE session manager  (ksmserver)
+--------------------------------
+
+Matthias Ettrich <[email protected]>
+Lubos Lunak <[email protected]>
+
+ksmserver is KDE's new session management server. It talks the
+standard X11R6 session management protocol (XSMP).  Thus, in theory,
+it should be compatible with all session managment compliant X11R6
+applications. Unfortunately, there aren't that many of them. To be
+precise, I have never seen a single commercial application that
+supports it and even within the official X11R6 distribution, 'xclock'
+is the only exception. Nevertheless we've chosen to support XSMP
+despites the complexity of the protocol in order to provide KDE users
+more interoperability with applications that were not explicitely
+written with KDE in mind. XSMP, as an official X standard, promised to
+be more likely to be supported by third parties than even a superior
+KDE-specific protocol. Let's see whether we were right and more
+applications will actually talk XSMP. At least all KDE applications do
+now.
+
+Here's a short overview on how session management works.
+
+Starting the server
+-------------------
+
+The server is usually started from the 'startkde' script. It supports the following options:
+
+  -r, --restore             Restores the previous session if available
+  -w, --windowmanager <wm>  Starts 'wm' in case no other window manager is
+                            participating in the session. Default is 'kwin'
+
+The default 'startkde' launches 'ksmserver --restore'.  The
+'windowmanager' option is useful for users that prefer a window
+manager other than kwin. Since the window manager has to participate
+in the session (it has to remember window positions and states), it is
+usually restarted when the session is restored. To be *really* sure
+that this happens, even if the wm might have crashed during the
+previous session, ksmserver ensures that. The option specifies, which
+windowmanager shall be launched for sure. But again: if the stored
+session contains a window manager, the restored one will be used, not
+the specified one. As a special feature, ksmserver always starts the
+specified window manager first, which results in a much nicer startup
+sequence (less flashy).
+
+KDE startup sequence
+--------------------
+
+Ksmserver controls the second part of the KDE startup sequence,
+after it gets control from the startkde script, which controls
+the first part of the startup sequence. All code related to startup
+should be in startup.cpp and going down in that source file should
+follow the startup order (but note that this is just a documentation
+which may get outdated, so in case of doubts the source wins ;) ).
+
+The startkde scripts already launches kdeinit, which in turns launches
+KDE daemons like dcopserver, klauncher and kded. Kded loads autoloaded
+kded modules, i.e. those that have X-KDE-Kded-autoload=true in .desktop
+files. The exact way autoloading works is controlled by X-KDE-Kded-phase=,
+which may be 0, 1 or 2 (the default). Kded phase 0 means the module is
+always loaded by kded, even outside of KDE session. It should used only
+by kded modules which must be always running. Kded phase 1 modules are
+loaded right after kded startup, but only during KDE startup, i.e. it is
+for modules that are always needed by the KDE session. Phase 2 modules
+will be loaded later.
+
+Startkde also launches kcminit, which performs initialization done by kcontrol
+modules. There are three kcminit phases, 0, 1 and 2, controlled
+by X-KDE-Init-Phase= in the .desktop file, which defaults to 1. Phase 0 kcminit
+modules should be only those that really need to be run early in the startup
+process (and those should probably actually use kstartupconfig in startkde
+to be done even before kdeinit and daemons). After executing phase 0
+modules kcminit returns and waits.
+
+When ksmserver is launched, the first thing it does is launching
+the window manager, as the WM is necessary before any windows are possibly
+shown. When the WM is ready, ksmserver tells klauncher to perform autostart
+phase 0 ($KDEHOME/share/autostart). There are 3 autostart phases, 0, 1 and 2,
+defined by X-KDE-autostart-phase, defaulting to 2. Phase 0 is reserved only
+for the actual visible base components of KDE, i.e. KDesktop and Kicker,
+in order to make the startup appear visually faster. Both KDesktop and Kicker
+use DCOP calls suspendStartup() and resumeStartup() to make ksmserver stay
+waiting for autostart phase 0 until both KDesktop and Kicker are ready.
+
+Next step is telling the waiting kcminit to perform phase 1 - all kcminit
+modules that should be executed before KDE startup is considered done.
+After that ksmserver tells klauncher to perform autostart phase 1,
+i.e. launching normal components of KDE that should be available right
+after KDE startup, and after this session restore is performed,
+i.e. launching all applications that were running during last session
+saving (usually logout).
+
+By this time KDE session is considered to be more or less ready and
+ksmserver does the knotify startkde event (i.e. plays the login sound).
+It also tells klauncher to perform autostart phase 2, kded to load all
+remaining autoload (i.e. kded phase 2) modules, kcminit to execute
+kcminit phase 2 (kcontrol modules that do initialization that can wait,
+like launching daemons) and kdesktop to execute the user Autostart folder.
+
+Technical note: There's a reason why kded modules and items in autostart
+default to the latest phase. Before you explicitly use a different phase,
+read and understand what's above. You should also consider whether something
+really needs to be launched during KDE startup and can't be loaded on-demand
+when really needed. Abusing the phases will result in public spanking
+for making KDE startup slower.
+
+
+Establishing the connection
+---------------------------
+
+As required by the XSMP specification, the session management server
+propagates its network address in the SESSION_MANAGER environment
+variable. Probably not the best way to do it, but it's the way it
+is. All KDE (and plain Qt) applications simply read this variable and
+try to establish a connection to an XSMP server at this address. If
+the variable is undefined, nothing happens.
+
+This means, if you want to start a program that should not participate
+in the session, simply undefine SESSION_MANAGER in your terminal
+window and launch the application. If you want to see an application
+desparately trying to connect to something, try setting it to some
+bogus value.
+
+In addition, ksmserver propagates both its network address and its
+process id in ~/.kde/socket-$HOSTNAME/KSMserver-$DISPLAY. A
+utility function KApplication::propagateSessionManager() reads this
+setting and sets SESSION_MANAGER accordingly, so that child processes
+can pick it up.  The function is called by clients that are started
+outside the session ( i.e. before ksmserver is started), but want to
+launch other processes that should participate in the session.
+Examples are kdesktop or kicker, see below.
+
+Authorization
+-------------
+
+XSMP is, just like DCOP, built on top of the Inter Client Exchange
+(ICE) protocol, which comes standard as a part of X11R6 and later.
+Authorization is done using 'iceauth', with MIT-MAGIC-COOKIE as used
+by X. In order to be able to access the session management server, you
+need to be able to read ~/.ICEauthority. For security reasons, we do
+not provide any host-based authorization (neither does DCOP, btw.).
+
+
+Requesting a shutdown
+---------------------
+
+If an application wants to request a shutdown (i.e. a logout), it does
+this via an SmcRequestSaveYourself message to the server. In KDE, a
+utility function KApplication::requestShutDown() does exactly
+this. It's for example called by KDE's panel or by the context menu of
+the desktop.
+
+
+User Interface
+--------------
+
+ksmserver has a very straight-forward user interface.  It mainly asks
+the question "Shutdown KDE Session?" and provides two obvious command
+buttons "Yes" and "Cancel". The interesting bit is the additonal
+checkbox that says "Restore session when logging in next time". The
+checkbox remembers state within session, so simply use whatever you
+prefer.  For those who remember, this was one of the main questions
+with KDE-1.x ("How to get rid of session managment?"). With KDE-2.x,
+most users will probably prepare a session once, store it with the
+checkbox enabled and keep the checkbox disabled in the future. This
+way you get a proper and clean 'homesession' each time.
+
+
+Troubleshooting
+---------------
+
+If you experience trouble like 'logout does not work anymore' or 'I
+cannot start new applications', as a result of a previous crash,
+ensure that ksmserver is indeed not running anymore and remove the
+file ~/.kde/socket-$HOSTNAME/KSMserver-$DISPLAY. Shouldn't be necessry, 
+but one never knows.
+