Enlightenment

By Christian Hennecke and Platon Fomichev

Thanks to Platon Fomichev for allowing me to integrate his user's guide into my site.

Welcome to E/2 user's guide. This guide is written for end users to simplify the task of installing Enlightenment and will give you some basic knowledge of how to use many features integrated in E/2. The document is divided into seven sections:
 * 1) Overview
 * 2) Getting E/2 and short description of "who's who"
 * 3) Installing E/2 and possible problems
 * 4) Basic skills with E
 * 5) Themes
 * 6) Epplets
 * 7) Additional info


 * Support, help, docs and bugs: Platon Fomichev or Stauff__ at pla@cland.ru
 * Enlightenment/2 Homepage: birdy.os2.ru

Note: If you are using Enlightenment/2 and you like it, drop Platon Fomichev a note. If he gets to think that nobody actually uses the packages he has ported, he probably won't continue working on them in the future. If you don't like it, drop him a note, too, and include a description of your problems. That's the only way to improve the software!

1. Overview
First of all let's clarify everything. Enlightenment is an XFree86/OS2 application. It is designed to be used only on XFree86/OS2 and only on OS/2 Warp 3/4/WSeB or eComStation. The task of setting up XFree86/OS2 and configuring it is beyond this document, so if you just want to look at E/2 think about installing X first. (Information on how to do this can be found at this site.) And more.. I am not going to port E to PM, but it is possible. Good knowledge of X and OS/2 PM are of course the requirements for any coder who is going to start this project.

WARNING: Before you proceed with E/2 installation ensure that your system meets E/2's requirements! Minimum requirements:
 * 1) IBM PC machine with Intel architecture processor 133 or higher
 * 2) IBM OS/2 Warp 3/4/WSeB or eComStation (*1) with MMOS2 installed
 * 3) XFree86 3.3.3.1 or higher, 3.3.6 recommended. (*2)
 * 4) 48 MB of RAM. (*3)
 * 5) Accelerated X server (not generic SVGA (*4)) in 16, 24 or 32 bit colour depth while using X. 8 bits are too small and look bad.
 * 6) 3 Button Mouse - yes - this is a must if you want to work in E/2. Of course you can use a 2 Button mouse, too - but the third button has to be emulated by simultaneously pressing both buttons and this is an awful thing in my opinion.
 * 7) A filesystem that supports long filenames, i.e. HPFS, HPFS386, FAT32(?) or ext2.
 * 8) EMX 0.9d fix 2 or 3 runtime

2.1 Getting E/2
Installing E/2 is not easy most of all because I am a damned lazy man :) I do really hope someone will construct a .wpi package for E so this section will become obsolete. Meanwhile let's start digging into the Unix-way on OS/2. Well, apart from the Enlightenment package itself you need lots of libraries that will help E/2 to operate, also some ports from Unix and a shell... Let's try to summarize:

1. Shell: any shell will do, except for CMD.EXE. By the way, E/2 comes with a package called E-Support.zip. Therein you will find the shell which I use. 2. Programs: (You can find most of them at os2site.com and all in E-Support.zip) Seems this is all you need, but IMHO it is much easier to install ALL packages from os2site.com like GNU file utils, GNU text utils, GNU grep and other GNU things to keep yourself from future troubles.. Someone may say "what a bunch of crap" - hey-ho laddy indeed it is, but you want to have E/2 up and running so keep busy downloading software. And even more, some commands like rm -r * can do lot's of cool things ;). See also the guide Setting up a Unixish environment for OS/2 on this site for information on how to install all the GNU stuff.
 * awk - pattern scanning and processing language
 * grep - search stdin or files for pattern
 * head - print first 10 lines of each FILE to standard output
 * tail - print last 10 lines of each FILE to standard output
 * tr - translate, squeeze, and/or delete characters from standard input
 * which - search for application in %PATH%
 * ps - list processes
 * basename - get absolute file name without its path
 * sed - stream text editor
 * touch - update files date to current one
 * rm - remove files and/or directories
 * cp - Tremble, copy command! cp is much more powerful ;)
 * mv - move files
 * mkdir - make directory
 * gzip - good old file packer
 * tar - file archiver
 * Recommended bzip2 - good new file packer

Now for libs, they are all in fact DLL files.

