= Quick how to for adding program to HelenOS =

Following steps are needed in order to add a program to HelenOS (i.e. executable that can be launched from HelenOS userspace shell).

== Sources location ==
Under one of `uspace/` directories. Use `app/` for standalone applications, `srv/` for system services or `drv/` for device drivers.

Definitely put it inside its own subdirectory (e.g. `uspace/app/hello/`).

The `main` uses standard signature `int main(int, char **)`.

== `Makefile`s & co. ==
Simplest way is to copy `Makefile` from other program and change two variables:
 * `BINARY` to specify name of the compiled executable
 * `SOURCES` to list C source files

For a simple ''Hello World'' program, the `Makefile` would look like this (omitting the copyright notice):
{{{
#!Makefile
USPACE_PREFIX = ../..
BINARY = hello
SOURCES = hello.c
include $(USPACE_PREFIX)/Makefile.common
}}}

== Compiling ==
To compile the program, add the directory name (e.g. `app/hello`) to `DIRS` variable in `uspace/Makefile`.

== Adding it to the image ==
Last thing that needs to be done is to add the compiled executable to the image file (e.g. `image.iso` for IA-32). That is done by adding the executable filename to a variable in `boot/Makefile.common`.
For services use the `RD_SRVS_*` variable, for application use `RD_APPS_*`. The suffix is either `ESSENTIAL` or `NON_ESSENTIAL`.

== C++ support ==
Since HelenOS 0.7.2, all source files with the extensions `.cpp`, `.cxx` and `.cc` are compiled as C++17 source files with (at the moment) access
to most C++14 standard library features.

== Complete diff ==
Below is a diff (with copyrights omitted) for a ''Hello World''.
{{{
=== modified file 'boot/Makefile.common'
--- boot/Makefile.common	2011-06-12 15:44:38 +0000
+++ boot/Makefile.common	2011-06-12 20:45:19 +0000
@@ -142,6 +142,7 @@
 	$(USPACE_PATH)/app/dload/dload \
 	$(USPACE_PATH)/app/edit/edit \
 	$(USPACE_PATH)/app/ext2info/ext2info \
+	$(USPACE_PATH)/app/hello/hello \
 	$(USPACE_PATH)/app/kill/kill \
 	$(USPACE_PATH)/app/killall/killall \
 	$(USPACE_PATH)/app/mkfat/mkfat \

=== modified file 'uspace/Makefile'
--- uspace/Makefile	2011-06-12 15:44:38 +0000
+++ uspace/Makefile	2011-06-12 20:44:44 +0000
@@ -39,6 +39,7 @@
 	app/edit \
 	app/ext2info \
 	app/getterm \
+	app/hello \
 	app/init \
 	app/kill \
 	app/killall \

=== added directory 'uspace/app/hello'
=== added file 'uspace/app/hello/Makefile'
--- uspace/app/hello/Makefile	1970-01-01 00:00:00 +0000
+++ uspace/app/hello/Makefile	2011-06-12 20:43:41 +0000
@@ -0,0 +1,12 @@
+#
+# Copyright omitted
+#
+
+USPACE_PREFIX = ../..
+
+BINARY = hello
+SOURCES = \
+	hello.c
+
+include $(USPACE_PREFIX)/Makefile.common
+

=== added file 'uspace/app/hello/hello.c'
--- uspace/app/hello/hello.c	1970-01-01 00:00:00 +0000
+++ uspace/app/hello/hello.c	2011-06-12 20:44:18 +0000
@@ -0,0 +1,9 @@
+/* Copyright omitted */
+
+#include <stdio.h>
+
+int main(int argc, char * argv[]) {
+	printf("Hello World!\n");
+	return 0;
+}
+
}}}