readme - update readme for efl 1.8

lots of extra documentation and information now in the README

1 files changed, 607 insertions, 37 deletions

diff --git a/README b/README
index 8a8032bed7..2c47c2b8b3 100644
--- a/README
+++ b/README
@@ -1,18 +1,585 @@
 EFL 1.8.0
+=========
 
 ******************************************************************************
-
  FOR ANY ISSUES PLEASE EMAIL:
  enlightenment-devel@lists.sourceforge.net
-
 ******************************************************************************
 
 EFL is a collection of libraries for handling many common tasks a
 developer man have such as data structures, communication, rendering,
 widgets and more.
 
-VALGRIND DEPENDENCY:
-------------------------------------------------------------------------------
+There are many components inside EFL. They also build various things
+like shared libraries, loadable plug-in modules and also binary
+executables. Different elements will end up being licensed differently
+too. Below is a rundown of the components, what they do and their
+licensing.
+
+All library source is in the src/lib/ directory. All binaries are in
+src/bin/. All loadable modules are in src/modules/. All data files are
+in the data/ directory. Licensing details are listed in COPYING and
+the licenses/ directory. The pc/ directory holds all the Package
+Config files installed to help developers build against EFL.
+
+For more doumentation please see:
+
+http://www.enlightenment.org/p.php?p=docs
+
+
+COMPONENTS
+----------
+
+**Ecore:**
+
+//BSD 2-Clause license//
+
+This is the core main-loop, system events and execution layer. This
+handles running the main loop, integrating with external data and
+timing sources (the system clock, file descriptors, system signals),
+and producing an event queue, walking that queue and dispatching
+events to appropriate callbacks.
+
+
+
+**Ecore Audio:**
+
+//BSD 2-Clause license//
+
+This library provides an API for audio playback and recording. It uses
+pulse audio underneath to handle mixing and policies. The API for this
+should not be considered stable right now because it relies on EO and
+EO is not considers finalized yet.
+
+
+
+**Ecore Cocoa:**
+
+//BSD 2-Clause license//
+
+This provides wrappers/abstractions around Max OS-X Cocoa APIs to help
+Mac porting.
+
+
+
+**Ecore Con:**
+
+//BSD 2-Clause license//
+
+This provides a completely event-based TCP/UDB and Unix domain socket
+API that integrates with the main-loop. This means no blocking to send
+or receive data, supporting "infinite send buffers" with storage and
+spooling being done by Ecore Con. It also supports SSL encryption
+transparently turned on or not on the same connection, certificate
+verification, CURL wrapping for HTTP connection usage (GETs, POSTs
+etc.), asynchronous DNS lookups and provides the ability to also be a
+server, not just a client, with the same event-based API.
+
+
+
+**Ecore Evas:**
+
+//BSD 2-Clause license//
+
+This acts as glue between the display target (X11, Wayland,
+Frame buffer, Cocoa on OSX, Win32 etc.) and Evas. It creates/provides a
+target for Evas to render to (a Window or Surface etc.) and feeds
+input events (Keyboard, Mouse, Multi-touch) into Evas, which then
+selects the target object and calls the callbacks. It also provides
+wrappers/glue for manipulating the Window/Surface.
+
+
+
+**Ecore Fb:**
+
+//BSD 2-Clause license//
+
+This provides virtual terminal allocation, access and handling,
+frame buffer information, raw input handling for keyboard, mouse and
+touch (via tslib).
+
+
+
+**Ecore File:**
+
+//BSD 2-Clause license//
+
+This provides file access convenience APIs for doing simple file
+operations like renames, copies, listing directories and more. It also
+supports file change monitoring and URL downloads.
+
+
+
+**Ecore IMF:**
+
+//BSD 2-Clause license//
+
+This is an input method abstraction framework to allow EFL to talk to
+things like SCIM, IBus, Wayland and XIM. This allows for complex text
+entry in languages such as Chinese, Japanese and Korean.
+
+
+
+**Ecore IMF Evas:**
+
+//BSD 2-Clause license//
+
+This library glues Input method support from Ecore IMF and Evas
+together.
+
+
+
+**Ecore Input:**
+
+//BSD 2-Clause license//
+
+This acts as a generic input layer where multiple display systems can
+post events in the same format to the event queue.
+
+
+
+**Ecore Input Evas:**
+
+//BSD 2-Clause license//
+
+This Routes events from Ecore Input into a given Evas canvas which
+will then route the event further to the destination object and
+callbacks.
+
+
+
+**Ecore IPC:**
+
+//BSD 2-Clause license//
+
+This acts as a layer on top of Ecore Con which handles entire IPC
+message packets, dealing with header delta compression and
+portability, as well as ensuring an entire message is received in one
+go as a single IPC message, regardless of payload data size. The
+entire API is event based almost exactly like Ecore Con and thus it
+supports all the transport layers Ecore Con supports.
+
+
+
+**Ecore Psl1ght:**
+
+//BSD 2-Clause license//
+
+This library acts as a helper for porting to the Playstation 3 (PS3)
+native runtime environment.
+
+
+
+**Ecore SDL:**
+
+//BSD 2-Clause license//
+
+This acts as a wrapper/glue around SDL to handle SDL Windows as well
+as input events from SDL and tie them to the Ecore main-loop and event
+queue.
+
+
+
+**Ecore Wayland:**
+
+//BSD 2-Clause license//
+
+This is a glue/wrapper library to interface EFL to Wayland libraries
+to tie them into the Ecore main-loop and event queue.
+
+
+
+**Ecore Win32:**
+
+//BSD 2-Clause license//
+
+This acts as glue/wrapper around Windows Win32 APIs to tie them into
+the Ecore main-loop and event queue.
+
+
+
+**Ecore WinCE:**
+
+//BSD 2-Clause license//
+
+This acts as glue/wrapper around Windows CE APIs to tie them into the
+Ecore main-loop and event queue.
+
+
+
+**Ecore X:**
+
+//BSD 2-Clause license//
+
+This is a library to wrap/deal with Xlib as well as optionally XCB to
+make dealing with X11 less painful and less footwork as well as being
+glue to tie these into the Ecore main-loop and event queue.
+
+
+
+**Edje:**
+
+//BSD 2-Clause license// (except the epp binary which is GPLv2)
+
+This is a graphics event, input, theme, animation and theme
+abstraction library used to place many UI/UX elements into data files
+(called edj files) that define how to react to incoming
+events/signals, and define animation time lines, states, relative
+scalable layout and much much more. It comes with a compiler that
+compiles source "edc" files into "edj" files (which are actually just
+data files managed by Eet). These "edj" files are fully portable and
+can work on any OS/Architecture just like a JPEG or PNG might be
+portable.
+
+
+
+**Eet:**
+
+//BSD 2-Clause license//
+
+This library is a data storage, encoding and decoding library
+designed to be extremely compact, fast and easy to use. It can take
+data structures directly from memory and serialize them portably to
+disk, then de-serialize them right back to the same data structures in
+memory handling allocation and population of memory all for you in 1
+call. It handles indirections such as pointers, linked lists, arrays
+and hash tables too, so almost any level of data structure complexity
+can be easily saved and loaded back. It is used for "edj" files by
+Edje as well as all configuration in Enlightenment, Elementary and
+Terminology. It supports encryption of data too via SSL, signing of
+files, as well as various compression techniques. It also supports
+encoding and decoding of image data in lossless or lossy form.
+
+
+
+**Eeze:**
+
+//BSD 2-Clause license//
+
+This library acts as an abstraction to discovering hardware interfaces
+for sensors as well as removable media and much more.
+
+
+
+**EFL:**
+
+//BSD 2-Clause license//
+
+This is just some core common header data like a common version number
+for EFL and how to expose the EO API.
+
+
+
+**Efreet:**
+
+//BSD 2-Clause license//
+
+This library provides code for handling Freedesktop.org standards such
+as .desktop files, XDG Menus, Icon search paths and more. It provides
+a central daemon to handle monitoring for changes that the library
+talks to, and the daemon handles updating local cache files the
+library reads.
+
+
+
+**Eina:**
+
+//LGPL v2 license//
+
+This library provides low-level routines for common things like linked
+lists, hash tables, growable arrays, basic string buffers, shared
+string tokens, mmaped() file access, thread abstraction and locking,
+memory pools, copy-on-write segments, iterators, matrices, general
+data models, red/black trees, quad-trees, a simple SAX XML parser and
+more.
+
+
+
+**EIO:**
+
+//LGPL v2 license//
+
+This is an asynchronous I/O library for doing disk I/O without blocking.
+
+
+
+**ElDBus:**
+
+//LGPL v2 license//
+
+This is a DBus access library to allow you to create DBus services as
+well as clients. This glues in DBus into the main-loop so all access is
+asynchronous.
+
+
+
+**Embryo:**
+
+//Small license (same as ZLib license)//
+
+This is a small C-like language compiler and byte-code interpreter
+library. This is used for scripting in Edje. The code is based on
+original source from the Pawn/Small Language but has been made
+portable (endianess issues fixed) and 64bit issues fixed, with the
+runtime library being refactored to be extremely small.
+
+
+
+**Emotion:**
+
+//BSD 2-Clause license//
+
+This is a wrapper around Gstreamer and/or Xine and/or external
+pluggable decoder binaries (generic binaries provided by Emotion
+Generic Players or any suitable drop-in replacement). This glues in
+the decoder library, and its output into a smart Evas object that will
+display the playback for you as the video plays, as well as providing
+higher level controls to seek, play, pause and query the stream
+regardless of the back-end used. Note that using the Xine module may
+effectively make this library GPL v2, so be aware of that before
+turning that on.
+
+
+
+**EO:**
+
+//BSD 2-Clause license//
+
+This is a core object system API that EFL 1.8 and on depend on. The
+API is not finalized, so do not depend on it yet in EFL 1.8, but
+future EFL versions will lock it down.
+
+This object system does simple and multiple inheritance, refcounting,
+strong and weak references, auto-deletion of child objects, unifies
+callback handling with a single path, and also abstracts object
+pointers to be indirect table lookups for increased safety at runtime.
+
+
+
+**EPhysics:**
+
+//BSD 2-Clause license//
+
+This library provides a wrapper around the Bullet physics library,
+allowing for it to be linked directly with Evas objects and control
+their behavior as if they were real physical objects.
+
+
+
+**Escape:**
+
+//GPL v2 license//
+
+This library is used as a compatibility library to provide missing
+libc APIs for porting to the Playstation 3 (PS3) native runtime
+environment.
+
+
+
+**Ethumb:**
+
+//LGPL v2 license//
+
+This library provides core API for a thumbnailing daemon as well as
+the thumbnail daemon itself. Ethumb Client talks with Ethumb to pass
+off thumbnail generation to a central location to be done
+asynchronously.
+
+
+
+**Ethumb Client:**
+
+//LGPL v2 license//
+
+This is the client-side part of Ethumb that provides and API for
+clients to request the Ethumb thumbnailer to generate or find cached
+thumbnails of files.
+
+
+
+**Evas:**
+
+//BSD 2-Clause license//
+
+This is the core rendering and scene graph abstraction library for
+EFL. It manages a stateful 2D scene graph that defines the entire
+content of any canvas. This supplies rendering back-ends for many
+display systems like X11, Windows, Wayland, Frame-buffer etc. and via
+many rendering APIs like OpenGL, OpenGL-ES 2, and pure software
+implementations that are fast and accurate.
+
+
+
+**Evil:**
+
+//BSD 2-Clause license//
+
+This library acts as a porting library for Windows to provide missing
+libc calls not in Mingw32 that EFL needs.
+
+
+
+
+COMPILING AND INSTALLING
+------------------------
+
+    ./configure
+    make
+    sudo make install
+
+If you have doxygen, then you csan build documentation with:
+
+    make doc
+
+You will find documentation in the doc/ directory.
+
+
+REQUIREMENTS
+------------
+
+EFL requires a C and C++ compiler by default. Very little C++ exists
+and is mostly to interface to C++ libraries like Bullet.
+
+Required by default:
+
+    bullet
+    libpng
+    libjpeg
+    gstreamer (0.10) (ensure you have all the gstreamer codecs you need/want)
+    zlib
+    lua (5.1 or 5.2)
+    libtiff
+    openssl
+    curl
+    dbus
+    libc
+    fontconfig
+    freetype2
+    fribidi
+    libpulse
+    libsndfile
+    libx11
+    libxau
+    libxcomposite
+    libxdamage
+    libxdmcp
+    libxext
+    libxfixes
+    libxinerama
+    libxrandr
+    libxrender
+    libxss
+    libxtst
+    libxcursor
+    libxp
+    libxi
+    libgl
+    giflib
+    util-linux
+
+Recommended requirements (highly recommended):
+
+    harfbuzz
+    libxi (2.2 or newer)
+    systemd
+    libwebp
+
+Enable these with configure options:
+
+    --enable-xinput22 \
+    --enable-multisense \
+    --enable-systemd \
+    --enable-image-loader-webp \
+    --enable-harfbuzz
+
+After you install EFL it is **HIGHLY** recommended to install the Evas
+Generic Loaders package and Emotion Generic Players too. These provide
+external binaries, that are either unstable or GPL licensed that are
+just drop-in utilities for handling image and video codecs. They can
+be added or removed at any time (even runtime) so they could be
+replaced or augmented with other drop-in binaries that do the same job
+and talk the same simple stdin/out and shared memory protocol.
+
+
+COMPILER FLAGS
+--------------
+
+You can affect compilation optimization, debugging and other factors
+by setting your CFLAGS environment variable (and CXXFLAGS)
+
+Other recommendations:
+
+    scim
+
+Enable this with:
+
+    --enable-scim
+
+Framebuffer support:
+
+This requires linux frame-buffer support, headers etc. This supports
+basic frame-buffers like /dev/fb as well as input via /dev/input for
+keyboards and mice in a basic way. Enable this with:
+
+    --enable-fb
+
+This also turns on support for touch-screens via tslib. Not everyone
+has tslib, so you may want to disable it with:
+
+    --disable-tslib
+
+You likely don't need static libraries most of the time so you can
+disable them with:
+
+    --disable-static
+
+You may want to change the install prefix for EFL with:
+
+    --prefix=/path/to/prefix
+
+The default prefix if not given is "/usr/local". Many people like to
+use prefixes like /opt/e or /opt/efl or /home/USERNAME/software etc.
+
+You may want to enable valgrind support if you plan on doing debugging
+with EFL or apps built on top of EFL. This requires an install of
+valgrind first. You can enable this with:
+
+    --enable-valgrind
+
+You may want to enable xine support in emotion, as this library
+provides fairly solid support for a lot of codecs and DVD navigation
+support and more. You can enable it with:
+
+    --enable-xine
+
+Wayland is also supported fairly solidly in EFL 1.8. It is not
+required by default due to it being new and not that widely spread.
+You can enable Wayland support with:
+
+    --enable-wayland
+
+For faster rendering when dithering down to lower-than 24/32bpp, you
+can try:
+
+    --with-evas-dither-mask=small
+
+But this will drop quality slightly, using a small 16x16 ordered
+dither mask rather than the default 128x128. This should save a little
+memory too in the binary size of Evas.
+
+There are many other configure options that can be used, but in
+general it is not a good idea to go enabling or disabling things
+unless you wish to break things. The defaults are well tested, with
+the above recommended options also being well tested. Go much further
+and your mileage may vary wildly. Disabling features is a good way of
+breaking EFL functionality, so it is not recommended. The defaults
+have been carefully considered to provide full functionality so users
+will not be missing anything.
+
+
+VALGRIND DEPENDENCY
+-------------------
+
 EFL uses the concept of memory pools (mempool) and this will confuse
 valgrind memcheck tool. By using memory pool, the memory is still
 owned by EFL, then valgrind won't alert on memory leaks or use of
