Library Versioning

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Library Versioning

Diego Nehab-3
Hi,

While we are at it, here is a doubt I have always had.

There is the Lua version, and there is the extension library version.
LuaSocket 2.0 works with both Lua 5.0 and Lua 5.1. Other libraries work
only with 5.0, or only with 5.1 (LuaSocket 3.0 will probably be 5.1
only).

Should we make it obvious, in the extension library version, which Lua
it supports?

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

D Burgess-4
Diego Nehab  wrote:
> Should we make it obvious, in the extension library version, which Lua
> it supports?

Do you mean in name of the extension library? or in the APIs for your
library, e.g. socket

Methinks one LuaSocket library does not support both 5.0 and 5.1,
(not on windows anyway), it is two different builds of two DLLs which
get put in the separate directories.

DB
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Diego Nehab-3
Hi,

> Do you mean in name of the extension library? or in the APIs for your
> library, e.g. socket

Not sure I know how to answer this. Let's say LuaSocket 2.0 was only Lua
5.0 compatible. Someone suggested I should update a LuaSocket version
number from 2.0 to, say, 2.1, if I added support to Lua 5.1.  Does that
make sense? I mean, nothing else would have changed in LuaSocket...

> Methinks one LuaSocket library does not support both 5.0 and 5.1, (not
> on windows anyway), it is two different builds of two DLLs which get
> put in the separate directories.

The same distribution supports both, right? So what is the version of
the distribution?

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

D Burgess-4
Now I have it.

1) the C code and/or Lua code should do something like

assert(VERSION == "Lua5.1", "this version requires 5.1")

or

assert(VERSION == "Lua5.1" or VERSION == "Lua5.0,2",
  "this version requires 5.0.2 or 5.1")


2) What you are referring to at the end of the day is a name of a tarball or
zip file. Yes? Anecdotally the most common error I hear of with lua
packages is that they grab the wrong version of the tarball.

Why not like linux or MS and have:

luasocket-2.0-lua5.1.tar.gz
luasocket-2.0-lua5.2.tar.gz
luasocket-2.0-lua5.3.tar.gz

Using zlib as an example, it gets installed as libz.a

The fedora (as an example) tarball is something like zlib-1.4-i386.tar.gz

The above should solve the problem.

or do I still miss it?

DB
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Diego Nehab-3
Hi,

You got it, even after I botched the explanation. :)

> assert(_VERSION == "Lua 5.1", "this version requires 5.1")

This would make sure the library doesn't run in case the user manages to
compile it.

> Why not like linux or MS and have:
>
> luasocket-2.0-lua5.1.tar.gz
> luasocket-2.0-lua5.2.tar.gz
> luasocket-2.0-lua5.3.tar.gz

This is a very good idea. I am going to start doing this. Unless someone
else has a better idea.

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Andre Carregal
> De: Diego Nehab <[hidden email]>

> > luasocket-2.0-lua5.1.tar.gz
> > luasocket-2.0-lua5.2.tar.gz
> > luasocket-2.0-lua5.3.tar.gz
>
> This is a very good idea. I am going to start doing this. Unless someone else has a better idea.

I'm not sure if this applies to source versioning, but surely applies for binary versioning.

Source versioning relates to a published API, so if a module does not change its API for Lua 5.1 but compiles for it, ideally the module source should remain at the same major.minor version (the third number would change if the source has modifications but not the API). Note that this is valid for both C and Lua modules.

