Hello World

This tutorial will guide you through the necessary steps to build your first "Hello World" example program using the Enlightenment Foundation Libraries (EFL). Before continuing make sure you have read the Setting up the Development Environment guide.

There is very little code in this first tutorial so don't worry if you have little coding experience. The main goal is to build and execute an application using EFL. You will need a basic knowledge of C to get started.

Step One: Defines and Includes

Using your favorite text editor, create a text file and save it as hello-world.c. Type in the following:

#define EFL_BETA_API_SUPPORT 1
 
#include <Efl_Core.h>

The new EFL API has been in Beta stage for a while, and some libraries still need that you define the EFL_BETA_API_SUPPORT symbol before including any EFL library. Don't worry, though, they should not be required any more in the near future.

The EFL is split into several libraries. You only need to include the ones you actually want to use. In this tutorial you will be calling methods from the Eina and Efl libraries, therefore you just need to include the Efl_Core.h header which includes Eina.h and Efl.h.

You will explore the EFL libraries in greater depth in later tutorials. Other examples are Efl_Net.h for network operations and Efl_Ui.h to create User Interface elements like windows and buttons.

Step Two: Main Function

Instead of the main() function marking the standard C entry point EFL uses efl_main(). Type the following underneath the includes section of your program:

[...]
 
void
efl_main(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
}

NOTE: [...] in a Code Block indicates existing code which has been excluded for the sake of brevity. There is no need to type [...] into your program.

EFL takes care of all initialization tasks and calls your efl_main() method when everything is ready.

At this point the parameters to efl_main() are not being used, hence the EINA_UNUSED macro. This is optional but it gets rid of warnings regarding unused parameters so it's worth having. Moreover, the data argument will always be NULL in these tutorials.

Step Three: Print "Hello World"

Type the following between the curly brackets of efl_main():

[...]
   printf("Hello World!\n");
[...]

This is a regular C printf() which will output the "Hello World" string to the console.

Step Four: Exiting

Any programs you create with EFL must always terminate by calling efl_exit(). This is an important difference to the regular C main(), where a program exits when it reaches the end of a method. Enter the following below your printf():

[...]
    efl_exit(0);
[...]

The parameter in efl_exit() is the value your program returns to the operating system.

Step Five: Automatic EFL Setup and Shutdown

This final piece of "boilerplate" code should be included at the end of every EFL program. Type the following at the very end of your program as the last line:

[...]
EFL_MAIN()

This defines the real main() method required by C programs, which deals with initialization and deinitilization tasks. It also eventually calls the efl_main() method that you defined above.

This is not mandatory but it simplifies the setup and shutdown processes considerably, so it is going to be used a lot in this series of tutorials.

Your program should now look something like this:

#define EFL_BETA_API_SUPPORT 1
 
#include <Efl_Core.h>
 
void
efl_main(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Hello World!\n");
   efl_exit(0);
}
 
EFL_MAIN()

Save the program then build it as outlined in Setting up the Development Environment. As a reminder, if you are using the gcc compiler, run:

gcc -o hello-world hello-world.c `pkg-config --cflags --libs ecore`

If the systems displays no errors, your program should be ready. Test it by typing:

./hello-world

The words Hello World! should now appear on your terminal.

Step Six: Retrieve the Command Line Parameters

Sometimes you might be interested in retrieving the command line parameters passed to your program. They are passed to efl_main() but in a slightly different way than they are usually passed to main().

Replace your current efl_main() with this slightly modified version:

[...]
EAPI_MAIN void
efl_main(void *data EINA_UNUSED, const Efl_Event *ev)
{
   Efl_Loop_Arguments *args = ev->info;
 
   if (eina_array_count(args->argv) <= 1)
     {
        printf("Hello World!\n");
     }
   else
     {
        printf("Hello %s!\n", (char *) eina_array_data_get(args->argv, 1));
     }
 
   efl_exit(0);
}

As you can see, the Efl_Event *ev parameters is no longer marked with EINA_UNUSED, because now you are going to use it:

The Efl_Event structure contains an array with all the command line parameters. You retrieve it like this:

[...]
   Efl_Loop_Arguments *args = ev->info;
[...]

Finally, the array can be found in args->argv. Arrays in EFL are handled with the Eina_Array type, so you can use eina_array_count() to retrieve the number of elements in an array and eina_array_data_get() to access the contents of the array.

In the above example, if no parameters are passed to your program (eina_array_count(args->argv) == 0), it just prints "Hello World!". Otherwise, the first parameter is retrieved and printed. Try compiling again your program and running it with your name as the first parameter:

./hello-world Mike

Summary

At the end of this tutorial you have learned:

Header files must be included for any EFL libraries you intend to use. Typically, these are Efl_Core.h or Efl_Ui.h.
Your main method should be efl_main().
Your EFL programs should always call efl_exit() at some stage.
Your EFL programs should include the EFL_MAIN() macro at the end so EFL can insert its own start-up and shutdown code.
Command line parameters are available through the Efl_Event * parameter in efl_main(), and can be accessed with eina_array_count() and eina_array_data_get().

Navigation

Page Contents