Version: 1.80 - By: katmai

Table of Contents
        What is LiteSpawn?
        What's a Shell Manager?
        Installing LiteSpawn
        Uninstalling LiteSpawn
        Setting Up the Configuration File
        Specifying Alternate Shells
        Choosing a Shell at Startup
        Setting the Startup Timeout Value
        Setting the Termination Timeout Value
        Setting the Keyboard Interrupt Delay
        Configuring LiteStep Theme Preferences
        Swapping LiteStep Themes on the Fly
        Command Line Options
        Tips, Tricks and Things to be Aware of
        Change Log
        Scary Legal Stuff

What is LiteSpawn?
LiteSpawn is a shell manager for use with LiteStep, one of the coolest shell replacements around for the Windows platform. It has been designed to be small, fast and very unobtrusive.

LiteSpawn mimics much of the functionality of cael's excellent LoneRunner utility but goes a step further in that it will allow you to set up individual shell preferences for different user's and it allows you to switch between shells on the fly. It will allow you to setup and monitor shells other than LiteStep and Explorer on a per-user basis and allows each user under LiteStep to have his or her own theme preference as well as the ability to swap themes on the fly.

What's a shell manager all about?
As far as Windows is concerned, LiteSpawn is your shell. But once started, it spawns the shell of your choice (based on settings in the LiteSpawn.cfg file) and then transparently monitors that shell (either LiteStep or explorer) in the background. If the shell should crash, it will catch it and give you the option of restarting that shell, starting a different one, rebooting, logging off or shutting down the machine completely.

Among it's more notable features are the following:
  • Allows each user that logs in to specify a different shell.
  • Allows a default shell to be specified for user's not listed in the .cfg file.
  • Prevents having to reboot when your shell bites the dust.
  • Allows you to quickly reboot, shutdown or logoff.
  • Allows you to switch back and forth between shells on the fly!
  • Works well under both 95/98 AND NT.
  • Allows each user under LiteStep to specify a different theme.
  • Let's you swap themes on the fly.
  • Provides crash protection for shells other than LiteStep and Explorer.

Installing LiteSpawn
Installing LiteSpawn is a snap. Simply create a directory (i.e. c:\litespawn) and extract the LiteSpawn files to that directory. Then, from a command prompt run Litespawn with the -install option.
c:\litespawn\LiteSpawn -install
This will set LiteSpawn as your shell. Next you need to futz around with the .cfg file to set up your personal preferences (see below) and then, after a quick reboot, you're ready to go...

For those of you that have been burnt by programs mucking about with your system setup while you weren't looking, here is EXACTLY what the -install option does to your system:

  • Opens your system.ini file (found the windows directory), finds the [boot] section and replaces the shell entry with the full path to LiteSpawn.
  • Modifies the registry entry:
    "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\shell"
    to point to the LiteSpawn executable.
  • Modifies the registry entry:
    "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\AutoRestartShell"
    with a value of 0.
  • Deletes the registry entry:
    "HKCU\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\shell"
    if it exists.
Uninstalling LiteSpawn
Uninstalling LiteSpawn is just as easy. Simply run Litespawn with the -uninstall option.
c:\litespawn\litespawn -uninstall
This will set your default shell as the new shell.

Setting up the configuration file
The config file is where you specify all of LiteSpawn's options. There are two mandatory sections to this file, [LiteSpawn] and [default]. In the [LiteSpawn] section you need to specify two directives: litestep_exe and explorer_exe. These two directives specify the explicit path to where your explorer executable and your LiteStep executable resides. For example:
explorer_exe = c:\winnt\explorer.exe
litestep_exe = c:\litestep\litestep.exe
The second section, [default] will contain one entry: shell that points to either explorer_exe or litestep_exe. For example:
shell = litestep_exe
Additional sections can also be added for each user that logs into that machine to allow each user to specify their shell preference. This is especially handy under NT. For example if there are three users with the UserNames: katmai, mrgates and joeblow, and they all use the same PC, three sections can be added as follows:
shell = litestep_exe

shell = explorer_exe

