Feature Requests item #1578577, was opened at 2006-10-17 01:18
Message generated for change (Comment added) made by mhoenicka
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=512948&aid=1578577&group_id=65979
Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Priority: 5
Submitted By: Peter MacDonald (pcmacdon)
Assigned to: Nobody/Anonymous (nobody)
Summary: version number in header
Initial Comment:
As libdbi evolves and functions are added
it might be useful to put
a version number in the dbi.h header ala Tcl. eg.
#define DBI_VERSION "8.1"
#define DBI_VERSION_MAJOR "8"
#define DBI_VERSION_MINOR "1"
and would save doing bit hit and miss things like
#ifdef DB_TYPES_NULL
...
#endif
----------------------------------------------------------------------
>Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-23 11:02
Message:
Logged In: YES
user_id=85809
I absolutely agree with the purpose of this request. However
you seem to forget that compilation against a particular
version of libdbi is only half of a developers job. The
other half is ensuring that the compiled app also links to
the installed version of the library at runtime. If you
maintain one set of version numbers for the compiler, and
another set for the runtime linker, you will eventually end
up with an application that builds but does not load or
would load if only you could build it. From that I think we
agree that both the application developer and the runtime
linker should work with the same version numbers.
The question is which numbers we should use. We can freely
choose a version number for our project, but as stated
before we cannot force a particular library version if we
use libtool. libtool is portable and has served the
community for more than 10 years. I do not expect myself to
be more intelligent than libtool, so I suggest to use it
just as it is. Therefore, it is not an additional level of
indirection to ask developers to use the interface version
instead of the (arbitrary) project version. In contrast,
asking developers and package maintainers to use one set of
numbers for compiling and another set of numbers for
packaging and ensuring runtime linking *is* another level of
indirection. This has so far just not been apparent as no
one of the libdbi developers, including me, took care to
maintain the libtool versioning. Try building an executable
on a box using the current libdbi version and run it on a
box with 0.7.1 installed. You'll get boatloads of undefined
symbol errors instead of the clear message that the library
that the executable was linked against is missing from your
system. This is the kind of confusion that our version
numbers are supposed to prevent.
BTW LIB_CURRENT is as meaningless to the compiler as
DBI_VERSION_MAJOR or any other definition. It is the
developers job to make sense of it, and I am convinced that
using the interface numbers instead of release version
numbers simplify the task if you look at the whole chain of
events, up to the end-user who runs your application.
To make things a little easier to digest I'd suggest to bump
up the major version number of the next release that changes
the interface. We're currently at 0.8.1. Here the major
version is 0, not 8 (!). The interface version (LIB_CURRENT)
is also 0. The implementation number (LIB_REVISION)
unfortunately got stuck at 5 due to my neglect, and should
better be 8. Let the next incompatible change create
interface 1:0 (CURRENT:REVISION), which we'll release as
project version 1.0, essentially removing the split between
project version number and interface version.
There is another aspect which we didn't discuss so far. We
cannot (at least I didn't find a way to) use libtool to make
sure libdbi can load a particular driver version. The
drivers are loaded dynamically, so we essentially face the
same problem as the runtime linker. We started in the 0.8.x
series to guarantee developers that any 0.8.x release of
libdbi would be able to load any 0.8.x release of
libdbi-drivers. Using the suggested version and interface
numbers would essentially allow us to continue to do so with
just one set of numbers to maintain, as we can generate the
libdbi release version from the interface number.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-22 22:51
Message:
Logged In: YES
user_id=190660
Ultimately the purpose of this feature request
was to provide developers, the users libdbi
(tcldbi for example) a way of maintaining
source code to be compiled against multiple,
possibly incompatible, versions of libdbi.
This implies that Developers should easily be
able to discover the version of libdb they are
compiling against by simple inspection of the
interface file dbi.h. It should be obvious
to them how they can subsequently detect and
compile around changes in libdbi.
Tying it to symbols like LIB_CURRENT will not be
intuitive, and at any rate may be meaningless
to the compiler. This is because the shared
libraries idea of an interface change may be
different from the compilers where even a #define
change can cause a failure.
Moreover, developers should be able transform
Changelog/NEWS entries like:
version 0.8.1: ...
- New functions were added ..
dbi_conn_quote_string()
dbi_conn_quote_string_copy()
...
into code as easily as possible. As far as the
developer and compiler are concerned, these two
things (header and changelog) is the interface.
In other words, make it as easy as possible for
users to interface with the library, even at the
risk that some administrative oversight during
a release may cause problems.
Finally, how does adding another level of
indirection in there make sense? ie. forcing
every user of libdbi to perform the mapping:
version 0.8.1 ==> 0.0.5
BTW: I mangled the proposed declarations, ie. it should have
read.
#define DBI_VERSION_MAJOR 0
#define DBI_VERSION_MINOR 8
#define DBI_VERSION_PATCH 1
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-22 18:25
Message:
Logged In: YES
user_id=85809
I've reopened this request as it seems to warrant further
discussion.
Before fiddling with the libtool values in configure.in you
may want to read up about what these numbers mean. A good
summary is in the goat book
(http://sources.redhat.com/autobook/autobook/autobook_91.html#SEC91).
One key point is that there is no way to force a particular
library version number as these numbers are
platform-dependent and linker-dependent. You should accept
whatever libtool makes out of the input numbers.
Second, the LIB_AGE variable does not represent a
patchlevel. Rather, it is the number of major interface
revisions (the number in LIB_CURRENT) that the current
version of the library is able to serve. E.g. if you have
the third version of your library interface (LIB_CURRENT=2)
which is backwards-compatible with an application written
against the first interface, then LIB_AGE=2.
Therefore, using DBI_VERSION_MAJOR 8 and the like is
deceptive and essentially wrong. Application developers
should be concerned with the interface, not with a
particular (and more or less arbitrary) version number of
the project.
There are two reasons why I don't want to hard-code things
like DBI_VERSION_MAJOR: first, as mentioned above developers
should focus on the interface, not the project version.
Second, anything that is hardcoded will eventually not be
updated in time and cause confusion, because the compiler
and the run-time linker get different version informations.
If you can derive something, then don't hardcode it.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-22 18:10
Message:
Logged In: YES
user_id=190660
I changed configure.in to:
LIB_CURRENT=8
LIB_REVISION=2
LIB_AGE=0
And this built libdbi.so.8.0.2 which was not quite desired.
So I changed it to
LIB_CURRENT=8
LIB_REVISION=0
LIB_AGE=2
and after autogen.sh it built libdbi.so.6.2.0 so not sure
what is going on there.
Anyways, I'd like to suggest using the following macro names
instead of the rather obscure automake symbols:
#define DBI_VERSION_MAJOR 8
#define DBI_VERSION_MINOR 2
#define DBI_VERSION_PATCHLEVEL 0
ie. for the user these should be guessable by inspection.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-22 17:53
Message:
Logged In: YES
user_id=190660
I got the cvs head to build (after wrestling with autoconf
for a while) and it is now building and producing:
libdbi.so.0.0.5
Are you planning to roll this version number to 8.2 somehow?
I don't know. It's probably just me, but I don't
see why you don't just manually hardcode the version number
in there rather than rely on the rather fragile and
intractible structure provided by autoconf. It seems
like another level of indirection that is not really needed.
my 2c.
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-18 22:21
Message:
Logged In: YES
user_id=85809
I've checked in the suggested changes. With the current CVS
version you can access the libtool interface version info
through the defines called LIBDBI_LIB_CURRENT,
LIBDBI_LIB_REVISION, and LIBDBI_LIB_AGE. These numbers do
not have much in common with the libdbi version numbers, but
they are supposed to reflect all changes to the libdbi API
in future releases.
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-18 17:55
Message:
Logged In: YES
user_id=85809
Oh, I almost forgot that. To create a header file that
defines these values for other apps I'd suggest to let
configure create dbi.h from a dbi.h.in file using the
AC_CONFIG_FILES macro. This performs the necessary
substitutions.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-18 17:31
Message:
Logged In: YES
user_id=190660
As long as the version number ends up in the dbi.h file.
This because user/compiler may not have access to source.
So if that is what happens, great.
I'm assuming this would involve something like:
#define DBI_VERSION_MAJOR @LIB_CURRENT@
#define DBI_VERSION_MINOR @LIB_REVISION@
in a 'dbi-version.h.in' file, which would be included by
dbi.h
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-18 13:32
Message:
Logged In: YES
user_id=85809
I think this is less hairy than I thought. configure.in
defines LIB_CURRENT=0, LIB_REVISION=5, LIB_AGE=0 which is
later used in Makefile.am to construct the -version-info
option for libtool. It should suffice to add
"-DLIB_CURRENT=\"@[EMAIL PROTECTED]" and so on to AM_CPPFLAGS in
order to make these values available for C code.
Using the interface version of libtool has the added benefit
that developers using libdbi do not have to figure out which
libdbi version uses which interface.
Would that solve your needs for TclDBI?
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-18 09:54
Message:
Logged In: YES
user_id=85809
I see. But before adding defines manually, I'd like to
investigate whether these values can be generated from the
libtool versioning information. Currently libdbi does not
use libtool versioning correctly (the version has remained
the same since the project started). I'd greatly appreciate
if someone could lend me a hand in setting up the libtool
versioning properly and in figuring out how to propagate
this information into a header file.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-18 05:43
Message:
Logged In: YES
user_id=190660
I should add that the main use for this feature
is for TclDBI, which may be compiled against
multiple versions of LibDBI.
----------------------------------------------------------------------
Comment By: Peter MacDonald (pcmacdon)
Date: 2006-10-17 19:39
Message:
Logged In: YES
user_id=190660
Yes, am aware of the dbi_version() et al functions
which work great for run-time, but not compile-time.
8.1 contained new functions that were not found in 7.1,
and there is no easy way to detect this at compile time.
Here is an example extract of what I'm doing now:
#ifdef DBI_VALUE_NULL
if (!dbi_conn_quote_string(h->conn, &cpq)) {
...
}
#else
if (!dbi_driver_quote_string(dbi_conn_get_driver(h->conn),
&cpq)) {
...
}
#endif
This works for 7.1-8.1, but will not for 9.1 (when it comes
out).
Version strings in the header will allow something like:
#define DBI_VERSION "9.1"
#define DBI_VERSION_MAJOR 9
#define DBI_VERSION_MINOR 1
/* ... */
#if (!defined(DBI_VERSION))
/* ... */
#elif ((DBI_VERSION_MINOR == 1) && (DBI_VERSION_MAJOR==9))
/* ... */
#else
/* ... */
#endif
----------------------------------------------------------------------
Comment By: Markus Hoenicka (mhoenicka)
Date: 2006-10-17 16:29
Message:
Logged In: YES
user_id=85809
Are you aware of the current version facilities in libdbi?
const char *dbi_version() returns a string containing the
libdbi version
const char *dbi_driver_get_version(dbi_driver Driver)
returns a string containing the version of the database driver
Both libdbi and libdbi-drivers use the version value set in
configure.in. Having the version information in one spot
only greatly simplifies maintenance. Using functions instead
of defines to access the version values is preferable
because functions allow your code to adapt dynamically to
the installed versions of the library and the drivers.
defines create executables that are adapted to a particular
version at build time.
We should think about making the version information easier
to parse though. Strings do not lend themselves to easy
comparison. One way to fix this is to add functions that
return the version as an integer value, e.g. computed as
series*10000 + major*100 + minor, resulting in something
like 801 for version 0.8.1. A similar computation is used in
the dbi_conn_get_engine_version() function which returns the
version of the database engine.
----------------------------------------------------------------------
You can respond by visiting:
https://sourceforge.net/tracker/?func=detail&atid=512948&aid=1578577&group_id=65979
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Libdbi-drivers-devel mailing list
Libdbi-drivers-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/libdbi-drivers-devel
