Compiler Version in .a3c Storyfiles

[tajmone]

@thoni56, a few question about the ALAN compiler version stored in .a3c files (under header->version[]).

Compiler Version State

In main.c L247 we find:

static char *decodeState(int c) {
    static char state[2] = "\0\0";
    switch (c) {
    case 0: return ".";
    case 'd': return "dev";
    case 'a': return "alpha";
    case 'b': return "beta";
    default:
        state[0] = header->version[3];
        return state;
    }
}

What would the default case be used for? It seems that it will just return whatever character it contains. Is it actually ever used, or is it just a reasonable fallback for future uses?

When is dev used? I've compiled an adventure using ALAN 3.0beta8 build 2276, but the stored version in the .a3c file is just "3.0beta8", although it's a developer snapshot.

So, it seems impossible to tell if an adventure was compiled with a developer snapshot by looking at header->version[], since dev snapshots sign them just like their latest release.

In terms of compatibility, a dev snapshot could contain (as it's often the case) new features which are not present in the latest Beta release, so running an adventure compiled with a dev snapshot on Beta interpreter could actually lead to errors, even if they belong to the same version.

Or is it the case that the above scheme is intended for official releases only, meaning that anything relating to dev builds is unchecked since only developers should be fiddling with such tests, and they are expected to know what they are doing (i.e. use same-version SDK tools) and they are doing it at their own risk?

The ALAN Scheme

I'm also not entirely sure how the ALAN scheme works in general, since I've only seen it being used within Beta stage.

From what I understood from the above code, once ALAN reaches the stable stage with v3.0.0, the state byte will become 0, resulting in versions like 3.0.0, etc., where the state segment is basically suppressed in favour of a separating ..

But after ALAN becomes stable, will there still be Beta and Alpha releases, e.g. 3.0beta1 for the development snapshot(s) of the upcoming 3.0.1? Will the dev state be used? or will development snapshots just sign adventures using the stable version on which they are based (like they do now).

I've seen the comment on compatibility rules found in main.c L324:

void checkVersion(ACodeHeader *header)
{
    /* Strategy for version matching is:
       1) Development interpreters/games require exact match
       2) Alpha, Beta and Release interpreters will not run development games
       3) Alpha interpreters must warn if they run beta or release games
       4) Beta interpreters may introduce changes which are not alpha compatible,
          if the change is a strict addition (i.e. if not used will not affect
          alpha interpreters, example is introduction of a new opcode if it is
          done at the end of the list)
       5) Release interpreters should run alpha and beta games without problems
       NOTE that we are working with a non-reversed version string/word here.
    */

but even in this context, I'm not entirely sure what "Development interpreters/games" refers to, since dev snapshots are not leaving any print in the adventure header.

Hopefully these questions of mine might also help you see the code comments through the eyes of someone who's looking at it for the first time, in terms of small additions or tweaks to the source comments that could make the code more accessible to newbies.

[thoni56]

@thoni56, a few question about the ALAN compiler version stored in .a3c files (under header->version[]).

Compiler Version State

In main.c L247 we find:

...

What would the default case be used for? It seems that it will just return whatever character it contains. Is it actually ever used, or is it just a reasonable fallback for future uses?

Yes, just a reasonable fallback. Many modern C-compilers warns for switches that don't have cases for all possible values, so that is another reason.

When is dev used? I've compiled an adventure using ALAN 3.0beta8 build 2276, but the stored version in the .a3c file is just "3.0beta8", although it's a developer snapshot.

"dev" was actually an even earlier state than alpha, so before all the alphas, there were "dev" versions. I'm quite confident that this is what is refered to in the code.

So "dev" is not the snapshots.

dev -> alpha -> beta -> release

E.g 3.0dev34 -> 3.0alpha14 -> 3.0beta9 -> 3.0

So, it seems impossible to tell if an adventure was compiled with a developer snapshot by looking at header->version[], since dev snapshots sign them just like their latest release.

In terms of compatibility, a dev snapshot could contain (as it's often the case) new features which are not present in the latest Beta release, so running an adventure compiled with a dev snapshot on Beta interpreter could actually lead to errors, even if they belong to the same version.

Or is it the case that the above scheme is intended for official releases only, meaning that anything relating to dev builds is unchecked since only developers should be fiddling with such tests, and they are expected to know what they are doing (i.e. use same-version SDK tools) and they are doing it at their own risk?

Yes, that is a good summary, snapshots are not marked except in the packaging, and a developer should know ;-) This state is not completely to my liking since snapshots do tend to be used by some people, like you ;-) But for those few it is probably easy to pick another snapshot and try again, or ask about the problem.

Maybe an important point is that you should never release a game that has been compiled with a snapshot.

The ALAN Scheme

I'm also not entirely sure how the ALAN scheme works in general, since I've only seen it being used within Beta stage.

From what I understood from the above code, once ALAN reaches the stable stage with v3.0.0, the state byte will become 0, resulting in versions like 3.0.0, etc., where the state segment is basically suppressed in favour of a separating ..

But after ALAN becomes stable, will there still be Beta and Alpha releases, e.g. 3.0beta1 for the development snapshot(s) of the upcoming 3.0.1? Will the dev state be used? or will development snapshots just sign adventures using the stable version on which they are based (like they do now).

I've seen the comment on compatibility rules found in main.c L324:

void checkVersion(ACodeHeader *header)
{
    /* Strategy for version matching is:
       1) Development interpreters/games require exact match
       2) Alpha, Beta and Release interpreters will not run development games
       3) Alpha interpreters must warn if they run beta or release games
       4) Beta interpreters may introduce changes which are not alpha compatible,
          if the change is a strict addition (i.e. if not used will not affect
          alpha interpreters, example is introduction of a new opcode if it is
          done at the end of the list)
       5) Release interpreters should run alpha and beta games without problems
       NOTE that we are working with a non-reversed version string/word here.
    */

but even in this context, I'm not entirely sure what "Development interpreters/games" refers to, since dev snapshots are not leaving any print in the adventure header.

To sum up how I think I have been thinking about this:

• alpha and beta state are only applicable to next minor version, an upcoming 3.1 will have beta versions which will have consequitive numbers (3.1beta1, 3.1beta2, ...) just as the upcoming 3.0 has
• next upcoming non-beta is 3.0, which will be equivalent to 3.0.0
• any official corrections till increment correction/patch number so that's kind of semantic versioning

In a way you could see Alan using semantic versioning, but only for non-dev/alpha/beta releases. For dev/alpha/beta the state replaces the second dot, but an increment in the last number for a beta version, indicates that since it is not an official "official" release, that "patch" might be more than that, and the next "real" release will stabilize that minor (at least) version. 3.0beta1 means first "patch" after "alpha" on the way towards 3.0, and 3.1beta12, well, you get it.

Not totally clean or clear, and I've been thinking about changing it of and on, but all automation does it this way, and I think most people intuitively feel what 3.0beta9 means (almost 3.0, but not quite yet...).

Hopefully these questions of mine might also help you see the code comments through the eyes of someone who's looking at it for the first time, in terms of small additions or tweaks to the source comments that could make the code more accessible to newbies.

+1