backend-specific code/dependencies need documentation (and specification)

[ePaul]

I just switched from Ceylon 1.1 to Ceylon 1.2, and after updating the version numbers of the dependencies in my module.ceylon, ceylon compile gives me the following errors:

source/codegolf/ceylon/module.ceylon:3: error: native import for cross-platform module (mark either the module or the import as native)
    import ceylon.io "1.2.0";
           ^
source/codegolf/ceylon/module.ceylon:4: error: native import for cross-platform module (mark either the module or the import as native)
    import ceylon.math "1.2.0";
           ^
source/codegolf/ceylon/module.ceylon:5: error: native import for cross-platform module (mark either the module or the import as native)
    import javax.script "7";
           ^
source/codegolf/ceylon/module.ceylon:6: error: native import for cross-platform module (mark either the module or the import as native)
    import oracle.jdk.scripting "7";
           ^
source/codegolf/ceylon/module.ceylon:7: error: native import for cross-platform module (mark either the module or the import as native)
    import ceylon.interop.java "1.2.0";
           ^
ceylon compile: There were 5 errors

This was my file:

module codegolf.ceylon "1.0.0" {
    import ceylon.io "1.2.0";
    import ceylon.math "1.2.0";
    import javax.script "7";
    import oracle.jdk.scripting "7";
    import ceylon.interop.java "1.2.0";
}

The old file

module codegolf.ceylon "1.0.0" {
    import ceylon.io "1.1.0";
    import ceylon.math "1.1.0";
    import javax.script "7";
    import oracle.jdk.scripting "7";
    import ceylon.interop.java "1.1.0";
}

worked without problems in Ceylon 1.1.

Some use of Google showed me that this came in with issue #499 + #500.

But neither the language specification nor the reference for modules or native contain any mention of that requirement, or even how the syntax would look like.

Could that please be fixed? (The 1.2 announcement says the spec is "complete", which is actually is not, as this issue shows.)

[gavinking]

Yes, we dropped the ball on documenting this requirement. Ceylon 1.2 should have come out with a migration guide. It was an oversight. Won't happen again.

[gavinking]

Migration guide:

http://ceylon-lang.org/blog/#migrating_from_ceylon_12

[ePaul]

@gavinking Thanks, this is a first good step. I still think it should also be added to the specification (and the reference).

[gavinking]

@ePaul Well my thinking on this was that since this is an interop concern, and since the language spec does not, in general, address interop concerns, that it didn't belong in the spec itself. Perhaps that's wrong; it feels like a borderline case.

But what we certainly need to do is fully document the rules about native on the website, and I've already asked @quintesse to do that. Furthermore, it also needs to be covered in the tour, and I'm not sure why and how it slipped my mind to do that before the 1.2 release. Probably I'm getting old.