src/lib/elm_app.h

   1 /**
   2  * Provide information in order to make Elementary determine the @b
   3  * run time location of the software in question, so other data files
   4  * such as images, sound files, executable utilities, libraries,
   5  * modules and locale files can be found.
   6  *
   7  * @param mainfunc This is your application's main function name,
   8  *        whose binary's location is to be found. Providing @c NULL
   9  *        will make Elementary not to use it
  10  * @param dom This will be used as the application's "domain", in the
  11  *        form of a prefix to any environment variables that may
  12  *        override prefix detection and the directory name, inside the
  13  *        standard share or data directories, where the software's
  14  *        data files will be looked for.
  15  * @param checkfile This is an (optional) magic file's path to check
  16  *        for existence (and it must be located in the data directory,
  17  *        under the share directory provided above). Its presence will
  18  *        help determine the prefix found was correct. Pass @c NULL if
  19  *        the check is not to be done.
  20  *
  21  * This function allows one to re-locate the application somewhere
  22  * else after compilation, if the developer wishes for easier
  23  * distribution of pre-compiled binaries.
  24  *
  25  * The prefix system is designed to locate where the given software is
  26  * installed (under a common path prefix) at run time and then report
  27  * specific locations of this prefix and common directories inside
  28  * this prefix like the binary, library, data and locale directories,
  29  * through the @c elm_app_*_get() family of functions.
  30  *
  31  * Call elm_app_info_set() early on before you change working
  32  * directory or anything about @c argv[0], so it gets accurate
  33  * information.
  34  *
  35  * It will then try and trace back which file @p mainfunc comes from,
  36  * if provided, to determine the application's prefix directory.
  37  *
  38  * The @p dom parameter provides a string prefix to prepend before
  39  * environment variables, allowing a fallback to @b specific
  40  * environment variables to locate the software. You would most
  41  * probably provide a lowercase string there, because it will also
  42  * serve as directory domain, explained next. For environment
  43  * variables purposes, this string is made uppercase. For example if
  44  * @c "myapp" is provided as the prefix, then the program would expect
  45  * @c "MYAPP_PREFIX" as a master environment variable to specify the
  46  * exact install prefix for the software, or more specific environment
  47  * variables like @c "MYAPP_BIN_DIR", @c "MYAPP_LIB_DIR", @c
  48  * "MYAPP_DATA_DIR" and @c "MYAPP_LOCALE_DIR", which could be set by
  49  * the user or scripts before launching. If not provided (@c NULL),
  50  * environment variables will not be used to override compiled-in
  51  * defaults or auto detections.
  52  *
  53  * The @p dom string also provides a subdirectory inside the system
  54  * shared data directory for data files. For example, if the system
  55  * directory is @c /usr/local/share, then this directory name is
  56  * appended, creating @c /usr/local/share/myapp, if it @p was @c
  57  * "myapp". It is expected that the application installs data files in
  58  * this directory.
  59  *
  60  * The @p checkfile is a file name or path of something inside the
  61  * share or data directory to be used to test that the prefix
  62  * detection worked. For example, your app will install a wallpaper
  63  * image as @c /usr/local/share/myapp/images/wallpaper.jpg and so to
  64  * check that this worked, provide @c "images/wallpaper.jpg" as the @p
  65  * checkfile string.
  66  *
  67  * @see elm_app_compile_bin_dir_set()
  68  * @see elm_app_compile_lib_dir_set()
  69  * @see elm_app_compile_data_dir_set()
  70  * @see elm_app_compile_locale_set()
  71  * @see elm_app_prefix_dir_get()
  72  * @see elm_app_bin_dir_get()
  73  * @see elm_app_lib_dir_get()
  74  * @see elm_app_data_dir_get()
  75  * @see elm_app_locale_dir_get()
  76  */
  77 EAPI void        elm_app_info_set(void *mainfunc, const char *dom, const char *checkfile);
  78
  79 /**
  80  * Provide information on the @b fallback application's binaries
  81 <<<<<<< HEAD
  82  * directory, in scenarios where they get overriden by
  83 =======
  84  * directory, in scenarios where they get overridden by
  85 >>>>>>> remotes/origin/upstream
  86  * elm_app_info_set().
  87  *
  88  * @param dir The path to the default binaries directory (compile time
  89  * one)
  90  *
  91  * @note Elementary will as well use this path to determine actual
  92  * names of binaries' directory paths, maybe changing it to be @c
  93  * something/local/bin instead of @c something/bin, only, for
  94  * example.
  95  *
  96  * @warning You should call this function @b before
  97  * elm_app_info_set().
  98  */
  99 EAPI void        elm_app_compile_bin_dir_set(const char *dir);
 100
 101 /**
 102  * Provide information on the @b fallback application's libraries
 103 <<<<<<< HEAD
 104  * directory, on scenarios where they get overriden by
 105 =======
 106  * directory, on scenarios where they get overridden by
 107 >>>>>>> remotes/origin/upstream
 108  * elm_app_info_set().
 109  *
 110  * @param dir The path to the default libraries directory (compile
 111  * time one)
 112  *
 113  * @note Elementary will as well use this path to determine actual
 114  * names of libraries' directory paths, maybe changing it to be @c
 115  * something/lib32 or @c something/lib64 instead of @c something/lib,
 116  * only, for example.
 117  *
 118  * @warning You should call this function @b before
 119  * elm_app_info_set().
 120  */
 121 EAPI void        elm_app_compile_lib_dir_set(const char *dir);
 122
 123 /**
 124  * Provide information on the @b fallback application's data
 125 <<<<<<< HEAD
 126  * directory, on scenarios where they get overriden by
 127 =======
 128  * directory, on scenarios where they get overridden by
 129 >>>>>>> remotes/origin/upstream
 130  * elm_app_info_set().
 131  *
 132  * @param dir The path to the default data directory (compile time
 133  * one)
 134  *
 135  * @note Elementary will as well use this path to determine actual
 136  * names of data directory paths, maybe changing it to be @c
 137  * something/local/share instead of @c something/share, only, for
 138  * example.
 139  *
 140  * @warning You should call this function @b before
 141  * elm_app_info_set().
 142  */
 143 EAPI void        elm_app_compile_data_dir_set(const char *dir);
 144
 145 /**
 146  * Provide information on the @b fallback application's locale
 147 <<<<<<< HEAD
 148  * directory, on scenarios where they get overriden by
 149 =======
 150  * directory, on scenarios where they get overridden by
 151 >>>>>>> remotes/origin/upstream
 152  * elm_app_info_set().
 153  *
 154  * @param dir The path to the default locale directory (compile time
 155  * one)
 156  *
 157  * @warning You should call this function @b before
 158  * elm_app_info_set().
 159  */
 160 EAPI void        elm_app_compile_locale_set(const char *dir);
 161
 162 /**
 163  * Retrieve the application's run time prefix directory, as set by
 164  * elm_app_info_set() and the way (environment) the application was
 165  * run from.
 166  *
 167  * @return The directory prefix the application is actually using.
 168  */
 169 EAPI const char *elm_app_prefix_dir_get(void);
 170
 171 /**
 172  * Retrieve the application's run time binaries prefix directory, as
 173  * set by elm_app_info_set() and the way (environment) the application
 174  * was run from.
 175  *
 176  * @return The binaries directory prefix the application is actually
 177  * using.
 178  */
 179 EAPI const char *elm_app_bin_dir_get(void);
 180
 181 /**
 182  * Retrieve the application's run time libraries prefix directory, as
 183  * set by elm_app_info_set() and the way (environment) the application
 184  * was run from.
 185  *
 186  * @return The libraries directory prefix the application is actually
 187  * using.
 188  */
 189 EAPI const char *elm_app_lib_dir_get(void);
 190
 191 /**
 192  * Retrieve the application's run time data prefix directory, as
 193  * set by elm_app_info_set() and the way (environment) the application
 194  * was run from.
 195  *
 196  * @return The data directory prefix the application is actually
 197  * using.
 198  */
 199 EAPI const char *elm_app_data_dir_get(void);
 200
 201 /**
 202  * Retrieve the application's run time locale prefix directory, as
 203  * set by elm_app_info_set() and the way (environment) the application
 204  * was run from.
 205  *
 206  * @return The locale directory prefix the application is actually
 207  * using.
 208  */
 209 EAPI const char *elm_app_locale_dir_get(void);