Rework the versioning information, hopefully for the last time.

 * There are now only two public version identifiers:  "number" is
   a single integer that combines Major/minor/release in a single
   value of the form Mmmmrrr.  This is easy to compare against for
   checking feature support.  "string" is a displayable text string
   of the form "libarchive M.mm.rr".
 * The number is present both as a macro (version of the installed header)
   and a function (version of the shared library).  The string form
   is available only as a function.
 * Retain the older version definitions for now, but mark them all
   as deprecated, to disappear in libarchive 3.0 (whenever that happens).
 * Rework the various deprecation conditionals to use ARCHIVE_VERSION_NUMBER.

An ancillary goal is to reduce the number of @...@ substitutions that
are required.  Someday, I might even be able to avoid build-time
processing of archive.h entirely.

1 files changed, 37 insertions, 41 deletions

diff --git a/lib/libarchive/archive.h.in b/lib/libarchive/archive.h.in
index f29a72f..842b432 100644
--- a/lib/libarchive/archive.h.in
+++ b/lib/libarchive/archive.h.in
@@ -28,12 +28,6 @@
 #ifndef ARCHIVE_H_INCLUDED
 #define	ARCHIVE_H_INCLUDED
 
-/*
- * This header file corresponds to:
- *   Library version @ARCHIVE_VERSION@
- *   Shared library version @SHLIB_MAJOR@
- */
-
 #include <sys/types.h>  /* Linux requires this for off_t */
 @ARCHIVE_H_INCLUDE_INTTYPES_H@
 #include <stdio.h> /* For FILE * */
