8000 `@stableABI` SIP. by DarkDimius · Pull Request #654 · scala/docs.scala-lang · GitHub
[go: up one dir, main page]
Skip to content

@stableABI SIP. #654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 13, 2017
Merged

@stableABI SIP. #654

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0a8d6aa
Inital draft of `@binaryCompatible` proposal.
DarkDimius Jan 13, 2017
810637b
@binaryComatible: fixes and clarifications.
DarkDimius Jan 13, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
@binaryComatible: fixes and clarifications.
  • Loading branch information
@DarkDimius
DarkDimius committed Feb 13, 2017
commit 810637bfc9de107682aa0778813330a9d7c9184c
22 changes: 19 additions & 3 deletions sips/pending/_posts/2017-01-13-binary-compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ disqus: true

__Dmitry Petrashko__

__first submitted 13 February 2017__
__first submitted 13 January 2017__

## Introduction ##
Copy link
Contributor
@xeno-by xeno-by Jan 17, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that this document would benefit from the definitions of the following terms:

  1. Binary compatibility (both the intransitive and transitive variations used in the text below)
  2. Public API
  3. Binary signature
  4. The notion of signatures being different from those written by their authors.

I'd suggest having a small example that introduces and illustrates these notions.


Expand All @@ -19,7 +19,15 @@ As long as signatures of methods in source is not changed, `@binaryCompatible` a
will be compatible across major version of Scala.

## Use Cases
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. < 10000 /p>

Can we number these use cases, i.e. have this section look as follows:

1) Use case 1 
<explanation>

2) Use case 2
<explanation>

etc

Dotty currently uses java defined interfaces as public API for SBT in order to ensure binary compatibility.
In case there's a need to develop an API that will be used by clients compiled using different major versions of Scala,
the current approach is to either develop them in Java or to use best guess to restrict what Scala features should be used.
There's also a different approach which is used by SBT: instead of publishing a binary `compiler-interface`, sources are published instead
that would be locally compiled.

There's also a use-case of defining a class which is supposed to be also used from Java.
`@binaryCompatible` will ensure that there are no not-expected methods that would show up in members of a class or an interface.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/not-expected/unexpected/


Dotty currently uses java defined interfaces as public API for IntelliJ in order to ensure binary compatibility.
These interfaces can be replaced by `@binaryCompatible` annotated traits to reach the same goal.

## Design Guidelines
Expand Down Expand Up @@ -55,7 +63,6 @@ trait AbstractFile {

@binaryCompatible
trait SourceFile extends AbstractFile {
/** @return The content of this file as seen by the compiler. */
def content(): Array[Char]
}

Expand All @@ -75,13 +82,22 @@ object Diagnostic {
@static final val INFO: Int = 0
}

@binaryCompatible
class FeaturesInBodies {
def apiMethod: Int = {
// as body of the method isn't part of the public interface, one can use all features of Scala here.
lazy val result = 0 // while lazy vals are prohibited in the class, they are allowed in the bodies of methods
result
}
}
{% endhighlight %}
```

## Features that will fail compilation with `@binaryCompatible`
The features listed below have complex encodings that may change in future versions. We prefer not to compromise on them.
Most of those features can be simulated in a binary compatible way by writing a verbose re-impelemtation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo.

which won't rely on desugaring performed inside compiler.
Note that while those features are prohibited in the public API, they can be safely used inside bodies of the methods.

- public fields. Can be simulated by explicitly defining public getters and setters that access a private field;
- lazy vals. Can be simulated by explicitly writing an implementation in source;
Expand Down
0