Graphics subsystem:
All libs are shipped separately.
 * ImageMagick - A huge but very useful tool itself, it is a must for server based image operations from a command line.
 * GIF lib
 * PNG lib
 * JPEG lib
 * TIFF lib
 * Imlib195 lib - special library for E and GTK with its own config and tools.
 * MESAGL lib - Library for epplets

Font subsytem:
All libs are shipped separately.
 * FreeType lib - Enables E/2 to use TrueType fonts

Additional files for E:

 * E16MenuEditor & E16KeyEditor - both require GTK 1.2.8 but are very useful - A simple menu editor and a simple key editor.
 * The latest Shared Memory library. Latest shm.dll can always be found at birdy.os2.ru and is extremely necessary for X 3.3.1 users.

2.2 Who's who
Here I will explain what each file does.

\XFree86
First of all E/2 uses the \XFree86 root directory as a base and will not work without it. And no chance otherwise. You need to have the \Xfree86 directory for E/2 to work ok.

\XFree86\bin
The directory where the enlightenment binary is - it is called enlightenment.exe :). There are also some menu generation utilities and some epplets. All epplets have the extension .epplet. %HOME%\.enlightenment

Type SET HOME to get info where your home directory is. In it you typically can see:

Directories:

 * backgrounds - This is a directory where you will place backgrounds for fast access and fast switching.
 * cached - Contains some vital info to speed up E's loading & work.
 * bgsel - Backgrounds scaled for the configuration notebook
 * cfg - Configuration files processed through E compiler
 * img - Backgrounds and other images scaled for menu view
 * pager - Backgrounds scaled for pager view
 * epplet_config - Epplets write their stuff there
 * gnome_icons - Gnome icons scaled for menu view
 * menus_gnome - Contains *.menu files for gnome apps (see "menu" format).
 * themes - Here you can place tgz'ipped or untgz'ipped :) E themes.

Files:

 * ...e_session-XXXXXX - Weird system file. No maintenance please ;). In general it contains info about remembered settings, keys and so on.
 * ...e_session-XXXXXX.snapshots.0 - Weird system file. No maintenance please ;).
 * .initialized - You may look into this file. By the way, this file is an interesting one. By deleting it, you may re-initialize E.
 * .zoom_warn - You may look into this file.
 * epplets.menu - Epplets menu
 * file.menu - One of E main menus
 * gnome.menu - Gnome menu
 * gnome_user.menu - Gnome User Menu
 * user_apps.menu - General X applications you may have
 * user_theme.cfg - A file which is a pointer to the current theme.

Directories:
(you may not have some of them)
 * config - Some GENERAL defaults for E
 * E-docs - Enlightenment documentation
 * epplet_data - Epplets data
 * epplet_icons - Epplets icons
 * fonts - General fonts for E system use
 * themes - Themes directory (here you will see all themes you have)

Directories:

 * pix - Common pictures for settings and tooltips

Files:
(Please read the E theming tutorial on info about this files) That's all folks about E files and dirs.
 * actionclasses.cfg
 * control.cfg
 * definitions
 * icondefs.cfg
 * keybindings.cfg - You can dig up in this file - it is pretty understandable
 * keybindings.gmc.cfg
 * keybindings.nogmc.cfg
 * menus.cfg - You can dig up in this file - it is pretty understandable

3.1 Installing
Well, I recommend first getting ALL you may need and that's a lot as you may see, after that save it all in an "archive" directory and start installing. If you still haven't got X up and running it is very bad and sad.. loop at this point until you have X running in 16bpp colour depth with your old rusty window manager ;). This assumes by the way that EMX is also installed: Please double check its version and upgrade if necessary. Unzip the graphic libs, font libs, imlib195 and finally the huge E/2 package into the \XFree86 tree. Change xinitrc.cmd so it will start 'enlightenment' and check that you do not have .enlightenment or other similar directories in your HOME directory. If it exists please wipe it out.

Now for a brief test:

