summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorCarsten Haitzler (Rasterman) <raster@rasterman.com>2013-11-29 17:31:33 +0900
committerCarsten Haitzler (Rasterman) <raster@rasterman.com>2013-11-29 19:09:17 +0900
commit1b593c58df47fb8c2044b07f2aa6202183e6fbd6 (patch)
tree774c615561e3578459f955db9a454bfcbb4b885a /README
parent9e3b778acb851671c2f24454b80bdeafc20d1c65 (diff)
readme - update readme for efl 1.8
lots of extra documentation and information now in the README
Diffstat (limited to 'README')
-rw-r--r--README644
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 @@
1EFL 1.8.0 1EFL 1.8.0
2=========
2 3
3****************************************************************************** 4******************************************************************************
4
5 FOR ANY ISSUES PLEASE EMAIL: 5 FOR ANY ISSUES PLEASE EMAIL:
6 enlightenment-devel@lists.sourceforge.net 6 enlightenment-devel@lists.sourceforge.net
7
8****************************************************************************** 7******************************************************************************
9 8
10EFL is a collection of libraries for handling many common tasks a 9EFL is a collection of libraries for handling many common tasks a
11developer man have such as data structures, communication, rendering, 10developer man have such as data structures, communication, rendering,
12widgets and more. 11widgets and more.
13 12
14VALGRIND DEPENDENCY: 13There are many components inside EFL. They also build various things
15------------------------------------------------------------------------------ 14like shared libraries, loadable plug-in modules and also binary
15executables. Different elements will end up being licensed differently
16too. Below is a rundown of the components, what they do and their
17licensing.
18
19All library source is in the src/lib/ directory. All binaries are in
20src/bin/. All loadable modules are in src/modules/. All data files are
21in the data/ directory. Licensing details are listed in COPYING and
22the licenses/ directory. The pc/ directory holds all the Package
23Config files installed to help developers build against EFL.
24
25For more doumentation please see:
26
27http://www.enlightenment.org/p.php?p=docs
28
29
30COMPONENTS
31----------
32
33**Ecore:**
34
35//BSD 2-Clause license//
36
37This is the core main-loop, system events and execution layer. This
38handles running the main loop, integrating with external data and
39timing sources (the system clock, file descriptors, system signals),
40and producing an event queue, walking that queue and dispatching
41events to appropriate callbacks.
42
43
44
45**Ecore Audio:**
46
47//BSD 2-Clause license//
48
49This library provides an API for audio playback and recording. It uses
50pulse audio underneath to handle mixing and policies. The API for this
51should not be considered stable right now because it relies on EO and
52EO is not considers finalized yet.
53
54
55
56**Ecore Cocoa:**
57
58//BSD 2-Clause license//
59
60This provides wrappers/abstractions around Max OS-X Cocoa APIs to help
61Mac porting.
62
63
64
65**Ecore Con:**
66
67//BSD 2-Clause license//
68
69This provides a completely event-based TCP/UDB and Unix domain socket
70API that integrates with the main-loop. This means no blocking to send
71or receive data, supporting "infinite send buffers" with storage and
72spooling being done by Ecore Con. It also supports SSL encryption
73transparently turned on or not on the same connection, certificate
74verification, CURL wrapping for HTTP connection usage (GETs, POSTs
75etc.), asynchronous DNS lookups and provides the ability to also be a
76server, not just a client, with the same event-based API.
77
78
79
80**Ecore Evas:**
81
82//BSD 2-Clause license//
83
84This acts as glue between the display target (X11, Wayland,
85Frame buffer, Cocoa on OSX, Win32 etc.) and Evas. It creates/provides a
86target for Evas to render to (a Window or Surface etc.) and feeds
87input events (Keyboard, Mouse, Multi-touch) into Evas, which then
88selects the target object and calls the callbacks. It also provides
89wrappers/glue for manipulating the Window/Surface.
90
91
92
93**Ecore Fb:**
94
95//BSD 2-Clause license//
96
97This provides virtual terminal allocation, access and handling,
98frame buffer information, raw input handling for keyboard, mouse and
99touch (via tslib).
100
101
102
103**Ecore File:**
104
105//BSD 2-Clause license//
106
107This provides file access convenience APIs for doing simple file
108operations like renames, copies, listing directories and more. It also
109supports file change monitoring and URL downloads.
110
111
112
113**Ecore IMF:**
114
115//BSD 2-Clause license//
116
117This is an input method abstraction framework to allow EFL to talk to
118things like SCIM, IBus, Wayland and XIM. This allows for complex text
119entry in languages such as Chinese, Japanese and Korean.
120
121
122
123**Ecore IMF Evas:**
124
125//BSD 2-Clause license//
126
127This library glues Input method support from Ecore IMF and Evas
128together.
129
130
131
132**Ecore Input:**
133
134//BSD 2-Clause license//
135
136This acts as a generic input layer where multiple display systems can
137post events in the same format to the event queue.
138
139
140
141**Ecore Input Evas:**
142
143//BSD 2-Clause license//
144
145This Routes events from Ecore Input into a given Evas canvas which
146will then route the event further to the destination object and
147callbacks.
148
149
150
151**Ecore IPC:**
152
153//BSD 2-Clause license//
154
155This acts as a layer on top of Ecore Con which handles entire IPC
156message packets, dealing with header delta compression and
157portability, as well as ensuring an entire message is received in one
158go as a single IPC message, regardless of payload data size. The
159entire API is event based almost exactly like Ecore Con and thus it
160supports all the transport layers Ecore Con supports.
161
162
163
164**Ecore Psl1ght:**
165
166//BSD 2-Clause license//
167
168This library acts as a helper for porting to the Playstation 3 (PS3)
169native runtime environment.
170
171
172
173**Ecore SDL:**
174
175//BSD 2-Clause license//
176
177This acts as a wrapper/glue around SDL to handle SDL Windows as well
178as input events from SDL and tie them to the Ecore main-loop and event
179queue.
180
181
182
183**Ecore Wayland:**
184
185//BSD 2-Clause license//
186
187This is a glue/wrapper library to interface EFL to Wayland libraries
188to tie them into the Ecore main-loop and event queue.
189
190
191
192**Ecore Win32:**
193
194//BSD 2-Clause license//
195
196This acts as glue/wrapper around Windows Win32 APIs to tie them into
197the Ecore main-loop and event queue.
198
199
200
201**Ecore WinCE:**
202
203//BSD 2-Clause license//
204
205This acts as glue/wrapper around Windows CE APIs to tie them into the
206Ecore main-loop and event queue.
207
208
209
210**Ecore X:**
211
212//BSD 2-Clause license//
213
214This is a library to wrap/deal with Xlib as well as optionally XCB to
215make dealing with X11 less painful and less footwork as well as being
216glue to tie these into the Ecore main-loop and event queue.
217
218
219
220**Edje:**
221
222//BSD 2-Clause license// (except the epp binary which is GPLv2)
223
224This is a graphics event, input, theme, animation and theme
225abstraction library used to place many UI/UX elements into data files
226(called edj files) that define how to react to incoming
227events/signals, and define animation time lines, states, relative
228scalable layout and much much more. It comes with a compiler that
229compiles source "edc" files into "edj" files (which are actually just
230data files managed by Eet). These "edj" files are fully portable and
231can work on any OS/Architecture just like a JPEG or PNG might be
232portable.
233
234
235
236**Eet:**
237
238//BSD 2-Clause license//
239
240This library is a data storage, encoding and decoding library
241designed to be extremely compact, fast and easy to use. It can take
242data structures directly from memory and serialize them portably to
243disk, then de-serialize them right back to the same data structures in
244memory handling allocation and population of memory all for you in 1
245call. It handles indirections such as pointers, linked lists, arrays
246and hash tables too, so almost any level of data structure complexity
247can be easily saved and loaded back. It is used for "edj" files by
248Edje as well as all configuration in Enlightenment, Elementary and
249Terminology. It supports encryption of data too via SSL, signing of
250files, as well as various compression techniques. It also supports
251encoding and decoding of image data in lossless or lossy form.
252
253
254
255**Eeze:**
256
257//BSD 2-Clause license//
258
259This library acts as an abstraction to discovering hardware interfaces
260for sensors as well as removable media and much more.
261
262
263
264**EFL:**
265
266//BSD 2-Clause license//
267
268This is just some core common header data like a common version number
269for EFL and how to expose the EO API.
270
271
272
273**Efreet:**
274
275//BSD 2-Clause license//
276
277This library provides code for handling Freedesktop.org standards such
278as .desktop files, XDG Menus, Icon search paths and more. It provides
279a central daemon to handle monitoring for changes that the library
280talks to, and the daemon handles updating local cache files the
281library reads.
282
283
284
285**Eina:**
286
287//LGPL v2 license//
288
289This library provides low-level routines for common things like linked
290lists, hash tables, growable arrays, basic string buffers, shared
291string tokens, mmaped() file access, thread abstraction and locking,
292memory pools, copy-on-write segments, iterators, matrices, general
293data models, red/black trees, quad-trees, a simple SAX XML parser and
294more.
295
296
297
298**EIO:**
299
300//LGPL v2 license//
301
302This is an asynchronous I/O library for doing disk I/O without blocking.
303
304
305
306**ElDBus:**
307
308//LGPL v2 license//
309
310This is a DBus access library to allow you to create DBus services as
311well as clients. This glues in DBus into the main-loop so all access is
312asynchronous.
313
314
315
316**Embryo:**
317
318//Small license (same as ZLib license)//
319
320This is a small C-like language compiler and byte-code interpreter
321library. This is used for scripting in Edje. The code is based on
322original source from the Pawn/Small Language but has been made
323portable (endianess issues fixed) and 64bit issues fixed, with the
324runtime library being refactored to be extremely small.
325
326
327
328**Emotion:**
329
330//BSD 2-Clause license//
331
332This is a wrapper around Gstreamer and/or Xine and/or external
333pluggable decoder binaries (generic binaries provided by Emotion
334Generic Players or any suitable drop-in replacement). This glues in
335the decoder library, and its output into a smart Evas object that will
336display the playback for you as the video plays, as well as providing
337higher level controls to seek, play, pause and query the stream
338regardless of the back-end used. Note that using the Xine module may
339effectively make this library GPL v2, so be aware of that before
340turning that on.
341
342
343
344**EO:**
345
346//BSD 2-Clause license//
347
348This is a core object system API that EFL 1.8 and on depend on. The
349API is not finalized, so do not depend on it yet in EFL 1.8, but
350future EFL versions will lock it down.
351
352This object system does simple and multiple inheritance, refcounting,
353strong and weak references, auto-deletion of child objects, unifies
354callback handling with a single path, and also abstracts object
355pointers to be indirect table lookups for increased safety at runtime.
356
357
358
359**EPhysics:**
360
361//BSD 2-Clause license//
362
363This library provides a wrapper around the Bullet physics library,
364allowing for it to be linked directly with Evas objects and control
365their behavior as if they were real physical objects.
366
367
368
369**Escape:**
370
371//GPL v2 license//
372
373This library is used as a compatibility library to provide missing
374libc APIs for porting to the Playstation 3 (PS3) native runtime
375environment.
376
377
378
379**Ethumb:**
380
381//LGPL v2 license//
382
383This library provides core API for a thumbnailing daemon as well as
384the thumbnail daemon itself. Ethumb Client talks with Ethumb to pass
385off thumbnail generation to a central location to be done
386asynchronously.
387
388
389
390**Ethumb Client:**
391
392//LGPL v2 license//
393
394This is the client-side part of Ethumb that provides and API for
395clients to request the Ethumb thumbnailer to generate or find cached
396thumbnails of files.
397
398
399
400**Evas:**
401
402//BSD 2-Clause license//
403
404This is the core rendering and scene graph abstraction library for
405EFL. It manages a stateful 2D scene graph that defines the entire
406content of any canvas. This supplies rendering back-ends for many
407display systems like X11, Windows, Wayland, Frame-buffer etc. and via
408many rendering APIs like OpenGL, OpenGL-ES 2, and pure software
409implementations that are fast and accurate.
410
411
412
413**Evil:**
414
415//BSD 2-Clause license//
416
417This library acts as a porting library for Windows to provide missing
418libc calls not in Mingw32 that EFL needs.
419
420
421
422
423COMPILING AND INSTALLING
424------------------------
425
426 ./configure
427 make
428 sudo make install
429
430If you have doxygen, then you csan build documentation with:
431
432 make doc
433
434You will find documentation in the doc/ directory.
435
436
437REQUIREMENTS
438------------
439
440EFL requires a C and C++ compiler by default. Very little C++ exists
441and is mostly to interface to C++ libraries like Bullet.
442
443Required by default:
444
445 bullet
446 libpng
447 libjpeg
448 gstreamer (0.10) (ensure you have all the gstreamer codecs you need/want)
449 zlib
450 lua (5.1 or 5.2)
451 libtiff
452 openssl
453 curl
454 dbus
455 libc
456 fontconfig
457 freetype2
458 fribidi
459 libpulse
460 libsndfile
461 libx11
462 libxau
463 libxcomposite
464 libxdamage
465 libxdmcp
466 libxext
467 libxfixes
468 libxinerama
469 libxrandr
470 libxrender
471 libxss
472 libxtst
473 libxcursor
474 libxp
475 libxi
476 libgl
477 giflib
478 util-linux
479
480Recommended requirements (highly recommended):
481
482 harfbuzz
483 libxi (2.2 or newer)
484 systemd
485 libwebp
486
487Enable these with configure options:
488
489 --enable-xinput22 \
490 --enable-multisense \
491 --enable-systemd \
492 --enable-image-loader-webp \
493 --enable-harfbuzz
494
495After you install EFL it is **HIGHLY** recommended to install the Evas
496Generic Loaders package and Emotion Generic Players too. These provide
497external binaries, that are either unstable or GPL licensed that are
498just drop-in utilities for handling image and video codecs. They can
499be added or removed at any time (even runtime) so they could be
500replaced or augmented with other drop-in binaries that do the same job
501and talk the same simple stdin/out and shared memory protocol.
502
503
504COMPILER FLAGS
505--------------
506
507You can affect compilation optimization, debugging and other factors
508by setting your CFLAGS environment variable (and CXXFLAGS)
509
510Other recommendations:
511
512 scim
513
514Enable this with:
515
516 --enable-scim
517
518Framebuffer support:
519
520This requires linux frame-buffer support, headers etc. This supports
521basic frame-buffers like /dev/fb as well as input via /dev/input for
522keyboards and mice in a basic way. Enable this with:
523
524 --enable-fb
525
526This also turns on support for touch-screens via tslib. Not everyone
527has tslib, so you may want to disable it with:
528
529 --disable-tslib
530
531You likely don't need static libraries most of the time so you can
532disable them with:
533
534 --disable-static
535
536You may want to change the install prefix for EFL with:
537
538 --prefix=/path/to/prefix
539
540The default prefix if not given is "/usr/local". Many people like to
541use prefixes like /opt/e or /opt/efl or /home/USERNAME/software etc.
542
543You may want to enable valgrind support if you plan on doing debugging
544with EFL or apps built on top of EFL. This requires an install of
545valgrind first. You can enable this with:
546
547 --enable-valgrind
548
549You may want to enable xine support in emotion, as this library
550provides fairly solid support for a lot of codecs and DVD navigation
551support and more. You can enable it with:
552
553 --enable-xine
554
555Wayland is also supported fairly solidly in EFL 1.8. It is not
556required by default due to it being new and not that widely spread.
557You can enable Wayland support with:
558
559 --enable-wayland
560
561For faster rendering when dithering down to lower-than 24/32bpp, you
562can try:
563
564 --with-evas-dither-mask=small
565
566But this will drop quality slightly, using a small 16x16 ordered
567dither mask rather than the default 128x128. This should save a little
568memory too in the binary size of Evas.
569
570There are many other configure options that can be used, but in
571general it is not a good idea to go enabling or disabling things
572unless you wish to break things. The defaults are well tested, with
573the above recommended options also being well tested. Go much further
574and your mileage may vary wildly. Disabling features is a good way of
575breaking EFL functionality, so it is not recommended. The defaults
576have been carefully considered to provide full functionality so users
577will not be missing anything.
578
579
580VALGRIND DEPENDENCY
581-------------------
582
16EFL uses the concept of memory pools (mempool) and this will confuse 583EFL uses the concept of memory pools (mempool) and this will confuse
17valgrind memcheck tool. By using memory pool, the memory is still 584valgrind memcheck tool. By using memory pool, the memory is still
18owned by EFL, then valgrind won't alert on memory leaks or use of 585owned 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
29dependency on valgrind. 596dependency on valgrind.
30 597
31 598
32BULLET PHYSICS DEPENDENCY: 599BULLET PHYSICS DEPENDENCY
33------------------------------------------------------------------------------ 600-------------------------
34EFL comes with EPhysics(a physics wrapper library) enabled by default, to 601
602EFL comes with EPhysics (a physics wrapper library) enabled by default, to
35build it the user must have BulletPhysics engine installed. 603build it the user must have BulletPhysics engine installed.
36 604
37More informations about BulletPhysics can be obtained in the upstream project 605More informations about BulletPhysics can be obtained in the upstream project
38web site at: http://bulletphysics.org. 606web site at http://bulletphysics.org
39 607
40We have received many reports about BulletPhysics installation and distros 608We have received many reports about BulletPhysics installation and distros
41packages in bad shape, some without even a package. If your distro doesn't 609packages in bad shape, some without even a package. If your distro doesn't
42ship a BulletPhysics package or you want to build it from source code follow the 610ship a BulletPhysics package or you want to build it from source code follow
43instructions below: 611the instructions below:
612
613**Required Packages:**
44 614
45* Required Packages:
46You should have cmake installed. Bullet comes with autotools and cmake build 615You should have cmake installed. Bullet comes with autotools and cmake build
47systems, do not use the autotools alternative, it's unstable, bogus and hasn't 616systems, do not use the autotools alternative, it's unstable, bogus and hasn't
48been maintained for quite some time. 617been maintained for quite some time.
49 618
50* Download the tarball from: 619**Download the tarball from:**
620
51http://code.google.com/p/bullet/downloads/list 621http://code.google.com/p/bullet/downloads/list
52 622
53NOTE: the current supported version is 2.80 or greater. 623**NOTE:**
624
625The current supported version is 2.80 or greater.
54 626
55* Compiling and Installing: 627**Compiling and Installing:**
56Uncompress it to(say) ~/bullet and:
57 628
58$ cd ~/bullet/build 629Uncompress it to (say) ~/bullet and:
59$ cmake .. -DBUILD_CPU_DEMOS=OFF -DBUILD_DEMOS=OFF -DBUILD_SHARED_LIBS=ON
60$ make
61$ sudo make install
62$ sudo ldconfig
63 630
64* Ubuntu Users: 631 cd ~/bullet/build
65Alternatively ubuntu users have the option to install the BulletPhysics from 632 cmake .. -DBUILD_CPU_DEMOS=OFF -DBUILD_DEMOS=OFF -DBUILD_SHARED_LIBS=ON
633 make
634 sudo make install
635 sudo ldconfig
636
637**Ubuntu Users:**
638
639Alternatively Ubuntu users have the option to install the BulletPhysics from
66our official EFL PPA: 640our official EFL PPA:
67 641
68https://launchpad.net/~efl/+archive/trunk 642https://launchpad.net/~efl/+archive/trunk
69 643
70------------------------------------------------------------------------------
71COMPILING AND INSTALLING:
72 644
73 ./configure 645PROFILES
74 make 646--------
75(do this as root unless you are installing in your users directories):
76 make install
77 647
78EFL build is based on "profiles". It will default to "dev" for 648EFL build is based on "profiles". It will default to "dev" for
79unreleased software and "release" for official tarballs. One can 649unreleased software and "release" for official tarballs. One can
80change it with --with-profile=NAME, where NAME is one of: 650change it with --with-profile=NAME, where NAME is one of:
81 651
82 * dev: extra checks useful to test software. 652 * **dev**: extra checks useful to test software.
83 653 * **debug**: superset of dev, with debug features and assert().
84 * debug: superset of dev, with debug features and assert(). 654 * **release**: optimizations and less checks so it runs faster.
85 655
86 * release: optimizations and less checks so it runs faster.
87 656
657CRYPTOGRAPHY
658------------
88 659
89CRYPTOGRAPHIC SYSTEM: EFL officially uses "openssl" library to do 660EFL officially uses "openssl" library to do signature, cipher and related.
90signature, cipher and related. Alternatively one can use "gnutls" 661Alternatively one can use "gnutls" (some distros are strict about licenses
91(some distros are strict about licenses and want gnutls instead of 662and want gnutls instead of openssl) or disable it. One can change it with
92openssl) or disable it. One can change it with --with-crypto=NAME, 663--with-crypto=NAME, where NAME is one of: "openssl", "gnutls" and "none".
93where NAME is one of: "openssl", "gnutls" and "none".