@@ -29,65 +596,68 @@ EFL does NOT link to valgrind libraries. Then there is NO runtime
 dependency on valgrind.
 
 
-BULLET PHYSICS DEPENDENCY:
-------------------------------------------------------------------------------
-EFL comes with EPhysics(a physics wrapper library) enabled by default, to
+BULLET PHYSICS DEPENDENCY
+-------------------------
+
+EFL comes with EPhysics (a physics wrapper library) enabled by default, to
 build it the user must have BulletPhysics engine installed.
 
 More informations about BulletPhysics can be obtained in the upstream project
-web site at: http://bulletphysics.org.
+web site at http://bulletphysics.org
 
 We have received many reports about BulletPhysics installation and distros
 packages in bad shape, some without even a package. If your distro doesn't
-ship a BulletPhysics package or you want to build it from source code follow the
-instructions below:
+ship a BulletPhysics package or you want to build it from source code follow
+the instructions below:
+
+**Required Packages:**
 
-* Required Packages:
 You should have cmake installed. Bullet comes with autotools and cmake build
 systems, do not use the autotools alternative, it's unstable, bogus and hasn't
 been maintained for quite some time.
 
-* Download the tarball from:
+**Download the tarball from:**
+
 http://code.google.com/p/bullet/downloads/list
 
