From 2ddafe323adb2cc0e3481153f5f899a9ee86f7f5 Mon Sep 17 00:00:00 2001 From: raster Date: Tue, 9 Aug 2011 07:46:12 +0000 Subject: [PATCH] move getting started to header. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/elementary@62228 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/Elementary.h.in | 245 +++++++++++++++++++++++++++++++++++++++++++++++- src/lib/elm_main.c | 240 ----------------------------------------------- 2 files changed, 244 insertions(+), 241 deletions(-) diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index 3d3022c..849a0dd 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -11,7 +11,7 @@ /** @mainpage Elementary @image html elementary.png -@version @PACKAGE_VERSION@ +@version 0.7.0 @date 2008-2011 @section intro What is Elementary? @@ -22,6 +22,8 @@ applications (yet). Small simple ones with simple needs. It is meant to make the programmers work almost brainless but give them lots of flexibility. +@li @ref Start - Go here to quickly get started with writing Apps + @section organization Organization One can divide Elemementary into three main groups: @@ -42,6 +44,247 @@ gender, race or nationality - and that is really tough. So thanks to people and organisations behind this, as listed in the @ref authors page. */ + +/** + * @defgroup Start Getting Started + * + * To write an Elementary app, you can get started with the following: + * + * @code + * #include + * #ifndef ELM_LIB_QUICKLAUNCH + * EAPI int + * elm_main(int argc, char **argv) + * { + * // create window(s) here and do any application init + * elm_run(); // run main loop + * elm_shutdown(); // after mainloop finishes running, shutdown + * return 0; // exit 0 for exit code + * } + * #endif + * ELM_MAIN() + * @endcode + * + * To take full advantage of the quicklaunch architecture for launching + * processes as quickly as possible (saving time at startup time like + * connecting to X11, loading and linking shared libraries) you may want to + * use the following configure.in/configure.ac and Makefile.am and autogen.sh + * script to generate your files. It is assumed your application uses the + * main.c file for its code. + * + * configure.in/configure.ac: + * +@verbatim +AC_INIT(myapp, 0.0.0, myname@mydomain.com) +AC_PREREQ(2.52) +AC_CONFIG_SRCDIR(configure.in) + +AM_INIT_AUTOMAKE(1.6 dist-bzip2) +AM_CONFIG_HEADER(config.h) + +AC_C_BIGENDIAN +AC_ISC_POSIX +AC_PROG_CC +AM_PROG_CC_STDC +AC_HEADER_STDC +AC_C_CONST + +AC_LIBTOOL_WIN32_DLL +define([AC_LIBTOOL_LANG_CXX_CONFIG], [:])dnl +define([AC_LIBTOOL_LANG_F77_CONFIG], [:])dnl +AC_PROG_LIBTOOL + +PKG_CHECK_MODULES([ELEMENTARY], elementary) + +AC_OUTPUT(Makefile) +@endverbatim + * + * Makefile.am: + * +@verbatim +AUTOMAKE_OPTIONS = 1.4 foreign +MAINTAINERCLEANFILES = Makefile.in + +INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@ + +bin_PROGRAMS = myapp +myapp_LTLIBRARIES = myapp.la + +myappdir = $(libdir) + +myapp_la_SOURCES = main.c +myapp_la_LIBADD = @ELEMENTARY_LIBS@ +myapp_la_CFLAGS = +myapp_la_LDFLAGS = -module -avoid-version -no-undefined + +myapp_SOURCES = main.c +myapp_LDADD = @ELEMENTARY_LIBS@ +myapp_CFLAGS = -DELM_LIB_QUICKLAUNCH=1 +@endverbatim + * + * autogen.sh: + * +@verbatim +#!/bin/sh +rm -rf autom4te.cache +rm -f aclocal.m4 ltmain.sh +rm -rf m4 +mkdir m4 + +touch README +echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS -I m4 || exit 1 +echo "Running autoheader..." ; autoheader || exit 1 +echo "Running autoconf..." ; autoconf || exit 1 +echo "Running libtoolize..." ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1 +echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1 + +if [ -z "$NOCONFIGURE" ]; then + ./configure "$@" +fi +@endverbatim + * + * To gnerate all the things needed to bootstrap just run: + * +@verbatim +./autogen.sh +@endverbatim + * + * This will generate Makefile.in's, the confgure script and everything else. + * After this it works like all normal autotools projects: +@verbatim +./configure +make +sudo make install +@endverbatim + * + * Note sudo was assumed to get root permissions, as this would install in + * /usr/local which is system-owned. Use any way you like to gain root, or + * specify a different prefix with configure: + * +@verbatim +./confiugre --prefix=$HOME/mysoftware +@endverbatim + * + * Also remember that autotools buys you some useful commands like: +@verbatim +make uninstall +@endverbatim + * + * This uninstalls the software after it was installed with "make install". + * It is very useful to clear up what you built if you wish to clean the + * system. + * +@verbatim +make distcheck +@endverbatim + * + * This firstly checks if your build tree is "clean" and ready for + * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is + * ready to upload and distribute to the world, that contains the generated + * Makefile.in's and configure script. The users do not need to run + * autogen.sh - just configure and on. They don't need autotools installed. + * This tarball also builds cleanly, has all the sources it needs to build + * included (that is sources for your application, not libraries it depends + * on like Elementary). It builds cleanly in a buildroot and does not + * contain any files that are temporarily generated like binaries and other + * build-generated files, so the tarball is clean, and no need to worry + * about cleaning up your tree before packaging. + * +@verbatim +make clean +@endverbatim + * + * This cleans up all build files (binaries, objects etc.) from the tree. + * +@verbatim +make distclean +@endverbatim + * + * This cleans out all files from the build and from configure's output too. + * +@verbatim +make maintainer-clean +@endverbatim + * + * This deletes all the files autogen.sh will produce so the tree is clean + * to be put into a revision-control system (like CVS, SVN or GIT for example). + * + * The above will build a library - libmyapp.so and install in the target + * library directory (default is /usr/local/lib). You will also get a + * myapp.a and myapp.la - these are useless and can be deleted. Libtool likes + * to generate these all the time. You will also get a binary in the target + * binary directory (default is /usr/local/bin). This is a "debug binary". + * This will run and dlopen() the myapp.so and then jump to it's elm_main + * function. This allows for easy debugging with GDB and Valgrind. When you + * are ready to go to production do the following: + * + * 1. delete the myapp binary. i.e. rm /usr/local/bin/myapp + * + * 2. symlink the myapp binary to elementary_run (supplied by elementary). + * i.e. ln -s elmentary_run /usr/local/bin/myapp + * + * 3. run elementary_quicklaunch as part of your graphical login session and + * keep it running. + * + * This will man elementary_quicklaunch does pre-initialization before the + * application needs to be run, saving the effort at the time the application + * is needed, thus speeding up the time it takes to appear. + * + * If you don't want to use the quicklaunch infrastructure (which is + * optional), you can execute the old fashioned way by just running the + * myapp binary loader than will load the myapp.so for you, or you can + * remove the split-file binary and put it into one binary as things always + * have been with the following configure.in/configure.ac and Makfile.am + * files: + * + * configure.in/configure.ac: + * +@verbatim +AC_INIT(myapp, 0.0.0, myname@mydomain.com) +AC_PREREQ(2.52) +AC_CONFIG_SRCDIR(configure.in) + +AM_INIT_AUTOMAKE(1.6 dist-bzip2) +AM_CONFIG_HEADER(config.h) + +AC_C_BIGENDIAN +AC_ISC_POSIX +AC_PROG_CC +AM_PROG_CC_STDC +AC_HEADER_STDC +AC_C_CONST + +PKG_CHECK_MODULES([ELEMENTARY], elementary) + +AC_OUTPUT(Makefile) +@endverbatim + * + * Makefile.am: + * +@verbatim +AUTOMAKE_OPTIONS = 1.4 foreign +MAINTAINERCLEANFILES = Makefile.in + +INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@ + +bin_PROGRAMS = myapp + +myapp_SOURCES = main.c +myapp_LDADD = @ELEMENTARY_LIBS@ +myapp_CFLAGS = +@endverbatim + * + * Notice that they are the same as before, just with libtool and library + * building sections removed. Both ways work for building elementary + * applications. It is up to you to decide what is best for you. If you just + * follow the template above, you can do it both ways and can decide at build + * time. The more advanced of you may suggest making it a configure option. + * That is perfectly valid, but has been left out here for simplicity, as our + * aim to have an Elementary (and EFL) tutorial, not an autoconf & automake + * document. + * + */ + /** @page authors Authors @author Carsten Haitzler diff --git a/src/lib/elm_main.c b/src/lib/elm_main.c index 6196e33..406b14d 100644 --- a/src/lib/elm_main.c +++ b/src/lib/elm_main.c @@ -46,246 +46,6 @@ _elm_dangerous_call_check(const char *call) return 1; } -/** - * @defgroup Start Getting Started - * - * To write an Elementary app, you can get started with the following: - * - * @code - * #include - * #ifndef ELM_LIB_QUICKLAUNCH - * EAPI int - * elm_main(int argc, char **argv) - * { - * // create window(s) here and do any application init - * elm_run(); // run main loop - * elm_shutdown(); // after mainloop finishes running, shutdown - * return 0; // exit 0 for exit code - * } - * #endif - * ELM_MAIN() - * @endcode - * - * To take full advantage of the quicklaunch architecture for launching - * processes as quickly as possible (saving time at startup time like - * connecting to X11, loading and linking shared libraries) you may want to - * use the following configure.in/configure.ac and Makefile.am and autogen.sh - * script to generate your files. It is assumed your application uses the - * main.c file for its code. - * - * configure.in/configure.ac: - * -@verbatim -AC_INIT(myapp, 0.0.0, myname@mydomain.com) -AC_PREREQ(2.52) -AC_CONFIG_SRCDIR(configure.in) - -AM_INIT_AUTOMAKE(1.6 dist-bzip2) -AM_CONFIG_HEADER(config.h) - -AC_C_BIGENDIAN -AC_ISC_POSIX -AC_PROG_CC -AM_PROG_CC_STDC -AC_HEADER_STDC -AC_C_CONST - -AC_LIBTOOL_WIN32_DLL -define([AC_LIBTOOL_LANG_CXX_CONFIG], [:])dnl -define([AC_LIBTOOL_LANG_F77_CONFIG], [:])dnl -AC_PROG_LIBTOOL - -PKG_CHECK_MODULES([ELEMENTARY], elementary) - -AC_OUTPUT(Makefile) -@endverbatim - * - * Makefile.am: - * -@verbatim -AUTOMAKE_OPTIONS = 1.4 foreign -MAINTAINERCLEANFILES = Makefile.in - -INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@ - -bin_PROGRAMS = myapp -myapp_LTLIBRARIES = myapp.la - -myappdir = $(libdir) - -myapp_la_SOURCES = main.c -myapp_la_LIBADD = @ELEMENTARY_LIBS@ -myapp_la_CFLAGS = -myapp_la_LDFLAGS = -module -avoid-version -no-undefined - -myapp_SOURCES = main.c -myapp_LDADD = @ELEMENTARY_LIBS@ -myapp_CFLAGS = -DELM_LIB_QUICKLAUNCH=1 -@endverbatim - * - * autogen.sh: - * -@verbatim -#!/bin/sh -rm -rf autom4te.cache -rm -f aclocal.m4 ltmain.sh -rm -rf m4 -mkdir m4 - -touch README -echo "Running aclocal..." ; aclocal $ACLOCAL_FLAGS -I m4 || exit 1 -echo "Running autoheader..." ; autoheader || exit 1 -echo "Running autoconf..." ; autoconf || exit 1 -echo "Running libtoolize..." ; (libtoolize --copy --automake || glibtoolize --automake) || exit 1 -echo "Running automake..." ; automake --add-missing --copy --gnu || exit 1 - -if [ -z "$NOCONFIGURE" ]; then - ./configure "$@" -fi -@endverbatim - * - * To gnerate all the things needed to bootstrap just run: - * -@verbatim -./autogen.sh -@endverbatim - * - * This will generate Makefile.in's, the confgure script and everything else. - * After this it works like all normal autotools projects: -@verbatim -./configure -make -sudo make install -@endverbatim - * - * Note sudo was assumed to get root permissions, as this would install in - * /usr/local which is system-owned. Use any way you like to gain root, or - * specify a different prefix with configure: - * -@verbatim -./confiugre --prefix=$HOME/mysoftware -@endverbatim - * - * Also remember that autotools buys you some useful commands like: -@verbatim -make uninstall -@endverbatim - * - * This uninstalls the software after it was installed with "make install". - * It is very useful to clear up what you built if you wish to clean the - * system. - * -@verbatim -make distcheck -@endverbatim - * - * This firstly checks if your build tree is "clean" and ready for - * distribution. It also builds a tarball (myapp-0.0.0.tar.gz) that is - * ready to upload and distribute to the world, that contains the generated - * Makefile.in's and configure script. The users do not need to run - * autogen.sh - just configure and on. They don't need autotools installed. - * This tarball also builds cleanly, has all the sources it needs to build - * included (that is sources for your application, not libraries it depends - * on like Elementary). It builds cleanly in a buildroot and does not - * contain any files that are temporarily generated like binaries and other - * build-generated files, so the tarball is clean, and no need to worry - * about cleaning up your tree before packaging. - * -@verbatim -make clean -@endverbatim - * - * This cleans up all build files (binaries, objects etc.) from the tree. - * -@verbatim -make distclean -@endverbatim - * - * This cleans out all files from the build and from configure's output too. - * -@verbatim -make maintainer-clean -@endverbatim - * - * This deletes all the files autogen.sh will produce so the tree is clean - * to be put into a revision-control system (like CVS, SVN or GIT for example). - * - * The above will build a library - libmyapp.so and install in the target - * library directory (default is /usr/local/lib). You will also get a - * myapp.a and myapp.la - these are useless and can be deleted. Libtool likes - * to generate these all the time. You will also get a binary in the target - * binary directory (default is /usr/local/bin). This is a "debug binary". - * This will run and dlopen() the myapp.so and then jump to it's elm_main - * function. This allows for easy debugging with GDB and Valgrind. When you - * are ready to go to production do the following: - * - * 1. delete the myapp binary. i.e. rm /usr/local/bin/myapp - * - * 2. symlink the myapp binary to elementary_run (supplied by elementary). - * i.e. ln -s elmentary_run /usr/local/bin/myapp - * - * 3. run elementary_quicklaunch as part of your graphical login session and - * keep it running. - * - * This will man elementary_quicklaunch does pre-initialization before the - * application needs to be run, saving the effort at the time the application - * is needed, thus speeding up the time it takes to appear. - * - * If you don't want to use the quicklaunch infrastructure (which is - * optional), you can execute the old fashioned way by just running the - * myapp binary loader than will load the myapp.so for you, or you can - * remove the split-file binary and put it into one binary as things always - * have been with the following configure.in/configure.ac and Makfile.am - * files: - * - * configure.in/configure.ac: - * -@verbatim -AC_INIT(myapp, 0.0.0, myname@mydomain.com) -AC_PREREQ(2.52) -AC_CONFIG_SRCDIR(configure.in) - -AM_INIT_AUTOMAKE(1.6 dist-bzip2) -AM_CONFIG_HEADER(config.h) - -AC_C_BIGENDIAN -AC_ISC_POSIX -AC_PROG_CC -AM_PROG_CC_STDC -AC_HEADER_STDC -AC_C_CONST - -PKG_CHECK_MODULES([ELEMENTARY], elementary) - -AC_OUTPUT(Makefile) -@endverbatim - * - * Makefile.am: - * -@verbatim -AUTOMAKE_OPTIONS = 1.4 foreign -MAINTAINERCLEANFILES = Makefile.in - -INCLUDES = -I$(top_srcdir) @ELEMENTARY_CFLAGS@ - -bin_PROGRAMS = myapp - -myapp_SOURCES = main.c -myapp_LDADD = @ELEMENTARY_LIBS@ -myapp_CFLAGS = -@endverbatim - * - * Notice that they are the same as before, just with libtool and library - * building sections removed. Both ways work for building elementary - * applications. It is up to you to decide what is best for you. If you just - * follow the template above, you can do it both ways and can decide at build - * time. The more advanced of you may suggest making it a configure option. - * That is perfectly valid, but has been left out here for simplicity, as our - * aim to have an Elementary (and EFL) tutorial, not an autoconf & automake - * document. - * - */ - static Eina_Bool _elm_signal_exit(void *data, int ev_type, void *ev); -- 2.7.4