The E-Support package comes with the "ldd" tool for checking up executables and dlls. Type ldd enlightenment.exe in the \XFree86\bin directory and check your output. It may look like this:  Loading DLL 'emx' --> E:\OS2\DLL\EMX.DLL. Loading DLL 'EMXLIBCM' --> E:\OS2\DLL\EMXLIBCM.DLL. Loading DLL 'intl' --> F:\XFREE86\LIB\INTL.DLL. Loading DLL 'X11' --> F:\XFREE86\LIB\X11.DLL. Loading DLL 'Imlib195' --> F:\XFREE86\LIB\IMLIB195.DLL. Loading DLL 'XEXT' --> F:\XFREE86\LIB\XEXT.DLL. Loading DLL 'SHM' --> F:\XFREE86\LIB\SHM.DLL. Loading DLL 'XTST' --> F:\XFREE86\LIB\XTST.DLL. Loading DLL 'SM' --> F:\XFREE86\LIB\SM.DLL. Loading DLL 'ICE' --> F:\XFREE86\LIB\ICE.DLL. Loading DLL 'libaudio' --> F:\XFREE86\LIB\LIBAUDIO.DLL. Loading DLL 'ttf' --> F:\XFREE86\LIB\TTF.DLL. Loading DLL 'doscalls' --> loaded. Loading DLL 'mdm' --> E:\MMOS2\DLL\MDM.DLL. All DLL's used by 'enlightenment.exe' could be loaded. 

See the last line :) This is your goal, too. Now check that cp, rm, tar, gzip and other GNU utilities are in your PATH and may be run from anywhere on drive. Time to work with XF86Config. Find it and open it to edit modes. Now add these lines in your video card definition to make the Zoom feature work ok: Modes "1600x1200" "1280x1024" "1152x864" "1024x768" "800x600" "640x480" "512x384" "400x300" "320x240" An example:  Section "Screen" Driver "accel" Device "ATI 3D Xpression" Monitor "My Monitor" Subsection "Display" Depth 8 Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768" ViewPort 0 0 EndSubsection Subsection "Display" Depth 16 Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768" ViewPort 0 0 EndSubsection Subsection "Display" Depth 24 Modes "800x600" "640x480" "512x384" "400x300" "320x240" "1600x1200" "1280x1024" "1152x864" "1024x768" ViewPort 0 0 EndSubsection Subsection "Display" Depth 32 Modes "640x480" "800x600" "1024x768" ViewPort 0 0 EndSubsection EndSection  Now run X and see what will happen ;)

3.2 Possible problems
And there is a hell lot of them my friends... Although most of the users do not have E/2 troubles you may be the one who has them all.

1. X Server crashes Possibly old server, and most possibly old shm.dll

2. Wrong colors Possibly incorrect switch to 16bpp. Start X this way: startx -- -bpp 16

3. Strange dialog box with error Error ;) Send it to me no more

4. Illegal fonts Study theme creation procedures and change fonts the way you like.

5. Menu creation failure Get all utilities that I asked you to get and check that sh.exe can be run.

6.No icons in menus Install ImageMagick!

7.E/2 starts after a big pause XFree86/OS2 bug, not mine - bomb Mr. Holger Veit with this bug, may be he is going to fix it ;). By the way, you can install Samm's RxStartx which can launch XFree86 up to 2 times faster.

4. Basic skills with E for people that are not going to read docs :)
Well, E has an extremely good help system IMHO - I urge you to read it, but alas you may miss some points.. So I point out here the most useful and most not-so-obvious things:

4.1 Using Menus
To make a menu "stick" and leave it up so you can select items from it multiple times, click and hold down the mouse and release on the title of the menu (if it has one) and it will remain up. You can move it and manipulate it like a normal window. Close the window to unstick the menu.

4.2 Moving windows without titlebar
If you hold down the ALT key and hold down the left mouse button anywhere in the window (on the border OR in the application part) while dragging, you will move this window around. Doing the same but with the middle mouse button will resize the window in that direction. Clicking the right mouse button anywhere in the window while holding down the ALT key will bring up the window operations menu.

4.3 Useful keys
CTRL+ALT+(F1 - F12) - Go directly to desktops 0 - 11

ALT+Tab - Switch focus to the next window (only when XKB is enabled)

ALT+Enter - Zoom/Unzoom the currently focused window

I made myself a good key combination using the E16MenuEdit utility from the E-Support package and a go.exe application. I mapped the Windoze key to a command go -j pmspool.exe thus pressing this key I move from X to PM without the Ctrl-Esc sequence.

CTRL+Alt+ESC is also a useful combination. It kills all X in one second ;). Good when X is hanging.

CTRL+Alt+Shift+"+" and CTRL+Alt+Shift+"-" can quickly switch between video modes.