@@ -51,58 +45,59 @@ extern "C" {
 #endif
 
 /*
- * Each of the version identifiers comes as a macro and a function.
+ * The version number is provided as both a macro and a function.
  * The macro identifies the installed header; the function identifies
  * the library version (which may not be the same if you're using a
  * dynamically-linked version of the library).
  */
 
 /*
- * Textual name/version of the library, useful for version displays.
- */
-#define	ARCHIVE_LIBRARY_VERSION	"libarchive @LIBARCHIVE_VERSION_STRING@"
-const char *	archive_version(void);
-
-/*
- * The "version stamp" is a single integer that makes it easy to check
- * the exact version: for version a.b.c, the version stamp is
- * printf("%d%03d%03d",a,b,c).  For example, version 2.12.108 has
- * version stamp 2012108.
+ * The version number is expressed as a single integer that makes it
+ * easy to compare versions at build time: for version a.b.c, the
+ * version number is printf("%d%03d%03d",a,b,c).  For example, if you
+ * know your application requires version 2.12.108 or later, you can
+ * assert that ARCHIVE_VERSION >= 2012108.
  *
- * This was introduced with libarchive 1.9.0 in the libarchive 1.x family
- * and libarchive 2.2.4 in the libarchive 2.x family.  The following
- * may be useful if you really want to do feature detection for earlier
- * libarchive versions (which defined API_VERSION and API_FEATURE):
+ * This single-number format was introduced with libarchive 1.9.0 in
+ * the libarchive 1.x family and libarchive 2.2.4 in the libarchive
+ * 2.x family.  The following may be useful if you really want to do
+ * feature detection for earlier libarchive versions (which defined
+ * ARCHIVE_API_VERSION and ARCHIVE_API_FEATURE instead):
  *
- * #ifndef ARCHIVE_VERSION_STAMP
- * #define ARCHIVE_VERSION_STAMP 	\
+ * #ifndef ARCHIVE_VERSION_NUMBER
+ * #define ARCHIVE_VERSION_NUMBER	\
  *             (ARCHIVE_API_VERSION * 1000000 + ARCHIVE_API_FEATURE * 1000)
  * #endif
  */
-#define ARCHIVE_VERSION_STAMP	@LIBARCHIVE_VERSION@
-int		archive_version_stamp(void);
+#define ARCHIVE_VERSION_NUMBER		@LIBARCHIVE_VERSION@
+int		archive_version_number(void);
 
 /*
- * Major version number: If ARCHIVE_API_VERSION !=
- * archive_api_version(), then the library you were linked with is
- * using an incompatible API to the one you were compiled with.  This
- * is almost certainly a fatal problem.
- * This is deprecated and will be removed; use ARCHIVE_VERSION_STAMP
- * instead.
+ * Textual name/version of the library, useful for version displays.
  */
-#define	ARCHIVE_API_VERSION	(ARCHIVE_VERSION_STAMP / 1000000)
-int		archive_api_version(void);
+const char *	archive_version_string(void);
 
+#if ARCHIVE_VERSION_NUMBER < 3000000
 /*
- * Minor version number.  This is deprecated and will be removed.
- * Use ARCHIVE_VERSION_STAMP to adapt to libarchive API variations.
+ * Deprecated; these are older names that will be removed in favor of
+ * the simpler definitions above.
  */
-#define	ARCHIVE_API_FEATURE	((ARCHIVE_VERSION_STAMP / 1000) % 1000)
+#define	ARCHIVE_VERSION_STAMP	ARCHIVE_VERSION_NUMBER
+int		archive_version_stamp(void);
+#define	ARCHIVE_LIBRARY_VERSION	"libarchive @LIBARCHIVE_VERSION_STRING@"
+const char *	archive_version(void);
+#define	ARCHIVE_API_VERSION	(ARCHIVE_VERSION_NUMBER / 1000000)
+int		archive_api_version(void);
+#define	ARCHIVE_API_FEATURE	((ARCHIVE_VERSION_NUMBER / 1000) % 1000)
 int		archive_api_feature(void);
+#endif
 
-
+#if ARCHIVE_VERSION_NUMBER < 3000000
+/* This should never have been here in the first place. */
+/* Legacy of old tar assumptions, will be removed in libarchive 3.0. */
 #define	ARCHIVE_BYTES_PER_RECORD	  512
 #define	ARCHIVE_DEFAULT_BYTES_PER_BLOCK	10240
+#endif
 
 /* Declare our basic types. */
 struct archive;
@@ -119,6 +114,7 @@ struct archive_entry;
 #define	ARCHIVE_WARN	(-20)	/* Partial success. */
 /* For example, if write_header "fails", then you can't push data. */
 #define	ARCHIVE_FAILED	(-25)	/* Current operation cannot complete. */
+/* But if write_header is "fatal," then this archive is dead and useless. */
 #define	ARCHIVE_FATAL	(-30)	/* No more operations are possible. */
 
 /*
@@ -146,7 +142,7 @@ struct archive_entry;
 typedef ssize_t	archive_read_callback(struct archive *, void *_client_data,
 		    const void **_buffer);
 /* Skips at most request bytes from archive and returns the skipped amount */
-#if ARCHIVE_API_VERSION < 2
+#if ARCHIVE_VERSION_NUMBER < 2000000
 typedef ssize_t	archive_skip_callback(struct archive *, void *_client_data,
 		    size_t request);
 #else
@@ -370,7 +366,7 @@ void		archive_read_extract_set_skip_file(struct archive *,
 int		 archive_read_close(struct archive *);
 /* Release all resources and destroy the object. */
 /* Note that archive_read_finish will call archive_read_close for you. */
-#if ARCHIVE_API_VERSION > 1
+#if ARCHIVE_VERSION_NUMBER >= 2000000
 int		 archive_read_finish(struct archive *);
 #else
 /* Temporarily allow library to compile with either 1.x or 2.0 API. */
@@ -446,7 +442,7 @@ int		 archive_write_open_memory(struct archive *,
  */
 int		 archive_write_header(struct archive *,
 		     struct archive_entry *);
-#if ARCHIVE_API_VERSION > 1
+#if ARCHIVE_VERSION_NUMBER >= 2000000
 ssize_t		 archive_write_data(struct archive *, const void *, size_t);
 #else
 /* Temporarily allow library to compile with either 1.x or 2.0 API. */
@@ -456,7 +452,7 @@ int		 archive_write_data(struct archive *, const void *, size_t);
 ssize_t		 archive_write_data_block(struct archive *, const void *, size_t, off_t);
 int		 archive_write_finish_entry(struct archive *);
 int		 archive_write_close(struct archive *);
-#if ARCHIVE_API_VERSION > 1
+#if ARCHIVE_VERSION_NUMBER >= 2000000
 int		 archive_write_finish(struct archive *);
 #else
 /* Temporarily allow library to compile with either 1.x or 2.0 API. */