Source

All our source code is available from our GIT source repositories. It used to be SVN, and we are now in the process of switching between the two. If a repository is available by GIT, use that one. If we actually are moving seriously on a piece of code, it will make its way to our download page. For something supported, look there. If you want to help with development or are just hyper-curious and want to see what's in our workshop, then you will want to browse through our GIT repositories. Alternatively, you might want to clone it.

Our list of GIT repositories consists of many little projects. Our core projects, Enlightement, EFL, and Elementary, are prefixed with "core/", the legacy (before merge) EFL components are prefixed with "legacy/", and pet dev projects are prefixed with "devs/DEV-NAME/". Our repositories are not small and carry years of development. There are currently over 1.5 million lines of C source code alone in them. Along with some other languages. To clone the repositories you will have to get GIT A full local checkout will use about 1.2 GB of local disk space. To check it out you will need GIT. Most Linux distributions come with packages for it; for other operating systems your luck may vary. There is msysgit for Windows, and OSX users can just use regular GIT like their Linux counterparts. To clone a git repository you need to do (for example for the EFL repo):

git clone git://git.enlightenment.org/core/efl.git

Full links are easily guessable (just the repo name), but are also available from the online repository browser linked to above. (It's recommended you use the git protocol, but you can use the http protocol if you prefer; developers should use ssh)

To update the code in your tree (pull in changes from our master tree), just run:

git pull --rebase

In order to generate patches

git format-patch LAST-COMMIT-BEFORE-YOURS # read the manual

Please read more about git so you'll be able to unleash its full power. We use phabricator for patch reviews, ticket management, wiki and etc. This means we use "arcanist" for patch submissions. More info is available at the relevant phabricator wiki page.


Once you become an enlightenment developer, you will possibly get commit access. This means you'll be able to push commits into the branches, and create your own development branches. All changes are broadcast to our GIT Commits Mailing List as they happen. In order to give yourself the ability to do all of these, i.e use your commit access, you'll have to modify your git remote. You do that by running:

git remote set-url origin git+ssh://git@git.enlightenment.org/core/efl.git

If by some crazy turn of events we gave you access without you having a clone in the first place, or alternatively you are doing a new clone for whatever reason, you can just clone the git+ssh path directly. Important: Do not change the "git" username at the beginning of the command, that's correct.

Building

Note that this documentation will not apply to development trees, just releases right now and will be updated next release cycle.

Almost all our projects are C based (with some C++). They almost all use autoconf, automake, libtool etc. (autotools) and any such source tree will ship with an autogen.sh script. This is where it all begins.

To build a library or application simply start by running the autogen.sh script (and pass in a --prefix="/where/to/install" option if you wish something other than the default /usr/local install location). The autogen.sh script will run configure for you, passing in any parameters provided to it to configure. After this you should be able to do the usual make and make install (as root if you install in a root owned location). So a quick recipe for building anything would be:

./autogen.sh && make && sudo make install

You will definitely want the following installed to build EFL and E (exact package names may vary from system to system):

  • subversion
  • gcc
  • autoconf 2.59 or better
  • automake 1.10 or better
  • autopoint
  • libtool
  • make (gnu make)
  • gettext
  • libpam dev headers
  • libfreetype dev headers
  • libpng dev headers
  • libjpeg dev headers
  • zlib dev headers
  • libdbus dev headers
  • liblua 5.1 or better dev headers
  • libx11 dev headers
  • libxcursor dev headers
  • libxrender dev headers
  • libxrandr dev headers
  • libxfixes dev headers
  • libxdamage dev headers
  • libxcomposite dev headers
  • libxss dev headers
  • libxp dev headers
  • libxext dev headers
  • libxinerama dev headers
  • libxkbfile dev headers
  • libxtst dev headers
  • libxcb dev headers
  • libxcb-shape dev headers
  • libxcb-keysyms1-dev
  • libpulse-dev
  • libsndfile-dev
  • libudev dev headers (to build eeze for udev support)
  • libblkid-dev
  • libmount-dev
  • libgstreamer0.10-dev headers (Video file loading support in evas_generic_loaders or emotion)
  • check

Some extra optional packages for support of bonus features that you might want installed also are (there are even more optionally supported libraries than these, but these are the main/recommended set):

  • libtiff dev headers (tiff loading support in evas)
  • libesvg dev headers (svg loading support in evas)
  • libgif dev headers (gif loading support in evas)
  • libungif dev headers (gif loading support in evas *1)
  • libcurl dev headers (http download/fetch support in ecore *2)
  • libc-ares dev headers (async DNS lookup support in ecore)
  • libgnutls dev headers (signed eet files, secure tcp connection support for ecore)
  • libasound2 dev headers (alsa sound card support in E17 mixer module)
  • mesa-common dev headers (OpenGL2.0 or OpenGL-ES2.0 support in evas)
  • libspectre dev headers (Postscript Loading support in evas_generic_loaders)
  • libpoppler dev headers (PDF loading support in evas_generic_loaders)
  • librsvg dev headers (SVG loading support in evas_generic_loaders)
  • libraw dev headers (RAW loading support in evas_generic_loaders)
  • libxine dev headers (Video file loading support in emotion)
  • valgrind

*1. Due to a patent issue in GIF compression, libungif was created to work around this, but the patent has since expired so it is not needed anymore.
*2. Please ensure your system libcurl is compiled with c-ares support to avoid blocking DNS lookups when doing http transactions.

Enlightenment does lots of runtime support checks. If you want network management support you will want to install the connman daemon so you can connect to wireless and wired networks. You will need to load the Connection Manager module. For Bluetooth support you may want bluez installed and load the Bluetooth Manager module. You may want ofono installed, and load the Mobile Modems Manager to get support for wireless modems like 3G UMTS. You may want hal installed if you don't have modern udev support on your system. Enlightenment will discover these services via DBUS at runtime. Note that Enlightenment can run without DBUS, but it will be severely limited in functionality and it is never tested in this scenario.

Also note that for many other libraries and applications you may want or need other dependencies. These will vary from project to project. For example - emotion will require either gstreamer or libxine libraries and development headers to build.

The following handy script will also give you an insight as to how to compile things and in what order:

#!/bin/sh
set -e
PREFIX="/usr/local"
PROJECTS="\
efl evas_generic_loaders e_dbus e"
SITE="svn.enlightenment.org"
SVN="http://$SITE/svn/e/trunk"
OPT="--prefix=$PREFIX"
svn co $SVN
PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH"
PATH="$PREFIX/bin:$PATH"
LD_LIBRARY_PATH="$PREFIX/lib:$LD_LIBRARY_PATH"
for PROJ in $PROJECTS; do
  cd trunk/$PROJ
  make clean distclean || true
  ./autogen.sh $OPT
  make
  sudo make install
  cd ../..
  sudo ldconfig
done

Conventions

We follow many conventions in order to work as a team despite the fact that we are spread around the world, in many different timezones, speak many languages, run multiple operating systems and have divergent goals. These conventions cover how we speak, communicate, what our code looks like, what our source trees look like and more. These conventions help our many disparate libraries at least look somewhat alike and makes maintenance, development and troubleshooting much easier. It also helps with an introduction to Enlightenment and EFL as the rules you learn in one place allow you to quickly discover what you need in another unfamiliar location, as it follows the same conventions.

Language

Our primary language is English. For better or worse it is the one language most of us know better than any other. All documentation, comments and discussion should be in English. It doesn't need to be perfect. It needs to be understandable. So when you write code comments, discuss anything on IRC, in E-Mail or otherwise, please keep it in English.

Coding Style

Our golden rule of coding - FOLLOW THE CODING STYLE ALREADY THERE. That means that if you work on code that already exists, keep to the spacing, indenting, variable and function naming style, etc. that already exists. Don't go changing it mid-file or mid-project. It is even better if you use the same formatting for new projects that has already been used on others. It means the code is easier to read and maintain.

static Eet_File_Node *
_eet_node_find(Eet_File   *ef,
               const char *name)
{
  Eet_File_Node *efn;
  int hash = _eet_hash_gen(name, ef->dir->size);

  for (efn = ef->dir->nodes[hash]; efn; efn = efn->next)
    {
      if (_eet_match(efn->name, name)) return efn;
      else break;
    }
  return NULL;
}

EAPI Eet_Error
eet_sync(Eet_File *ef)
{
  Eet_Error ret;

  if (_eet_check(ef)) return EET_ERROR_BAD;
  if ((ef->mode != EET_MODE_WRITE) &&
      (ef->mode != EET_MODE_READ_WRITE))
    return EET_ERROR_CANNOT_WRITE;
  else
    {
      ef->data = NULL;
      ef->count++;
    }
  ret = eet_flush(ef);
  return ret;
}

Source Trees

We use "autotools" as our build setup. For better or worse this is the predominant "standard" when it comes to build systems in the open source world. It's the devil we know and changing it is an uphill battle that may not actually end up in a better position than where we started. So it's staying, for now.

The configure template file is configure.ac. This determines the package name, version, what it checks for in dependencies and what Makefiles are to be output in what directories. If configure has extra macros we place them inside the m4 directory. Here you will find extra non-default autotools macros for checking of dependencies etc.

Source is structured with source code being in the src directory tree. This in turn is split up into directories like bin (that produces binary executables), lib (that produces shared libraries for others to link to), and modules (that produces module shared objects that the binaries or libraries may dynamically load at runtime to add new features).

The documentation templates and build happens in the doc directory and uses the same template style for html etc. so our documentation looks consistent.

In the data directory you will find possibly many things, but mostly data files that get installed and then needed at runtime such as icons, desktop files, theme files (edj) and so on. This will normally be broken up into sub directories here too.

Some projects have a config directory in which a set of default configuration files are set up and installed by default, maybe split into profiles and more.

In some projects there is even a win32 directory for files related to building that project on windows.

Licenses & Copyright

By default we stick to open source licenses. GPL, LGPL, BSD and so on. The person who starts any project calls the shots on its initial license and it is assumed all people contributing to it do so under the terms of that license. We also respect the licenses of others and their works, so we won't be accepting code that we know is already under an incompatible license. All projects should contain a COPYING file in the base directory of that project that covers all files in that project (unless otherwise stated).

If you want your name listed as an author of a project when you contribute code, PLEASE remember to include your name and E-Mail address as a patch to the AUTHORS file. This way you will have the correct name and contact details listed. All members of the AUTHORS file share copyright over the code they contribute to. So remember to include this change to AUTHORS for the first patch or commit you provide to make sure your name is immortalized in blinking lights in the AUTHORS file.

If you want to begin work on a a feature - something that isn't just a small trivial fix or feature, please discuss it on our mailing lists or IRC channels or both. Generally try and find the person in charge of that component, but if you can't, a broadcast to the devel list should find them. At this point you should discuss your idea and plans. This is where you can find out if someone else is already doing it, if it's a good idea or not, if it can be done better, how it should be done etc. Once you get agreement, you will know what to do next. Doing work and then just dumping it on developers as a surprise generally doesn't get a positive response. It was unexpected and often quite large. If you send small patches and changes over many days or weeks, as opposed to wait weeks or even months then send a single massive patch, you will get much better response. Big patches discourage review as time to review it is large and most developers just don't have such large blocks of time. Lots of smaller steps always works better.

Join us

If you join us you'll be welcomed into a community of developers and users who like to do cool things and actually make them happen. If you join you will not only be able to hang out with us (well you can anyway), you'll actually start to have a say in how Enlightenment and EFL develop, if not actually get some control. It also reduces a massive amount of work involved in maintaining forks as your work becomes mainline and gets shared, tested and maintained by a wider audience earlier, not to mention it likely becomes much better quality. If you are not into doing code, maybe you can help in other ways like with advertising and publicity, documentation and packaging, if not just regular bug reporting.

To report a bug please see the contact page. To submit initial patches for code, please send them to the mailing list after discussions have taken place. Keep patches small and send them, often as you work. Small patches get reviewed quickly. Large patches get delayed or sometimes ignored or lost. Make sure that any patch at least compiles and doesn't break an existing functionality (so make the changes enableable at compile or runtime as part of the patch if it does intersect with existing functionality). You will get feedback on your patches and may be asked to make changes before inclusion. Also remember to respect the formatting and conventions of the existing code as it gets a bit tedious asking for basic changes like naming, spacing and general style. We'd rather focus on the actual algorithms and features involved. Refer the Archanist wiki page for the check points when you want to submit a patch.

If you want developer access (GIT commit access) first you will need an existing developer to approve that. Generally any senior or long time developer can do it - new ones can too but will probably defer the OK decision to a senior developer first. To gain access we need you to provide a few files. The kind of files you find in this developer's directory.

The info.txt file provides general information about you. Please fill one in with relevant information needed, with your Login being the developer login name you'd like, as well as other important fields. If you are new the Managing and Contributing fields may be empty, as well as Group, but please provide everything else including your location in the world as well as actual Geographic data.

The id_rsa.pub is your SSH public key. You will find this in your ~/.ssh directory. If you don't have one yet, you can generate one with:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

for example. You should read the SSH manuals for more information if you need it. This SSH key will give you access to GIT so you can check out and commit code, with all traffic between you and enlightenment.org being encrypted.

As an addition we also ask you to provide some photos/images/icons of yourself so we can put a face to a name. Take a look at the example ones in the above developer directory. Provide images of the exact same size in pixels, with the icon-map.png file having an arrow at the bottom pointing down. This image is used on our world developer map.

If you can't write code, you can always help by writing documentation or articles or blogs. Contributing content to our wiki site that may help other users is always useful. We also always can do with artwork and graphics people. People who do artwork would be able to get developer access as they will need access to the source trees so they can put their artwork in there anyway. We also can always do with people helping translate things. We use gettext like most open source software, so it's as simple as providing us with new or updated .PO files. We even have a dedicated mailing list for just this purpose.

Otherwise, debugging is also something that is always needed. No code is perfect. It's written by humans. But bugs need to be fixed and to help you help us find the bugs we don't see, but you do, see our debugging page that lets you know how to begin to find bugs and provide useful feedback.