shell = litestep_exe
When katmai or joeblow log in, LiteSpawn will start LiteStep. If mrgates logs in, then explorer will start. If the currently logged in user doesn't have a preference set up then the shell listed under [default] will be used.

Specifying alternate shells
If you are reading this, chances are you are into the whole Win32 shell development scene. Although LiteSpawn has been developed specifically with LiteStep in mind, there are many other new shells being developed such as Dimension, EVWM and Reveal that could benefit from LiteSpawns user configurability and crash protection features. For this reason LiteSpawn now has alternate shell support.

In the LiteSpawn.cfg file you may add up to five alternate shells under the [Alternate_Shells] section. Here you list shells by their name and the path to the executable using the following syntax:
altshell_name_x = "Shell Name"
altshell_path_x = "path\to\shell\executable"
For example a typical shell connoisseur might have the following in litespawn.cfg:
altshell_name_1 = "Reveal"
altshell_path_1 = "c:\reveal\reveal.exe"

altshell_name_2 = "Dimension"
altshell_path_2 = "c:\dimension\d.exe"

altshell_name_3 = "EVWM"
altshell_path_3 = "c:\evwm\evwm.exe"
Each user may now specify one of these shells as the one to start when they login by setting the shell directive to the name of the alternate shell rather than litestep_exe or explorer_exe:
shell = "Reveal"

shell = explorer_exe

shell = "Dimension"
LiteSpawn will provide full crash protection for each shell and most of the LiteSpawn commands such as -kill and -restart will work with no problems. Note, however, that swapping from an alternate shell on the fly is not supported.

Choosing a Shell at Startup
If you would like to be prompted at start up as to which shell to spawn you can use the ask_boot directive in your LiteSpawn.cfg. For example:
shell = litestep_exe
ask_boot = 1
Now when john logs in, a dialog box will pop up and prompt him as to which shell to start. If this flag is not present or is 0 then the default shell listed above will start automatically. Note that even if this flag is specified, a shell entry must still be provided.

The third option "Start Other..." provides a nice and quick way of selecting an alternate shell on the fly without setting it up in the litespawn.cfg file in advance. Clicking on this entry will popup a dialog that will let you browse for an executable to start as your shell. If an alternate shell is set as the default shell for that user as described above then this option will show the name of that alternate shell, for example: "Start EVWM"

Selecting "Terminate after spawn" from this dialog will cause LiteSpawn to start the selected shell and then immediately terminate itself. This is useful if you want a shell to start and have it be the ONLY process running on the machine (other than the Windows kernel itself of course).

If you would like LiteSpawn to ALWAYS terminate itself without having to manually check the Terminate after spawn box each time, you can specify the self_terminate option in LiteSpawn.cfg. For example:
shell = litestep_exe
self_terminate = 1
This tells litespawn to spawn LiteStep as the shell and then immediately terminate and remove itself from memory. Note that once LiteSpawn has terminated crash protection will be disabled and you will not be able to perform any LiteSpawn functions such as swapping shells or themes.

If this value is either 0 or not specified then LiteSpawn will continue to run after spawning the shell.

Setting the Startup Timeout Value
A timeout value: start_delay can be specified under each user's section. This integer value specifies the number of seconds to wait for the user to select a shell when ask_boot = 1 is present. The countdown timer will be displayed in the titlebar of the startup dialog and, if no item is selected within that amount of time, the default shell will start automatically. For example:
shell = litestep_exe
ask_boot = 1
start_delay = 10
This will show the startup dialog for ten seconds and then start the default shell if no choice is made in that time. If start_delay is 0 or is not specified then there is no timeout.

Setting the Termination Timeout
By design, LiteSpawn tries to be as nice to the shells that it manages as it can. When swapping shells on the fly it sends the proper messages to each shell to tell it to close itself down. Sometimes, however, the shell (beit LiteStep or Explorer) may be in an unstable state and refuse to acknowledge these shutdown requests. At this point, LiteSpawn will terminate the shell forcefully.