On the example above, the tar.gz files appear to be source only, so as long as LuaSocket 2.0 offers the same API for the three versions of Lua mentioned, the source distribution should remain a single file (luasocket-2.0.tar.gz), while the binary distribution could be spread in as many combinations as there were platforms and Lua versions (see LuaFileSystem 1.2 on http://luaforge.net/frs/?group_id=66&release_id=405 for an example).

By the way, since versioning is being mentioned, what about adopting some versioning policy for Lua modules? That would make things easier for module users and could open the doors for a Lua package manager such as Rocks, that have to take in account the module upward compatibility.

As an example, a policy like http://docs.rubygems.org/read/chapter/7 is being used for Kepler modules.

Andre
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Andy Stark
In reply to this post by D Burgess-4
Lua list <[hidden email]> wrote:
>the C code and/or Lua code should do something like
>
>assert(VERSION == "Lua5.1", "this version requires 5.1")

Some simple syntactic sugar in the Lua interpreter would be very sweet
here, something like:-

        expects "5.1"

...could print out a standard version warning message and quit. You would
also want a way to make this happen from C, of course. This would avoid
everyone having their own variations of the "sorry, you need at least
version xxx" message and would save memory, be easier to internationalise,
etc, etc...

&.


#####################################################################################
This e-mail message has been scanned for Viruses and Content and cleared
by NetIQ MailMarshal.
The Blackpool Sixth Form College.
#####################################################################################
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Diego Nehab-3
In reply to this post by Andre Carregal
Hi,

> Source versioning relates to a published API, so if a module does not
> change its API for Lua 5.1 but compiles for it, ideally the module
> source should remain at the same major.minor version (the third number
> would change if the source has modifications but not the API). Note
> that this is valid for both C and Lua modules.

What if the API is the same for Lua 5.1 and Lua 5.0, but the source code
is not? That's what I am talking about. It would become a mess. You
would have several files named luasocket-2.0.tar.gz, each for each
version of Lua, but all implementing the same API as far as Lua code is
concerned.

What David suggested is to make this part of the distribution file name.

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

RE: Library Versioning

Andre Carregal
In reply to this post by Diego Nehab-3
> Andre wrote:
> > Source versioning relates to a published API, so if a module does not
> > change its API for Lua 5.1 but compiles for it, ideally the module
> > source should remain at the same major.minor version (the third number
> > would change if the source has modifications but not the API). Note
> > that this is valid for both C and Lua modules.
>
> Diego wrote:
> What if the API is the same for Lua 5.1 and Lua 5.0, but the
> source code is not?

That would be the parenthesis. :o)

> That's what I am talking about. It would become a mess. You
> would have several files named luasocket-2.0.tar.gz, each for each
> version of Lua, but all implementing the same API as far as Lua code is
> concerned.

Indeed. What I am proposing assumes that your source is compilable in more
than one version of Lua.

So if luasocket-2.0.tar.gz is the source for Lua 5.0, the source that works
with both 5.0 and 5.1 would be released as luasocket-2.0.1.tar.gz

If your source is not compilable in both Lua versions, then you're probably
heading for a maintenance branch on your SCM tree or even the stagnation of
the old source base. In that case you'd better changing at least the second
number.

If that was the case, in the release docs you would indicate that LuaSocket
2.0 is only for Lua 5.0 and that LuaSocket 2.1 is only for Lua 5.1 for
example.

> What David suggested is to make this part of the distribution file name.

