Prefix Group
These functions provide the ability to determine the runtime location of a software package. More...Typedefs | |
typedef struct _Eina_Prefix | Eina_Prefix |
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 other data files such as images, sound files, other executable utilities, libraries, modules and locale files can be found. | |
Functions | |
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) |
Create a new prefix handle given some input information. | |
void | eina_prefix_free (Eina_Prefix *pfx) |
Free the prefix object and all its contents. | |
const char * | eina_prefix_get (Eina_Prefix *pfx) |
Get the prefix base directory. | |
const char * | eina_prefix_bin_get (Eina_Prefix *pfx) |
Get the binary installation directory. | |
const char * | eina_prefix_lib_get (Eina_Prefix *pfx) |
Get the library installation directory. | |
const char * | eina_prefix_data_get (Eina_Prefix *pfx) |
Get the data installation directory. | |
const char * | eina_prefix_locale_get (Eina_Prefix *pfx) |
Get the locale installation directory. |
Detailed Description
These functions provide the ability to determine the runtime location of a software package.
- Since:
- 1.1.0
Typedef Documentation
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 other data files such as images, sound files, other executable utilities, libraries, modules and locale files can be found.
- Since:
- 1.1.0
Function Documentation
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 | |||
) |
Create a new prefix handle given some input information.
- Parameters:
-
argv0 If this is an executable this is argv[0] of the binary, or NULL if it is used from a shared library symbol This is a symbol (function for example) inside the binary or library to find the source location of. Provide NULL if not used envprefix This is the prefix to any environment variables that may override prefix detection and give the exact location of the software sharedir This is the directory inside the standard share or data dir where the software will store data files magicsharefile This is a magic file to check existence of to determine the prefix find was 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 pkg_bin This is the compile-time binary install dir pkg_lib This is the compile-time library install dir pkg_data This is the compile-time share/data install dir pkg_locale This is the compile-time locale install dir
- Returns:
- The prefix handle, or NULL on failure
Being re-locatable 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 help the prefix system to determine its location. Call eina_prefix_new() early on before you change working directory or anything about argv[0] so it gets accurate information. It will use 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 share library, just pass NULL as argv0
It would prefer to use the symbol
function to determine location as that function will be unique inside the application and try and trace back which file this function comes from (be it a binary or shared library) as this avoids more expensive searches via argv0
. It will use this symbol if given in preference to argv0.
The envprefix
parameter, provides a string prefix to prepend before environment variables to allow a fallback to specific environment variables to locate the software. For example if "MYAPP" is provided a the prefix, then it uses "MYAPP_PREFIX" as a master environment variable to specify the exact install prefix for the software, or more specific environment variables like "MYAPP_BIN_DIR", "MYAPP_LIB_DIR", "MYAPP_DATA_DIR" and "MYAPP_LOCALE_DIR" which can be set by the user or scripts before launching. If not provided (NULL) environment variables will not be used to override compiled-in defaults or auto detections.
The sharedir
string provides a subdirectory inside the system shared data dir for data files. For example, if the system dir is /usr/local/share then this dir name is appended, creating /usr/local/share/appname if this dir was the "appname" string. It is expected the application or library installs data files in this directory.
The magicsharefile
is a filename or path of something inside the share or data dir to be used to test that the prefix detection worked. For example, your app will install a wallpaper image as /usr/local/share/appname/images/wallpaper.jpg and so to check that this worked, provide "images/wallpaper.jpg" as the magicsharefile
string so detection can know if it worked or not.
The pkg_bin
, pkg_lib
, pkg_data
and pkg_locale
are compile-time strings (the kind standard autoconf/automake define) to be passed in so there can be a fallback to compiled-in defaults as well as use them to determine actual names of directories like libdirs maybe changing to be lib32 or lib64 instead of lib etc.
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
(of course add appropriate compile flags to linking etc. etc. 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 (eg /usr/local/share/appname) and be referred to using a unix-style relative path from that dir, eg directory/filename.png)
static Eina_Prefix *pfx = NULL; int main(argc, char **argv) { 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\n"); printf("install prefix is: %s\n", eina_prefix_get(pfx)); printf("binaries are in: %s\n", eina_prefix_bin_get(pfx)); printf("libraries are in: %s\n", eina_prefix_lib_get(pfx)); printf("data files are in: %s\n", eina_prefix_data_get(pfx)); eina_prefix_free(pfx); }
- Since:
- 1.1.0
void eina_prefix_free | ( | Eina_Prefix * | pfx | ) |
Free the prefix object and all its contents.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0
const char* eina_prefix_get | ( | Eina_Prefix * | pfx | ) |
Get the prefix base directory.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0
const char* eina_prefix_bin_get | ( | Eina_Prefix * | pfx | ) |
Get the binary installation directory.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0
const char* eina_prefix_lib_get | ( | Eina_Prefix * | pfx | ) |
Get the library installation directory.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0
const char* eina_prefix_data_get | ( | Eina_Prefix * | pfx | ) |
Get the data installation directory.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0
const char* eina_prefix_locale_get | ( | Eina_Prefix * | pfx | ) |
Get the locale installation directory.
- Parameters:
-
pfx The prefix object
- Since:
- 1.1.0