Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_version.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_version.h
24  * @brief Version information.
25  */
26 
27 #ifndef SVN_VERSION_H
28 #define SVN_VERSION_H
29 
30 /* Hack to prevent the resource compiler from including
31  apr and other headers. */
32 #ifndef SVN_WIN32_RESOURCE_COMPILATION
33 #include <apr_general.h>
34 #include <apr_tables.h>
35 
36 #include "svn_types.h"
37 #endif
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif /* __cplusplus */
42 
43 
44 /* Symbols that define the version number. */
45 
46 /* Version numbers: <major>.<minor>.<micro>
47  *
48  * The version numbers in this file follow the rules established by:
49  *
50  * http://apr.apache.org/versioning.html
51  */
52 
53 /** Major version number.
54  *
55  * Modify when incompatible changes are made to published interfaces.
56  */
57 #define SVN_VER_MAJOR 1
58 
59 /** Minor version number.
60  *
61  * Modify when new functionality is added or new interfaces are
62  * defined, but all changes are backward compatible.
63  */
64 #define SVN_VER_MINOR 10
65 
66 /**
67  * Patch number.
68  *
69  * Modify for every released patch.
70  *
71  * @since New in 1.1.
72  */
73 #define SVN_VER_PATCH 0
74 
75 
76 /** @deprecated Provided for backward compatibility with the 1.0 API. */
77 #define SVN_VER_MICRO SVN_VER_PATCH
78 
79 /** @deprecated Provided for backward compatibility with the 1.0 API. */
80 #define SVN_VER_LIBRARY SVN_VER_MAJOR
81 
82 
83 /** Version tag: a string describing the version.
84  *
85  * This tag remains " (under development)" in the repository so that we can
86  * always see from "svn --version" that the software has been built
87  * from the repository rather than a "blessed" distribution.
88  *
89  * When rolling a tarball, we automatically replace this text with " (r1234)"
90  * (where 1234 is the last revision on the branch prior to the release)
91  * for final releases; in prereleases, it becomes " (Alpha 1)",
92  * " (Beta 1)", etc., as appropriate.
93  *
94  * Always change this at the same time as SVN_VER_NUMTAG.
95  */
96 #define SVN_VER_TAG " (under development)"
97 
98 
99 /** Number tag: a string describing the version.
100  *
101  * This tag is used to generate a version number string to identify
102  * the client and server in HTTP requests, for example. It must not
103  * contain any spaces. This value remains "-dev" in the repository.
104  *
105  * When rolling a tarball, we automatically replace this text with ""
106  * for final releases; in prereleases, it becomes "-alpha1, "-beta1",
107  * etc., as appropriate.
108  *
109  * Always change this at the same time as SVN_VER_TAG.
110  */
111 #define SVN_VER_NUMTAG "-dev"
112 
113 
114 /** Revision number: The repository revision number of this release.
115  *
116  * This constant is used to generate the build number part of the Windows
117  * file version. Its value remains 0 in the repository except in release
118  * tags where it is the revision from which the tag was created.
119  */
120 #define SVN_VER_REVISION 0
121 
122 
123 /* Version strings composed from the above definitions. */
124 
125 /** Version number */
126 #define SVN_VER_NUM APR_STRINGIFY(SVN_VER_MAJOR) \
127  "." APR_STRINGIFY(SVN_VER_MINOR) \
128  "." APR_STRINGIFY(SVN_VER_PATCH)
129 
130 /** Version number with tag (contains no whitespace) */
131 #define SVN_VER_NUMBER SVN_VER_NUM SVN_VER_NUMTAG
132 
133 /** Complete version string */
134 #define SVN_VERSION SVN_VER_NUMBER SVN_VER_TAG
135 
136 
137 
138 /* Version queries and compatibility checks */
139 
140 /**
141  * Version information. Each library contains a function called
142  * svn_<i>libname</i>_version() that returns a pointer to a statically
143  * allocated object of this type.
144  *
145  * @since New in 1.1.
146  */
148 {
149  int major; /**< Major version number */
150  int minor; /**< Minor version number */
151  int patch; /**< Patch number */
152 
153  /**
154  * The version tag (#SVN_VER_NUMTAG). Must always point to a
155  * statically allocated string.
156  */
157  const char *tag;
158 };
159 
160 /**
161  * Define a static svn_version_t object.
162  *
163  * @since New in 1.1.
164  */
165 #define SVN_VERSION_DEFINE(name) \
166  static const svn_version_t name = \
167  { \
168  SVN_VER_MAJOR, \
169  SVN_VER_MINOR, \
170  SVN_VER_PATCH, \
171  SVN_VER_NUMTAG \
172  } \
173 
174 /**
175  * Generate the implementation of a version query function.
176  *
177  * @since New in 1.1.
178  * @since Since 1.9, embeds a string into the compiled object
179  * file that can be queried with the 'what' utility.
180  */
181 #define SVN_VERSION_BODY \
182  static struct versioninfo_t \
183  { \
184  const char *const str; \
185  const svn_version_t num; \
186  } const versioninfo = \
187  { \
188  "@(#)" SVN_VERSION, \
189  { \
190  SVN_VER_MAJOR, \
191  SVN_VER_MINOR, \
192  SVN_VER_PATCH, \
193  SVN_VER_NUMTAG \
194  } \
195  }; \
196  return &versioninfo.num
197 
198 /**
199  * Check library version compatibility. Return #TRUE if the client's
200  * version, given in @a my_version, is compatible with the library
201  * version, provided in @a lib_version.
202  *
203  * This function checks for version compatibility as per our
204  * guarantees, but requires an exact match when linking to an
205  * unreleased library. A development client is always compatible with
206  * a previous released library.
207  *
208  * @note Implements the #svn_ver_check_list2.@a comparator interface.
209  *
210  * @since New in 1.1.
211  */
213 svn_ver_compatible(const svn_version_t *my_version,
214  const svn_version_t *lib_version);
215 
216 /**
217  * Check if @a my_version and @a lib_version encode the same version number.
218  *
219  * @note Implements the #svn_ver_check_list2.@a comparator interface.
220  *
221  * @since New in 1.2.
222  */
224 svn_ver_equal(const svn_version_t *my_version,
225  const svn_version_t *lib_version);
226 
227 
228 /**
229  * An entry in the compatibility checklist.
230  * @see svn_ver_check_list()
231  *
232  * @since New in 1.1.
233  */
235 {
236  const char *label; /**< Entry label */
237 
238  /** Version query function for this entry */
239  const svn_version_t *(*version_query)(void);
241 
242 
243 /**
244  * Perform a series of version compatibility checks. Checks if @a
245  * my_version is compatible with each entry in @a checklist. @a
246  * checklist must end with an entry whose label is @c NULL.
247  *
248  * @a my_version is considered to be compatible with a version in @a checklist
249  * if @a comparator returns #TRUE when called with @a my_version as the first
250  * parammeter and the @a checklist version as the second parameter.
251  *
252  * @see svn_ver_compatible(), svn_ver_equal()
253  *
254  * @note Subversion's own code invariably uses svn_ver_equal() as @a comparator,
255  * since the cmdline tools sometimes use non-public APIs (such as utility
256  * functions that haven't been promoted to svn_cmdline.h). Third-party code
257  * SHOULD use svn_ver_compatible() as @a comparator.
258  *
259  * @since New in 1.9.
260  */
261 svn_error_t *
262 svn_ver_check_list2(const svn_version_t *my_version,
263  const svn_version_checklist_t *checklist,
264  svn_boolean_t (*comparator)(const svn_version_t *,
265  const svn_version_t *));
266 
267 /** Similar to svn_ver_check_list2(), with @a comparator set to
268  * #svn_ver_compatible.
269  *
270  * @deprecated Provided for backward compatibility with 1.8 API.
271  */
273 svn_error_t *
274 svn_ver_check_list(const svn_version_t *my_version,
275  const svn_version_checklist_t *checklist);
276 
277 
278 /**
279  * Type of function returning library version.
280  *
281  * @since New in 1.6.
282  */
283 typedef const svn_version_t *(*svn_version_func_t)(void);
284 
285 
286 /* libsvn_subr doesn't have an svn_subr header, so put the prototype here. */
287 /**
288  * Get libsvn_subr version information.
289  *
290  * @since New in 1.1.
291  */
292 const svn_version_t *
293 svn_subr_version(void);
294 
295 
296 /**
297  * Extended version information, including info about the running system.
298  *
299  * @since New in 1.8.
300  */
302 
303 /**
304  * Return version information for the running program. If @a verbose
305  * is #TRUE, collect extra information that may be expensive to
306  * retrieve (for example, the OS release name, list of shared
307  * libraries, etc.). Use @a pool for all allocations.
308  *
309  * @note This function may allocate significant auxiliary resources
310  * (memory and file descriptors) in @a pool. It is recommended to
311  * copy the returned data to suitable longer-lived memory and clear
312  * @a pool after calling this function.
313  *
314  * @since New in 1.8.
315  */
318  apr_pool_t *pool);
319 
320 
321 /**
322  * Accessor for svn_version_extended_t.
323  *
324  * @return The date when the libsvn_subr library was compiled, in the
325  * format defined by the C standard macro @c __DATE__.
326  *
327  * @since New in 1.8.
328  */
329 const char *
331 
332 /**
333  * Accessor for svn_version_extended_t.
334  *
335  * @return The time when the libsvn_subr library was compiled, in the
336  * format defined by the C standard macro @c __TIME__.
337  *
338  * @since New in 1.8.
339  */
340 const char *
342 
343 /**
344  * Accessor for svn_version_extended_t.
345  *
346  * @return The canonical host triplet (arch-vendor-osname) of the
347  * system where libsvn_subr was compiled.
348  *
349  * @note On Unix-like systems (includng Mac OS X), this string is the
350  * same as the output of the config.guess script.
351  *
352  * @since New in 1.8.
353  */
354 const char *
356 
357 /**
358  * Accessor for svn_version_extended_t.
359  *
360  * @return The localized copyright notice.
361  *
362  * @since New in 1.8.
363  */
364 const char *
366 
367 /**
368  * Accessor for svn_version_extended_t.
369  *
370  * @return The canonical host triplet (arch-vendor-osname) of the
371  * system where the current process is running.
372  *
373  * @note This string may not be the same as the output of config.guess
374  * on the same system.
375  *
376  * @since New in 1.8.
377  */
378 const char *
380 
381 /**
382  * Accessor for svn_version_extended_t.
383  *
384  * @return The "commercial" release name of the running operating
385  * system, if available. Not to be confused with, e.g., the output of
386  * "uname -v" or "uname -r". The returned value may be @c NULL.
387  *
388  * @since New in 1.8.
389  */
390 const char *
392 
393 /**
394  * Dependent library information.
395  * Describes the name and versions of known dependencies
396  * used by libsvn_subr.
397  *
398  * @since New in 1.8.
399  */
401 {
402  const char *name; /**< Library name */
403  const char *compiled_version; /**< Compile-time version string */
404  const char *runtime_version; /**< Run-time version string (optional) */
406 
407 /**
408  * Accessor for svn_version_extended_t.
409  *
410  * @return Array of svn_version_ext_linked_lib_t describing dependent
411  * libraries. The returned value may be @c NULL.
412  *
413  * @since New in 1.8.
414  */
415 const apr_array_header_t *
417 
418 
419 /**
420  * Loaded shared library information.
421  * Describes the name and, where available, version of the shared libraries
422  * loaded by the running program.
423  *
424  * @since New in 1.8.
425  */
427 {
428  const char *name; /**< Library name */
429  const char *version; /**< Library version (optional) */
431 
432 
433 /**
434  * Accessor for svn_version_extended_t.
435  *
436  * @return Array of svn_version_ext_loaded_lib_t describing loaded
437  * shared libraries. The returned value may be @c NULL.
438  *
439  * @note On Mac OS X, the loaded frameworks, private frameworks and
440  * system libraries will not be listed.
441  *
442  * @since New in 1.8.
443  */
444 const apr_array_header_t *
446 
447 
448 #ifdef __cplusplus
449 }
450 #endif /* __cplusplus */
451 
452 #endif /* SVN_VERSION_H */