5. Themes
Enlightenment themes are packages that can change the look and feel of Enlightenment incredibly. Some have already been included and can be selected from the item Themes in the Enlightenment menu (click the middle mouse button). Changing themes can take a while, so please be patient. Additional themes can be obtained from http://e.themes.org.

Well, E themes can be unpacked using untgzos2.exe from the E-Support package or with gzip and tar. Their installation is quite simple - just copy a compressed theme to \XFree86\lib\X11\enlightenment\themes or unpack a theme to this directory. By uncompressing the theme you speed up loading of E/2 a lot, by the way.

WARNING: Some themes may have errors or just don't like Enlightenment/2. So in case you experiences lock-ups using a new theme, you'd better switch back to one of the standard ones.

6. Epplets
Epplets introduce new package for E/2 users to enhance their life with small yet beautiful and useful programs ;) 50% of core code of most of Epplets was written to use specific OS/2 API's for better performance. Also some epplets are set to work on idle priority. 6.1 What epplets are in the package?

Many ;). But not all! For example the E-CD applet was dropped because I do not know how to program CD operations in OS/2. So here is the list: E-Areas.epplet - Desktop switcher E-Battery.epplet - Battery status (may not work on some OS/2s) E-Biff.epplet - Mail checker E-Clock.epplet - Clock ;) E-Cpu.epplet - CPU usage E-Exec.epplet - Quick exec E-Load.epplet - CPU Usage E-Magic.epplet - What's that I do not know myself E-MemWatch.epplet - Memory meter E-MoonClock.epplet - Moon clock E-Net.epplet - Net usage E-NetFlame.epplet - Net usage E-NetGraph.epplet - Net graph (powerful!) E-OpenGL-Demo.epplet - Open GL demo - you will need MESA/2 libs for it E-SD.epplet - ESD monitor (requires ESD to be running) E-ScreenSave.epplet - Screen save E-ScreenShoot.epplet -Screen shot E-Slides.epplet - Dynamic background change E-Sys.epplet - Uptime E-Time.epplet - Current date E-UrlWatch.epplet -Url grabber E-Xss.epplet - X-ScreenSaver wrapper

6.2 How to install
Unpack the archive to the \XFree86 tree and in E/2 launch Menu Regeneration (New menu-gen-scripts are also added to this package.) (User Menus -> Enlightenment Epplets)

6.3 What about the sources?
All epplets are OpenSource if you want to make modifications. Sources are included as there are many changes, too many for diff.

6.4.1 E-MemWatch
You will need latest THESEUS installed to correctly see Swap statistics.

6.4.2 Open-GL Demo
It needs MESA libs to work.

7.1 Setting up ESD
ESD is the Enlightenment Sound Daemon and is required to enable Enlightenments system sounds. Just run esd.exe before starting XFree86/OS2. You should hear some lovely ;) tunes. Next time use the -nobeeps option to make ESD silent. If you want you can modify xinitrc.cmd to automatically start ESD every time X starts by adding the line 'detach esd.exe -nobeeps' After that enable sound in E/2.

7.2 Locale things
E comes with locale support so it supports messages in your language. Just check \XFree86\lib\X11\locale\, i.e de for German. CAUTION: Not all themes have fonts that support all your characters. If you do not want to use E locale support, please delete \XFree86\lib\X11\locale\\LC_MESSAGES\enlightenment.mo.

7.3 Menu generation issues & GNOME/2
E/2 will automatically construct menus for you at first startup. If you have troubles with GNOME/2 please download the package gnome2-apps_tree_for_E.zip to get a full GNOME/2 application tree.

Credits
I wish to express my deepest gratitude to Mr. Hung Chi Chu for doing first work on E/2 0.15.5 and for starting the port itself. I do not know where he is now, what is he doing now and nothing can stop my grief. He disappeared so suddenly and for a year I heard nothing about him. He was the MASTER of porting. I miss him so much.

Christoph Vogelbusch is the person who made E/2 available to millions, thanks Chris!

Alex Galkin kept me busy testing E/2 code. 10X! (Thanks)

Holger Veit for doing XFree86/OS2 :) ....hmm.. heh....what the hell for..eeek...damn... IBM (only OS/2 loyal people) for OS/2 ;)

I also want to thank some people on #os2russian & #os2warez: [Nuke] es Alexx banshee _mda_ Samm dip Euxx Chill |AlexV| OS2OK Ltning and all others!

That's all folks! May the Source be with you ;)