I see the point, but I still think that compatible versions (same API)
should get only third number versions (you can look at them as fixing the
source so it now compiles in 5.1) and incompatible versions should get
second or even first number versions (since now one version works and the
other don't).

But please, as long as it is clear which package one should get to use a
module in a version of Lua, use the system that feels better for you. I'm
really biased here.

Andre


Reply | Threaded
Open this post in threaded view
|

RE: Library Versioning

Diego Nehab-3
Hi,

> I see the point, but I still think that compatible versions (same API)
> should get only third number versions (you can look at them as fixing the
> source so it now compiles in 5.1) and incompatible versions should get
> second or even first number versions (since now one version works and the
> other don't).

I don't think we are understanding each other. There are *no* API
changes between LuaSocket 2.0 and LuaSocket 2.0.1. It's a bugfix version
and an upgrade to Compat-5.1r5. We agree on the versioning here.

Now suppose LuaSocket 2.0 did /not/ support Lua 5.1, but only Lua 5.0.
And suppose LuaSocket 2.0.1 supported Lua 5.1. How is the user supposed
to know about this? Reading the manual? Should I release it as LuaSocket
2.1 instead? This wouldn't make sense, there were no API changes as far
as Lua code is concerned.

This is the point. A library can support the same Lua side API
throughout different Lua releases. How do we associate version numbers
to such a library?  Ideally, the user would be able to tell *both* what
is the Lua side API compatibility and what Lua versions are supported.

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

RE: Library Versioning

Andre Carregal
In reply to this post by Diego Nehab-3
> Diego wrote:
> I don't think we are understanding each other. There are *no* API
> changes between LuaSocket 2.0 and LuaSocket 2.0.1. It's a
> bugfix version and an upgrade to Compat-5.1r5. We agree on the versioning
here.

Right, sorry for the noise

> Now suppose LuaSocket 2.0 did /not/ support Lua 5.1, but only Lua 5.0.
> And suppose LuaSocket 2.0.1 supported Lua 5.1. How is the
> user supposed to know about this? Reading the manual? Should I release it
> as LuaSocket 2.1 instead? This wouldn't make sense, there were no API
> changes as far as Lua code is concerned.

Here is the subtle part. Does your 2.0.1 version support 5.1 only, or both
5.x? See below.

> This is the point. A library can support the same Lua side API
> throughout different Lua releases. How do we associate version numbers
> to such a library?  Ideally, the user would be able to tell
> *both* what is the Lua side API compatibility and what Lua versions are
supported.

I agree with that too. I was just pointing that while your source runs in
both 5.x versions, there was no need to separate the distribution packages.
On the other hand, once it does not run on both versions you'd have two
branches of code, therefore two different packages.

And yes, in that case the packages could be called luasocket-2.0.1-lua50.tgz
and luasocket-2.0.1-lua51.tgz, that is clear enough I guess.

Andre


Reply | Threaded
Open this post in threaded view
|

RE: Library Versioning

Diego Nehab-3
Hi,

> Here is the subtle part. Does your 2.0.1 version support 5.1 only, or both
> 5.x? See below.

It will support both.

> I agree with that too. I was just pointing that while your source runs in
> both 5.x versions, there was no need to separate the distribution packages.
> On the other hand, once it does not run on both versions you'd have two
> branches of code, therefore two different packages.

Right, but LuaThread, which I decided to work on right now will be
different. I will have one version for each of Lua 5.0 and 5.1.

Regards,
Diego.
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Alex Queiroz
In reply to this post by Diego Nehab-3
Hallo,

On 4/4/06, Diego Nehab <[hidden email]> wrote:
>
> Now suppose LuaSocket 2.0 did /not/ support Lua 5.1, but only Lua 5.0.
> And suppose LuaSocket 2.0.1 supported Lua 5.1. How is the user supposed
> to know about this? Reading the manual? Should I release it as LuaSocket
> 2.1 instead? This wouldn't make sense, there were no API changes as far
> as Lua code is concerned.
>

     Everywhere else this is stated in the web page/documentation of
the software. I agree that appending the Lua version to the file name
is cumbersome.
     Besides, at one point a single LuaSocket source tree could be
compiled for two different versions of Lua, say 5.1 and 5.2. Would you
release two identical source tarballs?

--
-alex
http://www.ventonegro.org/
Reply | Threaded
Open this post in threaded view
|

Re: Library Versioning

Diego Nehab-3
Hi,

>     Everywhere else this is stated in the web page/documentation of
> the software. I agree that appending the Lua version to the file name
> is cumbersome.
>     Besides, at one point a single LuaSocket source tree could be
> compiled for two different versions of Lua, say 5.1 and 5.2. Would you
> release two identical source tarballs?

I wouldn't have a problem with that. The source code is small, and I
believe the clarity would be worth it. Regardless, we need something like
this for the binaries.

Regards,
Diego.