I'll not be here for 3 weeks - but I recently put some ideas about some minor changes for the 4.2 API on Tomasu's Wiki.

As I understand it, in 4.2 we want to be compatible with the current Allegro as much as possible, but just remove some of the worst inconsistencies in the API, along with prefixing it. In the long run (4.4, 4.6, 4.8...) we should get a quite nice API. The time in actual time, and not in version numbers, will depend on if we have developers of course (we decided on AD we don't have enough developers for a complete new API like A5 - AllegroPro (should I say Korval's lib?) will be there for that and hopefully we can mutually share some ideas for the driver implementations at some point..).

Not really sure a wiki is a good place for API discussions, since the changes will have to be discussed on [AD] anyway before going to CVS.. but since Tomasu's wiki looks quite empty except some code snippets, I thought I could put it there: http://awiki.strangesoft.net?AllegroAPIDesign

I'm not sure we should go for a prefixed api in 4.2.
The reason being that I'd personally like to get 4.2 out relatively soon and prefixing the whole API is something that takes time.

The main reason I'm eager to get 4.2 out soon is that currently, there is no officially stable Allegro version that supports MacOS X, and I think it is very important that one be available as soon as possible.
Ultimately, that's Angelo's call though.

Not that the version number matters that much anyway. If we clean up the TODO list and release the result as 4.2 and then start refitting the API for 4.3 or clean up the TODO list and start refitting the API while still in 4.1 doesn't really matter as far as time is concerned. It's not like development is a discrete process, jumping from version number to version number.

Yes, I agree. Version numbers are nothing. But for a stable release like 4.2.0, we should do some extended testing, like, have a freeze period of 2 or 3 weeks or so, and only do testing and bugfixing. Probably should have release candidates like for 4.0.0. I'm actually also wanting to have it out soon, maybe as Christmas present (That would be about 5 months.. maybe can even do it sooner.)

And we'll need to decide what to do about 4_0_branch at some point.

There's a number of bugfixes that could be backported to the 4.0 branch. It's up to Eric when 4.0.4 goes out though. Unless major bugfixes are needed after that, I suppose we can more or less forget about 4_0_branch once 4.2 comes out.

And I agree that we could aim for a christmas release of 4.2... I think we should try to have a regular flow of WIP releases going in the mean time though.

1. yes, a regular flow of WIPs is a good idea.

2. a christian holiday that has less and less meaning to most of the planet has zero to do with allegro, lets not align development with psuedo-religious festivals.

3. i think the pre-fixing is a long overdue thing, and the dropping of ex() etc, but all that for 4.2 seems like too soon. i think 4.2 should be the last nice stable release of the current API, that attempts to replace both the 4.0 branch and the 4.1._ WIP branch.

as soon as 4.2 is final and released, the next day we should do a major overhaul, and prefix at the same time, a few core developpers and a handful of 1/2 wits like myself, should get most of it done in a week.

idea: everyone with broadband should install a VOIP app, and the whole thing can get done in days not weeks!

Well, I didn't use this with any religious meaning. It's just a standard saying in English (even though I'm not a native speaker, I'm quite sure of that). And it won't influence the release date.

AJ, its just a day... It only has meaning if you asign it meaning. For me, its when I get to see my extended family. And eat lost of good food, and candy. So, its all good. Oh, not to mention giving a little happyness to lovedones, and recieving some in return.

Okay, I don't really see a note like this anywhere, nor can remember any responses to me saying this before, but please let me say agian:

Prefixing the entire API at once is a very bad idea.

The reason is obvious.. do it right the first time around. Once we create al_play_sample/al_set_gfx_mode, or whatever, that's it. We won't be able to recreate them without resorting to things like al_play_sample_ex and the like. Prefixed functions/typedefs should start after 4.2 is released, and be incremental. Some functions will have prefixed/improved counterparts by 4.4, more by 4.6, etc. There's no reason we have to have the entire API prefixed before having the redesigned API.

(I very rarely use this expression but: )
O.M.G.

Your actually going to convert the functions in groups as opposed to a whole? So that every time someone gets a new version, they have to go back over their functions and replace them with the prefixed versions? Everytime you release a new version...?

I think I'm going to be sick...

Its going to stay backwards compatable. You can just keep the old functions in there.

