jatcwang / ghid-compatibilitate-binara

Material complementar la Ghidul de compatibilitate binara al docs.scala.org.

Scopul acestei repo este de a ajuta autorii bibliotecilor sa reduca cantitatea de versiuni binare incompatibile pe care trebuie sa o faca. Aici veti gasi:

• Do e si Do nu e atunci cand scrieti biblioteca Scala
• Exemple de modificari incompatibile binare si sursa

Modificarile incompatibile mai evidente, cum ar fi eliminarea unei clase / metode, nu vor fi documentate in mod explicit.

Cuprins

• Exemple si explicatii ale codului de compatibilitate binara
  • Cuprins
• Exemple de cod
  • Executarea exemplelor
  • Cum sunt configurate exemplele
• Explicatie detaliata a DO-urilor si DONT-urilor
  • DO: Marcati metodele ca pachete private atunci cand efectuati modificari de interfata API
  • DONT: Adaugarea de parametri cu valori implicite la metode
  • EVITATI: Utilizarea claselor de cazuri
  • DO: Adnotati tipurile de returnare a metodei in mod explicit
  • DONT: Adaugarea de metode cu implementare implicita la trasaturi (2.11 sau anterior)
  • DONT: Inliniat din alte biblioteci

Executarea exemplelor

Asigurati-va ca ati instalat SBT si rulati scriptul

Va publica toate bibliotecile la nivel local atat pentru versiunea Scala 2.11, cat si pentru versiunea 2.12.

Dupa care,

pentru a executa aplicatia atat in ​​2.11 cat si in 2.12 (deoarece anumite exemple se aplica numai in versiunile scala mai vechi)

Cum sunt configurate exemplele

Acest set de depozite contine 4 baze de cod scala care simuleaza relatia reala dintre diferite biblioteci.

Mai intai avem App, aplicatia noastra care depinde de biblioteca A si B.

Atat biblioteca A, cat si B depind de o alta biblioteca comuna. Cu toate acestea, biblioteca A depinde de o versiune mai veche de common (common_old) si, astfel, in timpul executiei, versiunea mai veche common_old de care depinde A este evacuata.

Iata o vizualizare a graficului dependentei:

DO: Marcati metodele ca pachete private atunci cand efectuati modificari de interfata API

Metodele de marcare ca pachet privat intrerupe doar compatibilitatea sursei, ceea ce inseamna ca puteti rupe API-urile in siguranta fara a rupe compatibilitatea binara.

Inainte de:

Dupa:

DONT: Adaugarea de parametri cu valori implicite la metode

Versiunea Scala: toate

Incompatibilitate: binara

Desi este posibil sa nu provoace erori de compilare, modificarea listei de parametri a unei metode ii va schimba semnatura, rezultand NoSuchMethodError pentru cod compilat impotriva unei versiuni mai vechi

EVITATI: Utilizarea claselor de cazuri

Versiunea Scala: toate

Incompatibilitate: Binar + Sursa

Scala genereaza automat o multime de metode pentru clasele de cazuri (de exemplu, egal, hashCode). Semnatura unor metode generate, cum ar fi neaplicarea, depinde de parametrii constructorului clasei de cazuri si, astfel, adaugarea sau eliminarea parametrilor din constructorul primar al clasei de cazuri va rupe compatibilitatea binara.

Va recomandam sa nu utilizati clase de cazuri decat daca dvs.

• sunt increzatori ca campurile clasei de caz vor ramane constante pe masura ce bibliotecile evolueaza
• chiar am nevoie de metode precum generarea neaplicata pentru dvs.

Daca totusi doriti toate avantajele unui contraband este o alta alternativa pentru generarea claselor dvs. si este conceput pentru a facilita mai bine evolutia bibliotecii fara ruperi binare. (Este folosit de SBT)

DO: Adnotati tipurile de returnare a metodei in mod explicit

Versiunea Scala: toate

Incompatibilitate: Binar + Sursa

Cand tipul de returnare al unei metode este dedus de compilator, modificarea corpului continutului schimba uneori tipul de returnare dedus si astfel rupe compatibilitatea binara (semnatura diferita a metodei). Prin urmare, recomandam adnotarea in mod explicit a tipului de returnare a tuturor metodelor.

Un exemplu din biblioteca standard Scala:

In Scala 2.11 si versiunile anterioare, tipul de returnare al Optiunii # toRight este dedus ca fiind Produs cu Serializabil cu Fie [X, Int], totusi nu am reusit sa il corectam la Fie [X, Int] printr-o adnotare de tip explicit, deoarece s-ar rupe compatibilitate binara. Adnotarea de tip a fost adaugata numai in versiunea 2.12 incompatibila binara intentionat.

DONT: Adaugarea de metode cu implementare implicita la trasaturi (2.11 sau anterior)

Versiunea Scala: 2.11 sau inainte

Incompatibilitate: binara

Inainte de Java 8 (care 2.12 vizeaza), metodele de interfata nu pot avea implementari implicite. Pentru a sprijini metodele implicite pentru trasaturi, Scala 2.11 si inainte inlocuieste automat metoda pentru clasele care extind trasatura. Totusi, daca nu se efectueaza nicio recompilare a bibliotecii cu trasatura actualizata (cu noua metoda defult), nu se genereaza nicio metoda de suprascriere si se va arunca un AbstractMethodError cand se apeleaza metoda implicita.

Consultati aceasta intrebare StackOverflow pentru o explicatie mai detaliata.

DONT: Inliniat din alte biblioteci

Din Scala 2.12 note de lansare

Daca construiti o biblioteca de publicat pe Maven Central, nu ar trebui sa introduceti codul din dependente. Utilizatorii bibliotecii dvs. ar putea avea versiuni diferite ale acestor dependente de classpath, ceea ce rupe compatibilitatea binara.

Aceasta inseamna ca, atunci cand se utilizeaza -opt: l: inline, trebuie sa se aiba grija sa nu se incadreze in dependente de calea de clasa. De exemplu, -opt: l: inline -opt-inline-from: <sources> este sigur, deoarece va include numai fisiere sursa compilate in unitatea de compilare curenta, in timp ce -opt: l: inline -opt-inline-from: some .other.library. ** nu este sigur, deoarece poate include metode dintr-o biblioteca de care depindeti.

Pentru mai multe informatii, puteti rula scalac -opt: help si scalac -opt-inline-from: help