This group discusses the functions that provide the ability to determine the runtime location of a software package. More...
Typedefs | |
| typedef struct _Eina_Prefix | Eina_Prefix |
| An opaque type for prefix handle. More... | |
Functions | |
| EINA_API Eina_Prefix * | eina_prefix_new (const char *argv0, void *symbol, const char *envprefix, const char *sharedir, const char *magicsharefile, const char *pkg_bin, const char *pkg_lib, const char *pkg_data, const char *pkg_locale) |
| Creates a new prefix handle given that some input information is provided. More... | |
| EINA_API void | eina_prefix_free (Eina_Prefix *pfx) |
| Frees the prefix object and all its contents. More... | |
| EINA_API const char * | eina_prefix_get (Eina_Prefix *pfx) |
| Gets the prefix base directory. More... | |
| EINA_API const char * | eina_prefix_bin_get (Eina_Prefix *pfx) |
| Gets the binary installation directory. More... | |
| EINA_API const char * | eina_prefix_lib_get (Eina_Prefix *pfx) |
| Gets the library installation directory. More... | |
| EINA_API const char * | eina_prefix_data_get (Eina_Prefix *pfx) |
| Gets the data installation directory. More... | |
| EINA_API const char * | eina_prefix_locale_get (Eina_Prefix *pfx) |
| Gets the locale installation directory. More... | |
This group discusses the functions that provide the ability to determine the runtime location of a software package.
An opaque type for prefix handle.
This is a prefix object that is returned by eina_prefix_new() when trying to determine the runtime location of the software in question so that other data files such as images, sound files, other executable utilities, libraries, modules, and locale files can be found.
| EINA_API Eina_Prefix * eina_prefix_new | ( | const char * | argv0, |
| void * | symbol, | ||
| const char * | envprefix, | ||
| const char * | sharedir, | ||
| const char * | magicsharefile, | ||
| const char * | pkg_bin, | ||
| const char * | pkg_lib, | ||
| const char * | pkg_data, | ||
| const char * | pkg_locale | ||
| ) |
Creates a new prefix handle given that some input information is provided.
| [in] | argv0 | If this is an executable this is argv[0] of the binary, otherwise NULL if it is used from a shared library |
| [in] | symbol | A symbol (function for example) inside the binary or library to find the source location of, provide NULL if not used |
| [in] | envprefix | The prefix to any environment variable that may override prefix detection and give the exact location of the software |
| [in] | sharedir | The directory inside the standard share or data dir where the software stores data files |
| [in] | magicsharefile | A magic file to check existence of and determine whether the prefix found is correct, and it must be located in the data dir under the share dir provided above, or NULL if the check is not to be done |
| [in] | pkg_bin | The compile-time binary install dir |
| [in] | pkg_lib | The compile-time library install dir |
| [in] | pkg_data | The compile-time share/data install dir |
| [in] | pkg_locale | The compile-time locale install dir |
NULL on failureApplications and libraries are most often not just single executables nor single shared library binaries, but also come with extra modules that they have to load, extra binary utilities they need to run, or have data files that they need to load. A very primitive application ASSUMES a fixed install location at compile-time, but this disallows the ability to relocate the application (or library) somewhere else after compilation (if you run out of space on a given disk, partition, etc. for example), or necessitate the need for having to maintain environment variables for every piece of software to let it know its location, or have to use large sets of symlinks pointing from the compiled location to the new one.
Being relocatable at runtime allows much easier distribution and installation into places like the users own home directory, instead of on a system partition, if the developer wishes for easier distribution of pre-compiled binaries.
The prefix system is designed to locate where the given software is installed (under a common prefix) at runtime and then report specific locations of this prefix and common directories inside this prefix like the binary, library, data, and locale directories.
To do this some information needs to be provided to eina_prefix_new(). If you have developed a binary executable, then provide argv[0] as the argv0 argument. This plus the PATH environment variable helps the prefix system to determine its location. Call eina_prefix_new() early on before you change the working directory or anything about argv[0], so it gets accurate information. It uses the first argument, being the executable itself, to look in absolute directories, relative paths, and PATH to see if it finds the right executable to determine just where the actual binary is installed and being run from. If you develop a shared library, just pass NULL as argv0.
Compile the following defining at compile time your prefixes like (example):
gcc appname.c -o appname -DPACKAGE_BIN_DIR=\"/usr/local/bin\"
-DPACKAGE_LIB_DIR=\\"/usr/local/lib\"
-DPACKAGE_DATA_DIR=\\"/usr/local/share/appname\"
-DLOCALE_DIR=\\"/usr/local/share/locale\"
<tt>pkg-config --cflags --libs eina</tt>
(of course add appropriate compile flags to linking and note that
locale dir is optional. If you don't need it, provide data dir as the
locale dir. Also note that the magicsharefile is optional for testing and
ensuring that the prefix check is correct. This file must be installed
in the application data dir (e.g. /usr/local/share/appname) and be referred
to using a unix-style relative path from that dir, e.g. directory/filename.png)
@code
#include <Eina.h>
static Eina_Prefix *pfx = NULL;
int main(int argc, char **argv)
{
eina_init();
pfx = eina_prefix_new(argv[0], main, "APPNAME", "appname", NULL,
PACKAGE_BIN_DIR, PACKAGE_LIB_DIR,
PACKAGE_DATA_DIR, LOCALE_DIR);
if (!pfx) printf("ERROR: Critical error in finding prefix
");
printf("install prefix is: s
", eina_prefix_get(pfx));
printf("binaries are in: s
", eina_prefix_bin_get(pfx));
printf("libraries are in: s
", eina_prefix_lib_get(pfx));
printf("data files are in: s
", eina_prefix_data_get(pfx)); eina_prefix_free(pfx);
References alloca(), DBG, EINA_FALSE, eina_file_path_join(), EINA_PATH_SEP_C, EINA_PATH_SEP_S, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, INF, realpath(), and WRN.
Referenced by ecore_init(), elm_quicklaunch_init(), and elua_init().
| EINA_API void eina_prefix_free | ( | Eina_Prefix * | pfx | ) |
Frees the prefix object and all its contents.
| [in] | pfx | The prefix object |
This function frees the prefix object and all its allocated content. It is invalid to access the object after it is freed.
References EINA_SAFETY_ON_NULL_RETURN.
Referenced by elm_quicklaunch_shutdown(), elua_shutdown(), and emotion_shutdown().
| EINA_API const char * eina_prefix_get | ( | Eina_Prefix * | pfx | ) |
Gets the prefix base directory.
| [in] | pfx | The prefix object |
References EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by elm_app_prefix_dir_get().
| EINA_API const char * eina_prefix_bin_get | ( | Eina_Prefix * | pfx | ) |
Gets the binary installation directory.
| [in] | pfx | The prefix object |
References EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by elm_app_bin_dir_get().
| EINA_API const char * eina_prefix_lib_get | ( | Eina_Prefix * | pfx | ) |
Gets the library installation directory.
| [in] | pfx | The prefix object |
References EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by elm_app_lib_dir_get(), and elm_quicklaunch_init().
| EINA_API const char * eina_prefix_data_get | ( | Eina_Prefix * | pfx | ) |
Gets the data installation directory.
| [in] | pfx | The prefix object |
References EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by elm_app_data_dir_get(), and elm_quicklaunch_init().
| EINA_API const char * eina_prefix_locale_get | ( | Eina_Prefix * | pfx | ) |
Gets the locale installation directory.
| [in] | pfx | The prefix object |
References EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by elm_app_locale_dir_get().