Then your not using the "strict" version of Allegro. And can you imagine functions with allegro al_ next to other allegro functions without them? ::hits the floor (along with Allegro's code readibility)::

And I assume all new functions with have that prefix. So if you don't convert it, and you want to use a new function, you have the same problem I listed above. ::jams pencil in left-eye::

I have a feeling that the redability problems will only happen if you use WIPs. IF not you wont have any of the prefixed api.. I'd say the prefixing, if not done between now and 4.2, should be done between 4.3(WIP) and 4.4.

But I could be wrong. 2 years is enough time to get the prefixing done

Shawn warned STRENUOUSLY against casually breaking backwards compatibility. Here's the section about it in its entirety:

[url http://alleg.sourceforge.net/future/shawns_thoughts.txt]

I don't think anyone's going to be ignoring that.

We will only be breaking compatibility once.. which is why we shouldn't rush in and prefix everything at once. We should only prefix what will be a part of the "new API". I'd also recommend against deprecating the old API functions when the new API replacements come up.. at least to not use the GCC deprecation flag (and generate so many warnings for compiling old programs).

I think Kitty Cat's idea might work, but it needs to be documented extremely well to get the point across to users, in bold, red, blinking text no less. The first time he said it on [AD] I didn't understand what he meant by breaking compatibility "only once".

Making sure I understand: If we followed Kitty Cat's way, then I think our timeline would work something like this. In each stable release (4.4, 4.6, 4.8) more and more sections of the API are redesigned. These will be lexically differentiated from the older API because of their "al_" prefixes. The newly introduced parts of the API will have the same API compatibility guarantees as the older API (i.e. stuff from 4.4 will exist in 4.6). At the same time, the parts of the older API which have been superceded will still be available. It is completely up to the user when and if he should update his programs to use the newer API. That bold text is the most important point to get across. If users don't see it, they will complain, and they will be pissed off, and we will get a bad rap.

At some stage, the entirety of the older API will have been replaced or updated. If a user prefers to upgrade his programs only once, he can wait until that time. If he prefers to not upgrade his programs at all, he can keep using the compatibility layer -- after all, if we decide that compatibility is to be retained throughout, it will not be any extra work for us to keep that compatibilty layer around (at least, initially).

The only problem is, how much compatibility can we retain? For really drastic changes, it may prove to be impossible. In that case, we are constrained by the past in what designs we can have for the future. I don't think that's entirely a bad thing, though. It prevents us from going too far over the edge.

BTW, I'd be happier if we moved this discussion to [AD].

Well, it all depends on what "too far over the edge" entails.

Limiting yourself to an API that has already proven itself to not be able to conform to the modern way of handling things (graphics, in particular) is just silly. It is not only that, it is counterproductive to advancing an API.

One of the reasons why Shawn's suggestion for a sudden change in API is a good one is so that the new API is not constrained by the bounds of the old one. To do so only invites creating the same problems that required a new API to begin with.

It has been said that Allegro abstracts hardware into a DOS box. Some of that may be still useable, and some of it isn't. But creating an abstraction into a mutant DOS box, a mere modification of a DOS box rather than a modern 2D game API, is just wrongheaded, and doesn't solve Allegro's problems.

This is, basically, the only significant discussion that the mainline Allegro developers have had with the actual Allegro users. Why are you so quick to move this to the ML, rather than discussing it openly?

Developement is done on the List. you want to help? go there. simple as that.

And, not all developers read these forums. Someone really should post weekly updates here of what's been happening on the mailing list again. That way, those that don't read the mailing list can still have some input.

Peter: That is exactly right. As for how much compatiblity we can keep this way.. I don't know. But it seems to be a better solution than to do a completely rewrite (re: Allegro 5) or to prefix everything and create/change the "new functions" as we see fit, until the new API is complete.

Nor is Allegro's new API going to be constrained by the old one. Since the new API will be prefixed with al_, there's no risk of function clashes, and if needs be, we can have: allegro/src/old_funcs (as a last case scenario for those pesky functions that just won't fit otherwise).

f*ck, I spent 20 min writing a reply in firefox, then promptly lost it all when I hit "Add Reply". Another reason email is better.

Anyway, the important part was in response to Kitty Cat: I have a feeling that a lot of things are possible given a background thread (e.g. emulating the a4 input API on top of the event-based input API which was slated for a5). This does tend to rule out DOS support, though, which I am personally willing to forsake. If we decide that, then we must say that the backward compatibility does not mean that all currently-supported OSes will remain supported. Actually, we should say that anyway. Slippery slope and all that, though.

Stable releases will be backward compatible. If you're using WIP releases, then that's a risk you're taking.

But yeah, as Peter said: this needs to be documented very well.
Once a new API is available under the hood of the old one, (and the new one by no means needs to be constrained to DOS), then we can either decide wether we break the API for good, or we can just tell users to use the new header file and ignore the old API.
At any rate, a new API would need to be tested in action prior to official release anyway. As far as I know, the plan used to be to test the redesgined "Allegro 5" API on top of current Allegrlo to see how it would work.

I used to do that for a while a (long) time a go. Writing actual summaries of discussion may be a little too much some of the time, but I guess I could post the changelog...

Nothing has been said that hasn't been said in previous threads already. Actual design threads on a forum like this tend to end in endless silly arguments where everyone has an opinion and everyone disagrees. There's just too much random noice. At least on a mailing list, people have to take more trouble to make a reply, forcing them to think more.
Beside which, as somone already said somewhere, Allegro development is a dictatorship, not a democracy.

As can be noted elsewhere, democracy really doesn't work all that well.

[Please, guys, keep the noise levels down.]

We won't need or use the deprecation flag if the new API is declared in a new header file. Either that, or the new API takes over allegro.h and the old API goes elsewhere. I prefer the former.

Also, the GTK+ and other folks have started a convention that headers go like /usr/include/gtk-2.0/gtk/gtk.h on Unix. This is a good convention I feel we should follow, as it allows you to install incompatible versions of the same library in parallel). It might be feasible for 4.2, even (I know Vincent has been advocating it for a while). Replies to 4.2 stuff => [AD].

I don't quite like that idea, though. Perhaps something like <allegro/allegro.h>, but we couldn't use <allegro-4.2/allegro.h> because that would implicitly break compatibility with 4.0, 4.1, 4.3, 4.4, etc..

The deprecation flag has nothing to do with what header the function is declared in, AFAIK. I just don't like the prospect that, by completing a new sound API, for instance, that every old sound function would produce a deprecation warning. Taking this a bit farther, one could argue that the deprecation flag shouldn't be used at all, since if a project uses -Werror it will fail to compile.. which is breaking compatiblity with older versions.

Gtk's include gets added to the include path, as does Qts. (my qt is in usr/qt/3*)

SDL's doesn't, nor do I see a good way to get Allegro's without having the user do it manually..

in some cases, yes the user would have to. But in linux, all youd have to do is add it to the `allegro-config --cflags` output.

Right, that would be horrible. In GTK+ you do #include <gtk/gtk.h>. To compile, you have to use pkg-config (similar to the allegro-config), which does -I/usr/include/gtk-2.0. Hope that clears it up.

Yes, it's a per-function thing.

The purpose of the deprecation flag is to help programmers who want to upgrade to find code they may have inadvertantly missed. What I'm saying is, if the old API and the new API are in different header files the deprecation flag isn't needed. To catch places where you haven't switched to the new API, just don't include the old-API header and try to recompile.

That's going a bit far. There's always -Wno-deprecated if you must.

How many programs use `allegro-config --cflags` now? Next to none, AFAIK.. I've never used it and've never had any problems.. the docs have never said anything aboiut it that I remember seeing..

But we already have something we can do like this already now... when the programmer defines ALLEGRO_NO_COMPATIBILITY it doesn't include various fixed point functions (itof, fsin, fcos, etc) due to libc name clash problems.. why not extend this to all deprecated functions and variables? That way, the Allegro headers won't include the declarations for the deprecated functions and variables, and the programmer can remove all references to them in their code. And old code will still compile without warnings.

And how many use `allegro-config --libs`? Why? Because they have to.

Any Unix-compatible one.

But they don't have to use `allegro-config --cflags`, nor has anything mentioned they have to. And requiring it now will break compatibility because then you'd have to go around and change system or project settings. Not to mention it looks fugly, IMO.

Not yet anyhow. this is for 4.2 or greater, I have no doubt that the plain allegro.h and allegro/* files will continue to be accessable for allegro 4.0 and 4.1 (via links, or compatability headers).

The allegro/* files don't need to be accessible, since AFAIK they were never meant to be included by a user program directly. As long as allegro.h and the other relevant library files are changed accordingly, anything can happen with them.

It matters if you install Allegro in a non-standard place, such as your home directory. Hence it's a good idea to use it, even if not mandatory so far.

Are you talking about 4.2 or the yet-to-come new API? For the new API, I think a new header is just cleaner. For 4.2, I guess it just depends if you want to encourage people to stop using the deprecated API. Old code that compiles but has warnings is no big deal, IMHO. It's just what happens.

Both. When a function or variable is replaced/superceded/depricated, it goes into the alcompat.h header (or another header that alcompat.h includes), which is automatically blocked out by the definition of ALLEGRO_NO_COMPATIBILITY. This way, programmers can fix code by finding which functions and variables are no longer working, or they can continue on with the current functions, with no warnings or problems.

Except code that is made to compile with -Werror. Not only that, but it'll look ugly and in bad form to have a ton of deprecation warnings fly by as code compiles.. especially if things work 100% as expected otherwise.

IMHO, projects that reach a stable final version and that the user has to build himself should not use -Werror, or at least include
-Wno-deprecated-declarations in the list of compilation options for exactly this reason.
Although it would be something to check, I think there are other libraries that also produce warnings during compilation if the library version is different from the one that was initially used to create the program.

I've seen far worse fly by when I compiled projects

This I don't get. You'd rather see that things didn't work as they should after a warning was given?

A warning is given when things might not work as expected (as far as the compiler's concerned). However, we know things will work as expected with respect to Allegro's deprecated features, so why generate a warning? You can simply dump the functions currently marked deprecated into a header that's excluded from compilation when ALLEGRO_NO_COMPATIBILITY is defined, so if a person cares about such problems and wants to fix them, he can simply define that and get to work.. otherwise it leaves the rest of us alone with full backwards compatiblity.

Don't forget, Allegro's been around for a while.. long before the deprecation attribute was available. Granted it's not smart to use -Werror on releases, but there's nothing enherently wrong with that when the warnings are generated by a compile problem, not a function attribute that was added after said project was released.

Anyway, about the timeline: if everyone here is pretty much in agreement with Kitty Cat's idea, let's copy this thread over to AD. I'd really like to get especially Eric, Angelo and Bob's responses.