The default behavior is to wait 10 seconds after sending the shutdown request before terminating the shell. This is a good default value for a mid to low end PC with small amounts of RAM since Windows may be busy doing other things and may not get the chance to forward the request to the shell in a timely manner. If you are on a faster PC and the shell seems to be periodically hanging for no good reason (as shells tend to do) then you can specify a different termination timeout value using the kill_delay directive under any user section:
kill_delay = 5
This will tell LiteSpawn to wait 5 seconds for the shell to terminate before getting all medieval on the its ass. If you set kill_delay = 0 then LiteSpawn will simply terminate the shell immediately and not bother sending the QUIT messages at all. This translates to super fast swapping between shells BUT may also lead to system instability over an extended period of time since the shell does not get the opportunity to clean up all of its resources and library connections.

Setting the Keyboard Interrupt Delay
When swapping shells, LiteSpawn will generate a keyboard interrupt to make the shell suppress running the startup items each time. When swapping from Explorer to LiteStep a SHIFT interrupt is generated and when swapping from LiteStep to Explorer a CTRL interrupt is generated. On most machines LiteSpawn is able to determine the appropriate times to depress and release the key when starting the shell but under certain circumstances this may not always work reliably. If you find that swapping from Explorer to LiteStep causes all the startup items to be run a second time then you can override the default detection mechanism and tell LiteSpawn to depress the key for a specific number of seconds using the shift_delay directive under any user section:
shift_delay = 3
This will tell LiteSpawn to wait 3 seconds before sending an interrupt to release the key. Depending on your CPU speed you may have to play around with different values before getting one that works reliably 100% of the time. This is, hopefully, a temporary feature that will be removed once a better startup suppression mechanism is written into LiteStep itself.

Configuring LiteStep Theme Preferences
Due to overwhelming demand, LiteSpawn now supports the ability to define a different LiteStep theme for each user. Up to ten themes can be defined under the [Themes] section of LiteSpawn.cfg using the following syntax:
theme_name_x = "Theme Name"
theme_path_x = "path\to\theme\step.rc\and\modules.ini"
theme_back_x = "path\to\theme\background\image"
theme_mode_x = "tile" | "stretch" | "center"
theme_disp_x = (x_res,y_res)
For example:
theme_name_1 = "Deception"
theme_path_1 = "c:\litestep\themes\decept"
theme_back_1 = "c:\litestep\themes\decept\background.bmp"
theme_mode_1 = "tile"
theme_disp_1 = (1024,768)

theme_name_2 = "NeXTStep"
theme_path_2 = "c:\litestep\themes\NeXTStep"
theme_back_2 = "c:\litestep\themes\NeXTStep\wallpaper.bmp"
theme_mode_2 = "center"
theme_disp_2 = (1152,864)
Now the theme for each user can be specified using the theme directive in each user section as follows:
shell = litestep_exe
theme = "Deception"

shell = litestep_exe
theme = "NeXTStep"
When fred logs in, LiteSpawn will copy the Step.rc and (if present) the modules.ini files from "c:\litestep\themes\decept" into the LiteStep directory and then change the background image to "c:\litestep\themes\decept\background.bmp". The background is not actually changed in the system so after a reboot, the previous background image will still be intact. Just to be on the safe side, LiteSpawn makes a backup copy of the step.rc and modules.ini in the LiteStep directory before it overwrites them with the new ones. These can be found in the LiteSpawn directory as Previous_Step.rc and Previous_Modules.ini.

Swapping LiteStep Themes on the Fly
LiteSpawn now also allows you to swap themes on the fly. Similar to swapping shells, you can pass LiteSpawn a -swaptheme option after LiteSpawn is loaded and running and it will seamlessly install the new theme, change the background and reload LiteStep for you.

If there are only two themes defined in litespawn.cfg then LiteSpawn will automatically toggle between the two. If there are more than two, a dialog will popup and allow you to choose the theme that you want to load. If you change your mind you can back out of this dialog by hitting ESCAPE or the close button in the upper right corner.

Command-line options
Once LiteSpawn has been installed and is running, you can run LiteSpawn again with several command-line options to tell it to do different things. If you run LiteSpawn again after it has already started it will read the option, send the message to the already running instance and then quit. This lets you bind LiteSpawn to a popup, a Wharf item or a HotKey under LiteStep. For example, the following in your step.rc will instantly swap shells whenever you hit Win-S.
*Hotkey Win S "C:\LiteSpawn\LiteSpawn.exe" -swap
or if you wanted a reeeeal fast (seriously man, no prompts or nuthin!) way of shutting down:
*Hotkey Win Q "C:\LiteSpawn\LiteSpawn.exe" -shutdown
The full list of options is as follows:

