====== Basic EDE Application ======

This tutorial will show how to integrate simple EDE application with EDE tree and build system. Application will be built when the whole tree was built and installed with other EDE applications at default location or location user specified during configure phase.

===== Introduction =====

The main tool for building EDE and edelib source is [[http://www.perforce.com/jam/jam.html|jam]]. Jam is a nice replacement for make (and the mess called Automake) providing a good facility for writing sane compile scripts. Jam's [[http://public.perforce.com/public/jam/src/Jamfile.html|reference and documents]] gives a good starting point where you can find all details about the language and available jam functions.

EDE build system is designed to allow writing quick and short build scripts, without much messing with jam language. Currently, EDE specific build API is not documented which is planned for the future.

===== Source Tree =====

EDE source tree is made of top build scripts and bunch of directories, representing a single application or set of the similar applications. Currently, EDE tree looks like this:
<code>
ede/
 Jamconfig.in
 Jamfile
 Jamrules
 autogen.sh
 configure.in
 build/
 data/
 ede-about/
 ede-autostart/
 ...
</code>

Adding your application is a matter of creating a directory in this tree and setting up some jam scripts. Rest of the job, like compiling, installing and uninstalling will be done by build system.

===== Sample Application =====

Now we will write some actual application, called ''ede-hello''. This must be done in EDE source tree because you will need to have access to build scripts and script helpers.

''ede-hello'' will be made of example source code from EdelibBasics where the final application should show a window with "Hello World" in it.

First create directory in EDE source directory; for this tutorial it will be ''ede-hello'', like:
<code>
 cd ede/
 mkdir ede-hello
</code>

Now, in ''ede-hello'' directory, create ''ede-hello.cpp'' with the following content:

<code cpp>
/* ede-hello.cpp */

#include <FL/Fl.H>
#include <FL/Fl_Box.H>
#include <edelib/Ede.h>
#include <edelib/Window.h>

EDELIB_NS_USING_AS(Window, MainWindow)

int main(int argc, char **argv) {
  EDE_APPLICATION("ede-hello");

  MainWindow *window = new MainWindow(300,180);
  Fl_Box *box = new Fl_Box(20,40,260,100,"Hello, World!");
  box->box(FL_UP_BOX);
  box->labelsize(36);
  box->labelfont(FL_BOLD+FL_ITALIC);
  box->labeltype(FL_SHADOW_LABEL);
  window->end();
  window->show(argc, argv);
  return Fl::run();
}
</code>

Then create ''Jamfile'' file, with this content:
<code>
SubDir TOP ede-hello ;

SRC = ede-hello.cpp ;

EdeProgram ede-hello : $(SRC) ;
TranslationStrings locale : $(SRC) ;
</code>

:!: In case you wrote make scripts before, ''Jamfile'' to jam is pretty much the same as ''Makefile'' to make.

At the end, the tree should look like this:
<code>
ede/
  ede-hello/
    Jamfile
    ede-hello.cpp
</code>

The only thing left to be done is to "register" your application in main Jamfile, so jam could know what to build in a single run. This file is ''ede/Jamfile''.

<code>
# ede/Jamfile

SubDir TOP ;

EdeManualWithToc README ;
Clean distclean : $(JCACHEFILE) $(HCACHEFILE) ;

SubInclude TOP ede-about ;
...
SubInclude TOP ede-help ;

# your application
SubInclude TOP ede-hello ;
</code>

:!: Watch for extra space before semicolon; this is required by jam parser.

Now, all hard work will be done by jam. Besides ede-hello.cpp will be compiled and installed, jam will also extract translatable strings and store it in ''ede/ede-hello/locale/messages.pot'' file, so translators can use it as source for language specific translations.

===== Make It Translatable =====
To allow your application to speak on different languages and give ''!TranslationStrings'' something to extract, you will need to mark translatable strings. EDE's main translation facility is located in ''edelib/Nls.h'' header, so we will add it to our example.
<code cpp>
/* ede-hello.cpp */

#include <FL/Fl.H>
#include <FL/Fl_Box.H>
#include <edelib/Ede.h>
#include <edelib/Window.h>

/* include translation facility */
#include <edelib/Nls.h>

EDELIB_NS_USING_AS(Window, MainWindow)
</code>

Now, to make our ''Hello, World'' string to appear differently on different languages, we will mark it as:
<code cpp>
int main(int argc, char **argv) {
  EDE_APPLICATION("ede-hello");

  MainWindow *window = new MainWindow(300,180);
  Fl_Box *box = new Fl_Box(20,40,260,100, _("Hello, World!"));
  ...
  return Fl::run();
}
</code>

by using ''_()'' construct. If you are going to disallow translation of certain strings (and clearly mark it as that to anyone happen to read your code), you should use ''N_()'', like:

<code cpp>
  ...
  Fl_Box *box = new Fl_Box(20,40,260,100, N_("Hello, World!"));
  ...
</code>


===== Magic EDE_APPLICATION macro =====

Each application should call **EDE_APPLICATION** macro, preferable after application entry point (e.g. ''main()'' function), where first and only parameter should be application binary name. This macro will setup needed ingredients like correct localization path, logging facility, probably load theme or icon theme suport and etc. Content of this macro can be changed in the future, but thankfully to language macro facility, only recompilation of target application will be needed.

Console applications (those who will not run any GUI part, nor will make connection to X server) should use '''EDE_CONSOLE_APPLICATION'''. This macro will will just setup localization path based on application name.