src/include/eina_prefix.h

   1 #ifndef EINA_PREFIX_H_
   2 #define EINA_PREFIX_H_
   3
   4 /**
   5  * @addtogroup Eina_Prefix_Group Prefix Group
   6  *
   7  * @brief These functions provide the ability to determine the runtime
   8  * location of a software package
   9  *
  10  * @{
  11  *
  12  * @since 1.1.0
  13  */
  14
  15 /**
  16  * @typedef Eina_Prefix
  17  * This is a prefix object that is returned by eina_prefix_new() when trying
  18  * to determine the runtime location of the software in question so other
  19  * data files such as images, sound files, other executable utilities,
  20  * libraries, modules and locale files can be found.
  21  *
  22  * @since 1.1.0
  23  */
  24 typedef struct _Eina_Prefix Eina_Prefix;
  25
  26 /**
  27  * @brief Create a new prefix handle given some input information
  28  *
  29  * @param argv0 If this is an executable this is argv[0] of the binary, or @c NULL if it is used from a shared library
  30  * @param symbol This is a symbol (function for example) inside the binary or library to find the source location of. Provide @c NULL if not used
  31  * @param envprefix This is the prefix to any environment variables that may override prefix detection and give the exact location of the software
  32  * @param sharedir This is the directory inside the standard share or data dir where the software will store data files
  33  * @param 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
  34  * dir under the share dir provided above, or @c NULL if the check is not to be done.
  35  * @param pkg_bin This is the compile-time binary install dir
  36  * @param pkg_lib This is the compile-time library install dir
  37  * @param pkg_data This is the compile-time share/data install dir
  38  * @param pkg_locale This is the compile-time locale install dir
  39  * @return The prefix handle, or @c NULL on failure.
  40  *
  41  * Applications and libraries are most often not just single executables nor
  42  * single shared library binaries, but also come with extra modules they
  43  * have to load, extra binary utilities they need to run, or have data files
  44  * they need to load. A very primitive application ASSUMES a fixed install
  45  * location at compile-time, but this disallows the ability to re-locate
  46  * the application (or library) somewhere else after compilation (if you run
  47  * out of space on a given disk, partition etc. for example), or necessitate
  48  * the need for having to maintain environment variables for every piece of
  49  * software to let it know its location, or have to use large sets of
  50  * symlinks pointing from the compiled location to the new one.
  51  *
  52  * Being re-locatable at runtime allows much easier distribution and
  53  * installation into places like the users own home directory, instead of
  54  * on a system partition, if the developer wishes for easier distribution
  55  * of pre-compiled binaries.
  56  *
  57  * The prefix system is designed to locate where the given software is
  58  * installed (under a common prefix) at runtime and then report specific
  59  * locations of this prefix and common directories inside this prefix like
  60  * the binary, library, data and locale directories.
  61  *
  62  * To do this some information needs to be provided to eina_prefix_new(). If
  63  * you have developed a binary executable, then provide argv[0] as the @p argv0
  64  * argument. This plus the PATH environment variable help the prefix system
  65  * to determine its location. Call eina_prefix_new() early on before you
  66  * change working directory or anything about argv[0] so it gets accurate
  67  * information. It will use the first argument, being the executable itself,
  68  * to look in absolute directories, relative paths and PATH to see if it
  69  * finds the right executable to determine just where the actual binary is
  70  * installed and being run from. If you develop a share library, just pass
  71  * @c NULL as argv0
  72  *
  73  * It would prefer to use the @p symbol function to determine location as
  74  * that function will be unique inside the application and try and trace
  75  * back which file this function comes from (be it a binary or shared library)
  76  * as this avoids more expensive searches via @p argv0. It will use this
  77  * symbol if given in preference to argv0.
  78  *
  79  * The @p envprefix parameter, provides a string prefix to prepend before
  80  * environment variables to allow a fallback to specific environment variables
  81  * to locate the software. For example if "MYAPP" is provided a the prefix,
  82  * then it uses "MYAPP_PREFIX" as a master environment variable to specify
  83  * the exact install prefix for the software, or more specific environment
  84  * variables like "MYAPP_BIN_DIR", "MYAPP_LIB_DIR", "MYAPP_DATA_DIR" and
  85  * "MYAPP_LOCALE_DIR" which can be set by the user or scripts before
  86  * launching. If not provided (NULL) environment variables will not be
  87  * used to override compiled-in defaults or auto detections.
  88  *
  89  * The @p sharedir string provides a subdirectory inside the system shared
  90  * data dir for data files. For example, if the system dir is
  91  * /usr/local/share then this dir name is appended, creating
  92  * /usr/local/share/appname if this dir was the "appname" string. It is
  93  * expected the application or library installs data files in this directory.
  94  *
  95  * The @p magicsharefile is a filename or path of something inside the share
  96  * or data dir to be used to test that the prefix detection worked. For
  97  * example, your app will install a wallpaper image as
  98  * /usr/local/share/appname/images/wallpaper.jpg and so to check that this
  99  * worked, provide "images/wallpaper.jpg" as the @p magicsharefile string
 100  * so detection can know if it worked or not.
 101  *
 102  * The @p pkg_bin, @p pkg_lib, @p pkg_data and @p pkg_locale are compile-time
 103  * strings (the kind standard autoconf/automake define) to be passed in
 104  * so there can be a fallback to compiled-in defaults as well as use them
 105  * to determine actual names of directories like libdirs maybe changing to
 106  * be lib32 or lib64 instead of lib etc.
 107  *
 108  * Compile the following defining at compile time your prefixes like (example):
 109  *
 110  * gcc appname.c -o appname
 111  * -DPACKAGE_BIN_DIR=\\"/usr/local/bin\"
 112  * -DPACKAGE_LIB_DIR=\\"/usr/local/lib\"
 113  * -DPACKAGE_DATA_DIR=\\"/usr/local/share/appname\"
 114  * -DLOCALE_DIR=\\"/usr/local/share/locale\"
 115  * `pkg-config --cflags --libs eina`
 116  *
 117  * (of course add appropriate compile flags to linking etc. etc. and note that
 118  * locale dir is optional. if you don't need it provide data dir as the
 119  * locale dir. also note that the magicsharefile is optional for testing and
 120  * ensuring that the prefix check is correct. this file must be installed
 121  * in the application data dir (eg /usr/local/share/appname) and be referred
 122  * to using a unix-style relative path from that dir, eg directory/filename.png)
 123  *
 124  * @code
 125  * #include <Eina.h>
 126  *
 127  * static Eina_Prefix *pfx = NULL;
 128  *
 129  * int main(int argc, char **argv)
 130  * {
 131  *   eina_init();
 132  *
 133  *   pfx = eina_prefix_new(argv[0], main, "APPNAME", "appname", NULL,
 134  *                         PACKAGE_BIN_DIR, PACKAGE_LIB_DIR,
 135  *                         PACKAGE_DATA_DIR, LOCALE_DIR);
 136  *   if (!pfx) printf("ERROR: Critical error in finding prefix\n");
 137  *   printf("install prefix is: %s\n", eina_prefix_get(pfx));
 138  *   printf("binaries are in: %s\n", eina_prefix_bin_get(pfx));
 139  *   printf("libraries are in: %s\n", eina_prefix_lib_get(pfx));
 140  *   printf("data files are in: %s\n", eina_prefix_data_get(pfx));
 141  *   eina_prefix_free(pfx);
 142  *
 143  *   eina_shutdown();
 144  * }
 145  * @endcode
 146  *
 147  * @since 1.1.0
 148  */
 149 EAPI Eina_Prefix *
 150 eina_prefix_new(const char *argv0, void *symbol, const char *envprefix,
 151                 const char *sharedir, const char *magicsharefile,
 152                 const char *pkg_bin, const char *pkg_lib,
 153                 const char *pkg_data, const char *pkg_locale);
 154
 155 /**
 156  * @brief Free the prefix object and all its contents
 157  *
 158  * @param pfx The prefix object
 159  *
 160  * Free the prefix object and all its allocated content. It will be invalid
 161  * to access the object after being freed.
 162  *
 163  * @since 1.1.0
 164  */
 165 EAPI void
 166 eina_prefix_free(Eina_Prefix *pfx);
 167
 168 /**
 169  * @brief Get the prefix base directory
 170  *
 171  * @param pfx The prefix object
 172  * @return The base prefix (eg "/usr/local", "/usr", "/opt/appname" or
 173  * "/home/user/myapps/appname" etc.) that the software resides in at runtime.
 174  *
 175  * @since 1.1.0
 176  */
 177 EAPI const char *
 178 eina_prefix_get(Eina_Prefix *pfx);
 179
 180 /**
 181  * @brief Get the binary installation directory
 182  *
 183  * @param pfx The prefix object
 184  * @return The location of installed binaries (eg "/usr/local/bin",
 185  * "/usr/bin", "/opt/appname/bin", "/home/user/myapps/appname/bin" etc.).
 186  *
 187  * @since 1.1.0
 188  */
 189 EAPI const char *
 190 eina_prefix_bin_get(Eina_Prefix *pfx);
 191
 192 /**
 193  * @brief Get the library installation directory
 194  *
 195  * @param pfx The prefix object
 196  * @return The location of installed binaries (eg "/usr/local/lib",
 197  * "/usr/lib32", "/opt/appname/lib64", "/home/user/myapps/appname/lib" etc.).
 198  *
 199  * @since 1.1.0
 200  */
 201 EAPI const char *
 202 eina_prefix_lib_get(Eina_Prefix *pfx);
 203
 204 /**
 205  * @brief Get the data installation directory
 206  *
 207  * @param pfx The prefix object
 208  * @return The location of installed binaries (eg "/usr/local/share/appname",
 209  * "/usr/share/appname", "/opt/appname/share/appname", "/home/user/myapps/appname/share/appname" etc.).
 210  *
 211  * @since 1.1.0
 212  */
 213 EAPI const char *
 214 eina_prefix_data_get(Eina_Prefix *pfx);
 215
 216 /**
 217  * @brief Get the locale installation directory
 218  *
 219  * @param pfx The prefix object
 220  * @return The location of installed binaries (eg "/usr/local/share/locale",
 221  * "/usr/share/locale", "/opt/appname/share/locale", "/home/user/myapps/appname/share/locale" etc.).
 222  *
 223  * @since 1.1.0
 224  */
 225 EAPI const char *
 226 eina_prefix_locale_get(Eina_Prefix *pfx);
 227
 228 /**
 229  * @}
 230  */
 231 #endif