"API version" switch

Started by Crimson Wizard, Mon 15/09/2014 14:04:03

Previous topic - Next topic

Crimson Wizard

This issue was created in the early days of open source development:
http://www.adventuregamestudio.co.uk/forums/index.php?issue=303.0

I want to bring it up again.

Reason / problem: we are inserting new stuff to script API header and removing something old. Both can break existing projects, or popular templates and script modules.
Spoiler

For example, recently added Character.FaceDirection breaks 9-verb MI template.
[close]
Solution: a per-module and/or global switch which defines API version.

Idea is to put API items in question in following blocks (pseudo-code):
Code: ags

#ifdef API_VERSION >= 3.4.0
int NewFunction();
#endif

#ifdef API_VERSION < 2.7.2
int OldFunction();
#endif


The compiler will have API version set for each module (ideally). These blocks will be processed only if condition is met, otherwise ignored.

There should be a global property in General Settings to define default API version (the highest for the new projects), and, preferrably, individual property for every script module. (Maybe rooms too).

#ifdef STRICT. The "STRICT" macro has been used to separate new OO-style classes and methods from old non-OO-style functions. Problem is that it has too much stuff hidden under itself (several iterations of API change), and sometimes the distinction is preferred.

#ifver. The "ifver"/"ifnver" macros allow to check current Editor's version. They are useful to provide backwards compatibility in script modules. However, they cannot be effectively used in API header, because, well, the Editor version is always the same, while some modules might need to be compiled with different API version.

Gurok

Okay, I've been thinking along similar lines. I don't know how practical it is, but at compile time, we can detect if a symbol exists (e.g. Character::FaceDirection)

So something like,

Code: ags
#ifndef_symbol Character::FaceDirection
function FaceDirection(this Character *, CharacterDirection direction, BlockingStyle block)
{
// User's face direction shim in here
}
#endif


would be possible.

I think I prefer your suggestion though. Could we make it a simple float (e.g. 2.72, 3.40) and extend its use to any defined macro? That way, someone could do:

Code: ags
#ifdef MI_9VERB_TEMPLATE_VERSION < 1.31
Display("This feature isn't available without the latest MI verb template.");
#endif


Anyway, no objections from me. I'm just sorry to cause such trouble. I thought because everyone implemented it, it would be a good candidate for inclusion.
[img]http://7d4iqnx.gif;rWRLUuw.gi

Crimson Wizard

#2
Quote from: Gurok on Mon 15/09/2014 14:19:29
Okay, I've been thinking along similar lines. I don't know how practical it is, but at compile time, we can detect if a symbol exists (e.g. Character::FaceDirection)
The problem here is that this will require changing existing script modules. While my suggestion was to provide a method that will let you use them without fixing.


Quote from: Gurok on Mon 15/09/2014 14:19:29
I'm just sorry to cause such trouble. I thought because everyone implemented it, it would be a good candidate for inclusion.
Uhhhh, why do you think it is because of you? Stop doing that, please :-\.
The changes to 3.3.0 already made someone fix their scripts (Speech functions).

Now, since the branch is WIP, we have time to think how to implement this in a better way.
I got distracted by other things, but it appeared to me that my suggestion on individual per-module setting needs some consideration: problem is that the script headers are included to every compiled script, so the compiled script setting probably will affect all included headers, not the settings of modules these headers belong too. (wtf)

Maybe global setting could be enough for starters. Although that would limit user to old API...

Crimson Wizard

#3
Bump!

http://adventuregamestudio.myjetbrains.com/youtrack/issue/AGS-9

Since I know little more about how script preprocessor works in the Editor now, I am seriously considering adding this switch to 3.4.0. Maybe not immediately, but certainly before final release.

Basically, since we do not have support for #if() expressions in script, we could simply use something like:
Code: ags

#ifdef API_VERSION_340
// declare new commands
#endif
#ifndef API_VERSION_340
// declare old commands
#endif



At least that would let use old modules and templates without fixing them.

Crimson Wizard

#4
Hmm hmm, making global switch appeared to be pretty easy actually.
https://github.com/adventuregamestudio/ags/pull/333

Basically, how this will work from user side: you load 3.2.1 project into 3.4.0, and in General Settings you already have "Scipt API version = 3.2.1".
If you want to use new functions, you will have to set it to 3.4.0, but be ready to fix your scripts in that case.

This is a pity that we did not try implementing this before. Issues with old/new function names are not always big deal, but happen often and may confuse people.

SMF spam blocked by CleanTalk