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     * directory, in scenarios where they get overriden by
  82     * elm_app_info_set().
  83     *
  84     * @param dir The path to the default binaries directory (compile time
  85     * one)
  86     *
  87     * @note Elementary will as well use this path to determine actual
  88     * names of binaries' directory paths, maybe changing it to be @c
  89     * something/local/bin instead of @c something/bin, only, for
  90     * example.
  91     *
  92     * @warning You should call this function @b before
  93     * elm_app_info_set().
  94     */
  95    EAPI void         elm_app_compile_bin_dir_set(const char *dir);
  96
  97    /**
  98     * Provide information on the @b fallback application's libraries
  99     * directory, on scenarios where they get overriden by
 100     * elm_app_info_set().
 101     *
 102     * @param dir The path to the default libraries directory (compile
 103     * time one)
 104     *
 105     * @note Elementary will as well use this path to determine actual
 106     * names of libraries' directory paths, maybe changing it to be @c
 107     * something/lib32 or @c something/lib64 instead of @c something/lib,
 108     * only, for example.
 109     *
 110     * @warning You should call this function @b before
 111     * elm_app_info_set().
 112     */
 113    EAPI void         elm_app_compile_lib_dir_set(const char *dir);
 114
 115    /**
 116     * Provide information on the @b fallback application's data
 117     * directory, on scenarios where they get overriden by
 118     * elm_app_info_set().
 119     *
 120     * @param dir The path to the default data directory (compile time
 121     * one)
 122     *
 123     * @note Elementary will as well use this path to determine actual
 124     * names of data directory paths, maybe changing it to be @c
 125     * something/local/share instead of @c something/share, only, for
 126     * example.
 127     *
 128     * @warning You should call this function @b before
 129     * elm_app_info_set().
 130     */
 131    EAPI void         elm_app_compile_data_dir_set(const char *dir);
 132
 133    /**
 134     * Provide information on the @b fallback application's locale
 135     * directory, on scenarios where they get overriden by
 136     * elm_app_info_set().
 137     *
 138     * @param dir The path to the default locale directory (compile time
 139     * one)
 140     *
 141     * @warning You should call this function @b before
 142     * elm_app_info_set().
 143     */
 144    EAPI void         elm_app_compile_locale_set(const char *dir);
 145
 146    /**
 147     * Retrieve the application's run time prefix directory, as set by
 148     * elm_app_info_set() and the way (environment) the application was
 149     * run from.
 150     *
 151     * @return The directory prefix the application is actually using.
 152     */
 153    EAPI const char  *elm_app_prefix_dir_get(void);
 154
 155    /**
 156     * Retrieve the application's run time binaries prefix directory, as
 157     * set by elm_app_info_set() and the way (environment) the application
 158     * was run from.
 159     *
 160     * @return The binaries directory prefix the application is actually
 161     * using.
 162     */
 163    EAPI const char  *elm_app_bin_dir_get(void);
 164
 165    /**
 166     * Retrieve the application's run time libraries prefix directory, as
 167     * set by elm_app_info_set() and the way (environment) the application
 168     * was run from.
 169     *
 170     * @return The libraries directory prefix the application is actually
 171     * using.
 172     */
 173    EAPI const char  *elm_app_lib_dir_get(void);
 174
 175    /**
 176     * Retrieve the application's run time data prefix directory, as
 177     * set by elm_app_info_set() and the way (environment) the application
 178     * was run from.
 179     *
 180     * @return The data directory prefix the application is actually
 181     * using.
 182     */
 183    EAPI const char  *elm_app_data_dir_get(void);
 184
 185    /**
 186     * Retrieve the application's run time locale prefix directory, as
 187     * set by elm_app_info_set() and the way (environment) the application
 188     * was run from.
 189     *
 190     * @return The locale directory prefix the application is actually
 191     * using.
 192     */
 193    EAPI const char  *elm_app_locale_dir_get(void);
 194