summaryrefslogtreecommitdiff
path: root/README
blob: 52c8426b5d78bc1527bc9528a7c70b16bd9fa1d3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
EFL
===

******************************************************************************
 FOR ANY ISSUES PLEASE EMAIL:
 enlightenment-devel@lists.sourceforge.net
******************************************************************************

EFL is a collection of libraries for handling many common tasks a
developer may have such as data structures, communication, rendering,
widgets and more.

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 documentation 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 considered 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/UDP 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 (endianness 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 an 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. C++ exists mostly to interface 
to C++ libraries like Bullet and our C++ bindings.

Required by default:

  * bullet
  * libpng
  * libjpeg
  * gstreamer (1.x) (ensure all codecs you want are installed. 0.10 optional)
  * zlib
  * luajit (lua 5.1 or 5.2 optional support)
  * 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 (opengl/glx or opengl-es2/egl)
  * giflib
  * util-linux (limbount + libblkid)
  * systemd / libudev

Recommended requirements (highly recommended):

  * harfbuzz
  * libxi (2.2 or newer)
  * systemd
  * libwebp

Enable these with configure options:

    --enable-xinput22 \
    --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). Be aware
that to ensure ABI stability you should use the exact same CFLAGS / 
CXXFLAGS for all the build of EFL and any applications/libraries that
depend on them.

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
unused memory. EFL will use memcheck.h from valgrind to declare its
memory pools to valgrind, producing better debugging results.

However valgrind is only available to limited platforms, making it 
hard for us to declare it a mandatory requirement. Based on
--with-profile={dev,debug} valgrind will be used if available or will
be issued a warning. You can force valgrind with --enable-valgrind, or
disable it and the warning with --disable-valgrind.

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 build it the user must have BulletPhysics engine installed.

More information about BulletPhysics can be obtained in the upstream project
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:

**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:**

http://code.google.com/p/bullet/downloads/list

**NOTE:**

The current supported version is 2.80 or greater.

**Compiling and Installing:**

Uncompress it to (say) ~/bullet and:

    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


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().
  * **release**: optimizations and less checks so it runs faster.


CRYPTOGRAPHY
------------

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".