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