/**\page hello An "Hello, World" example
A canonical Gabi application always implements the Herbs::Application interface. The idea behind this construction is that it makes it possible to run the application more than once without having to reload its settings. Also, it makes it possible to run several instances within the same process, either as separate threads or synchronously.

The default main calls an user-defined function called  Herbs::Application::instanceCreate. This function creates a new application object and returns a pointer to it. Then, the method Herbs::Application::init is called who is responsible for converting the given Herbs::Directory to a, from the application view, more useful format. The method Herbs::Application::run is responsible for performing the actual task.

\section hellocomp Compiling the example
First, make sure that the steps in the chapter \ref install has been followed. The "Hello, World" application is compiled by invoking the \ref UtilsWand utility. To compile the example application, open a command prompt or terminal and enter the <code>hello-world</code> directory in root directory of the Gabi tree. Then run
\code
wand
\endcode
After wand has terminated, invoking
\code
__wand_targets/gabi-hello
\endcode
prints the text "Hello, World".

The application, and its include files and object files, can be installed by running
\code
wand "config_set[components[Wand[actions[install]]]]"
\endcode
Assuming a special installation profile called <code>install</code> has been added to the global \ref UtilsWand configuration file, it is also possible to just invoke the command
\code
wand "profile[install]"
\endcode
For all options that can be passed to Wand, see \ref UtilsWandInvoke.

\section Files
The canonical "Hello, World" application using Gabi consists of four files:
<ul>
	<li><code>wandcfg.spell</code> sets parameters for \ref UtilsWand. Typically, the only project specific options are input directories and the name of the $term_ref("herbarium","herbarium").</li>
	<li>hello.h defining the HelloWorld class</li>
	<li>hello.cpp implementing functions in the Hello::HelloWorld class</li>
	<li>hello-main.cpp implementing the Herbs::Application::instanceCreate</li>
</ul>

This structure improves the re-usability: while only hello.h and hello.cpp are necessary to define the behavior of the application, it is necessary to separate Herbs::Application::instanceCreate from the application definition to avoid multiple definition of that function.

\subsection hellowandcfg wandcfg.spell
The contents of <code>wandcfg.spell</code> is the following:
\include hello-world/wandcfg.spell

This tells \ref UtilsWand to compile all files inside the current directory, and copy files to a subdirectory called <code>hello-world</code> when the application is installed. The actual location is determined by the global \ref UtilsWand configuration file.

\subsection hellohelloh hello.h

\dontinclude hello.h
In general, all files begins with a <code>wand</code> directive. In particular, all target declarations must be placed before <em>any</em> include directive. Otherwise, there will be no target that can have dependencies when the dependencies from the include directives are to be added, resulting in these dependencies being ignored, which in turn results in undefined references when linking.

\line WAND
The macro <code>__WAND__</code> is used for testing if the file is being processed by <code>wand</code>. It should be noted that Wand does not perform a full preprocessing. From Wand's point of view
\code{.cpp}
#ifdef __WAND__
\endcode
works as a marker indicating that the following data should be read as a \ref Spell directory.

\line dependency[
When this files is included, the files that included this file will need to link to the file <code>hello.o</code>.

\line target
This file should be installed as an include file.
\line endif

\until define
Guard blocks are used to avoid double inclusion of the file.

\line include
Since this files defines a class inheriting from the Herbs::Application class, the include file for that class is included. This include directive will be followed by <code>wand</code>, which if it can find the file, continues to add dependencies and walk through other include files.

\until {
It is a good idea to try to avoid name conflicts. Therefore, all classes used by the application should be declared inside a namespace.

\until }
This is the class definition. The Herbs::Application::init function is not overridden since the "Hello, World" program does not require any arguments.

\until endif

\subsection hellohellocpp hello.cpp
This file defines all functions in the Hello::HelloWorld class.

\dontinclude hello.cpp

\until target
This file should be compiled into object code in the file <code>hello.o</code>. The file should be used on any platform.

\line endif

\until string
These include files are nessecary to compile this file. By including hello.h and herbs/string.h, the dependencies from these files are added to the dependency list for the target <code>hello.o</code> recursivly.


\until }
The run function creates a Herbs::String and sends it to the standard output stream associated with this application object.

\until }
Since Herbs::Application::instanceCreate creates objects using new, this function lets the object commit suicide by saying \code delete this;\endcode

\subsection hellohellomain hello-main.cpp
The sole purpose of this file is to define Herbs::Application::instanceCreate.
\dontinclude hello-main.cpp
\until target
This file should be compiled and linked into an executable file called <code>hello.exe</code> on Windows

\until target
The output filename on other platforms is <code>hello</code>.
\until endif

\until maindefault
Since the function Herbs::Application::instanceCreate should return a new Hello::HelloWorld object, the file hello.h is included. Also, to make it link against the main function defined by Gabi, the file maindefault.h is included.

\until }
The function Herbs::Application::instanceCreate create a new GabiHello::HelloWorld. Note that this may throw an exception, that will cause the application to terminate. However, at this point, there should be enough memory to allocate a new object. Also it is assumed that the constructor of an Herbs::Application never throws other exceptions.

*/
