Modules created and initial files checked in

[Keith Packard]

On Mon, 2005-05-09 at 12:19 -0400, Kevin E Martin wrote:

> That's a really good question.  When I created the initial proto module
> components, I just used 7.0 for the version numbers to get the ball
> rolling, but I think you're correct that it would be better to use the
> library versions as a starting point for the corresponding proto
> packages.  

There are three version numbers here:

 1)  The X.org release number
 2)  The protocol revision
 3)  The library .so number
 4)  The library version

We would like to keep the library versions constant through multiple
X.org releases (especially across 6.9 and 7.0), so we can't base the
library versions on the X.org version

The .so version number will not necessarily be the same across different
operating systems as it depends on both local convention and system
capabilities.  So, we can't base the library version on the .so version
number.

For protocol libaries, the protocol revision should correlate pretty
directly with the ABI/API of the library, but this isn't always the
case, and it can go either way -- the library can often retain ABI
compatibility in the face of protocol changes, especially when the
protocol is demonstrated to have a catastrophic encoding bug.  And, even
protocol libraries end up with 'helper' functions that are added or
removed independent of protocol version changes.

However, I would like to try to hold the line on ABI changes in
libraries once they've reached 1.0 status and preserve the .so major
version number from that point without extremely strong provocation.
The Xft1/Xft2 transition is an instructive example here; instead of
replacing the older library with a new version, we augmented the system
by shipping both to make sure people could transition.  Of course, not
shipping both sets of headers was not my best plan; we will have to do
better the next time this happens.

So, while the library and protocol may have significant independent
changes, I would like to suggest that we *do* tie their version numbers
together to reduce confusion.  I initially assumed that the protocol
packages would have only two numbers (major/minor) tracking the protocol
version, but there are often editorial fixes or outright bugs in the
headers which need fixing without affecting the intended protocol
specification for which a revision number seems warrented.  So, this
means the protocol and library packages should each have three numbers,
the first two matching the protocol version and the third tracking the
package revision numbers.

For other standards-based libraries, I suggest numbering those packages
using the version number of the associated standard, again appending a
revision number for changes which are not associated with an updated
standard.

Other libraries should have bugs posted marking the absense of a
published standard...

> Note that as we move forward, the protocol and library
> version numbers will probably get out of sync since we can make major or
> minor changes to a library without a corresponding change to the
> protocol headers (e.g., deprecating library functions or adding new
> functions that make use of the existing protocol).

Again, the .so version of the library will differ based on convention or
capability of the underlying platform, so we must not associate library
version numbers with .so names.

> This re-raises the issue that I raised in an earlier thread regarding
> library headers being intertwined with protocol headers.  Ideally the
> protocol and library interface headers would be separable, but right now
> they are not.  Making all headers separable (and moving the lib headers
> to the lib module) could cause problems for ISVs who include the proto
> header instead of the lib header.  I would like to see this fixed, but I
> don't know if this is the appropriate time.  What do others think?

The existing headers contain three parts:

 1)	protocol
 2)	Xlib API
 3)	internal X server APIs

Any headers which are currently directly referenced by applications are
(by definition) part of the implicit API.  These should all exist in
some form in the standard include directory.  To retain API
compatibility (a very good idea), we need to make sure that applications
get all of the necessary Xlib API information when they include the
usual collection of these files.

I'm far less concerned about preserving the X server API here, so I
suggest that we remove those from any headers needed by applications and
move them to X server-specific headers.

Then I suggest that we can migrate the protocol data to new files
installed in the protocol directory.  Then move the Xlib API to the more
naturally named header file and empty any supplementary header files to
only refer to the Xlib header file.  This Xlib header file can refer to
the protocol header file.

If we don't change these now, we'll never manage to separate the
protocol from the Xlib API, and XCB will be forever burdened with that.

> 
> > One comment: can we *please* not call the MIT-SCREEN-SAVER protocol
> > module, 'SS'?
> 
> Sure.  What would you suggest as an alternative, ScrnSaver?

lets keep all of the module names lower case only so that the module
name exactly matches the pkg-config file name.

I realize our library names include upper case letters, but we shouldn't
take that as an opportunity to spread the confusion elsewhere.

-keith

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.x.org/archives/xorg-modular/attachments/20050509/99a06a33/attachment.pgp