Option Description
-kill Will instantly kill the current shell. Real handy if your debugging LiteStep and want to restart. Probably not very handy otherwise :)
-logoff Will instantly log you off.
-nuke Terminates both your shell AND LiteSpawn at the same time. (Definitely not recommended for the average user...)
-quit Will quit LiteSpawn but leave the shell running
-reboot Will instantly reboot your machine.
-restart Terminates and restarts the current shell. (Sort'of like a recycle on steroids)
-shutdown Will instantly shut your machine down.
-swap Will instantly stop the current shell and start the other.
-swaptheme Swaps LiteStep themes on the fly.

Tips, tricks and things to be aware of
aww, you didn't think you'd get away that easy did you? Here are the current "issues" that I'm aware of. If you think you have something else not on this list then by all means let me know
  • You cannot swap from LiteStep to Explorer while an explorer window is open.
  • Currently need administrator level privileges to use LiteSpawn under NT.
  • Under Win9x startup programs may not be suppressed properly when swapping from LiteStep to Explorer the first time after system startup. I recommend manually holding down the CTRL key just to be safe.
  • May lose system tray icons after swapping shells. This is really more the shell than LiteSpawn. I highly recommend using Mike Lin's TraySaver as a workaround.
  • There is a strange Open dialog recursion bug that occurs if you tab to the "Start Other" radio button in the startup dialog with the keyboard. I suggest using the mouse to select this option for now until I can fix it.
  • On fantasically rare occasions, hitting CTRL or SHIFT manually while swapping shells can cause the keyboard state to get out of sync requiring you to toggle the key after the swap is done to restore things back to the proper state. (I've never actually seen it happen but technically it could)

Change Log
Version 1.00b
- Initial public release
Version 1.10
- Added ask_boot support for shell selection at startup.
- Added additional error checking throughout.
- Rewrote shell termination routines to be safer and more efficient.
- Rewrote initialization code to be faster and use less memory.
Version 1.20
- Added reboot option after installation.
- Fixed multiple process bug in 1.10.
- Added keyboard interrupt code to suppress startup programs when swapping shells.
- Rewrote command line parsing and message posting for faster execution.
Version 1.50
- Added timeout to startup dialog.
- Added "Start Other..." option in startup dialog.
- Added "Terminate after spawn" in startup dialog.
- Added per-user theme support in litespawn.cfg.
- Added on the fly Theme swapping.
- Added LiteSpawn version in all dialogs.
- Added -restart command.
- Added -nuke command.
- Added kill_delay option.
- Added dynamic background switching with theme support.
- Added crash protection for alternate shells.
- Added support for multiple alternate shells for each user.
- Added improved support for NT5 beta2.
- Added improved thread synchronization.
- Added shift_delay parameter.
- Fixed option parsing routine for *shortcuts under LiteStep.
- Fixed shell entry detection in HKCU during NT install.
- Fixed reboot option to logoff after install under NT.
- Fixed having to reinstall LiteSpawn after a Windows crash.
Version 1.80
- Added ability to define different monitor resolution with each theme definition.
- Added ability to TILE, STRETCH or CENTER wallpaper in each theme.
- Added ability to support up to twenty themes instead of ten.
- Added improved support for NT5 (Win2000) beta3.
- Added self_terminate option to terminate LiteSpawn after spawning the shell.
- Rewrote initialization code to be a little faster.
- Rewrote multi-threaded code to be more memory efficient.
- Rewrote logoff function so that LiteSpawn now terminates properly after a logoff.

Scary legal stuff
By using this program you agree to not hold the author responsible for any damages or loses of any kind. You agree not to disassemble it, or modify it in any shape or form with out written permission from the author. Doing so revokes all licenses granted to you and/or your party and is punishable by law where applies. hoooooooo-boy!

This program is Copyrighted (c) 1998-1999 by Glen Anderson