-NOTE: the current supported version is 2.80 or greater.
+**NOTE:**
+
+The current supported version is 2.80 or greater.
 
-* Compiling and Installing:
-Uncompress it to(say) ~/bullet and:
+**Compiling and Installing:**
 
-$ cd ~/bullet/build
-$ cmake .. -DBUILD_CPU_DEMOS=OFF -DBUILD_DEMOS=OFF -DBUILD_SHARED_LIBS=ON
-$ make
-$ sudo make install
-$ sudo ldconfig
+Uncompress it to (say) ~/bullet and:
 
-* Ubuntu Users:
-Alternatively ubuntu users have the option to install the BulletPhysics from
+    cd ~/bullet/build
+    cmake .. -DBUILD_CPU_DEMOS=OFF -DBUILD_DEMOS=OFF -DBUILD_SHARED_LIBS=ON
+    make
+    sudo make install
+    sudo ldconfig
+
+**Ubuntu Users:**
+
+Alternatively Ubuntu users have the option to install the BulletPhysics from
 our official EFL PPA:
 
 https://launchpad.net/~efl/+archive/trunk
 
-------------------------------------------------------------------------------
-COMPILING AND INSTALLING:
 
-  ./configure
-  make
-(do this as root unless you are installing in your users directories):
-  make install
+PROFILES
+--------
 
 EFL build is based on "profiles". It will default to "dev" for
 unreleased software and "release" for official tarballs. One can
 change it with --with-profile=NAME, where NAME is one of:
 
-  * dev: extra checks useful to test software.
-
-  * debug: superset of dev, with debug features and assert().
+  * **dev**: extra checks useful to test software.
+  * **debug**: superset of dev, with debug features and assert().
+  * **release**: optimizations and less checks so it runs faster.
 
-  * release: optimizations and less checks so it runs faster.
 
+CRYPTOGRAPHY
+------------
 
-CRYPTOGRAPHIC SYSTEM: EFL officially uses "openssl" library to do
-signature, cipher and related. Alternatively one can use "gnutls"
-(some distros are strict about licenses and want gnutls instead of
-openssl) or disable it. One can change it with --with-crypto=NAME,
-where NAME is one of: "openssl", "gnutls" and "none".
+EFL officially uses "openssl" library to do signature, cipher and related.
+Alternatively one can use "gnutls" (some distros are strict about licenses
+and want gnutls instead of openssl) or disable it. One can change it with
+--with-crypto=NAME, where NAME is one of: "openssl", "gnutls" and "none".