Versionado del lenguaje

Un único SDK de Dart puede admitir simultáneamente múltiples versiones del lenguaje Dart. El compilador determina a qué versión se dirige el código y lo interpreta de acuerdo con esa versión.

El control de versiones del lenguaje adquiere importancia en las raras ocasiones en las que Dart introduce una característica incompatible como null safety. Cuando Dart introduce un cambio disruptivo (breaking change), es posible que el código que antes se compilaba ya no lo haga. El control de versiones del lenguaje te permite establecer la versión del lenguaje de cada biblioteca para mantener la compatibilidad.

En el caso de null safety, los SDKs de Dart del 2.12 al 2.19 te permitían elegir actualizar tu código para usar null safety. Dart utiliza el control de versiones del lenguaje para permitir que el código que no es seguro contra nulos (non-null-safe) se ejecute junto con el código que sí lo es (null-safe). Esta decisión permitió la migración de código no seguro a seguro contra nulos. Para revisar un ejemplo de cómo una aplicación o paquete puede migrar a una nueva versión del lenguaje con una característica incompatible, consulta este artículo sobre Migración gradual a null safety para proyectos grandes de Dart (Gradual null safety migration for large Dart projects).

Cada paquete tiene una versión de lenguaje por defecto igual al límite inferior (lower bound) de la restricción de SDK en el archivo pubspec.yaml.

Por ejemplo: La siguiente entrada en un archivo pubspec.yaml indica que este paquete tiene de forma predeterminada la versión de lenguaje de Dart 2.18.

environment:
  sdk: '>=2.18.0 <3.0.0'

Para saber cómo y por qué el equipo de Dart desarrolló este método de control de versiones, consulta la especificación de control de versiones del lenguaje (language versioning specification).

Dart formatea sus versiones del lenguaje como dos números separados por un punto. Se lee como un número de versión mayor y un número de versión menor. Los números de versión menores pueden introducir cambios disruptivos (breaking changes).

Los lanzamientos de Dart pueden añadir un número de parche a una versión de lenguaje. Los parches no deberían cambiar el lenguaje a menos que sea para corregir errores. A modo de ilustración: Dart 2.18.3 sirve como la última versión del lenguaje del SDK de Dart 2.18.

Cada lanzamiento del SDK de Dart admite su propia versión del lenguaje y todas las versiones anteriores dentro del mismo número de versión mayor. Eso significa que el SDK de Dart 2.18.3 admite las versiones del lenguaje de la 2.0 a la 2.18 inclusive, pero no Dart 1.x.

Derivar la versión del lenguaje a partir de la versión del SDK implica lo siguiente:

• Cada vez que se lanza una versión menor del SDK, aparece una nueva versión del lenguaje. En la práctica, muchas de estas versiones del lenguaje funcionan de manera muy similar a las versiones anteriores y tienen una compatibilidad total entre ellas. Por ejemplo: el lenguaje Dart 2.9 funciona de manera muy similar al lenguaje Dart 2.8.

• Cuando se lanza una versión de parche (patch release) del SDK, no puede introducir nuevas características del lenguaje. Por ejemplo: el lanzamiento 2.18.3 sigue siendo la versión de lenguaje 2.18. Debe seguir siendo compatible con 2.18.2, 2.18.1 y 2.18.0.

Por defecto, cada archivo Dart de un paquete utiliza la misma versión del lenguaje. Dart identifica la versión del lenguaje por defecto como el límite inferior de la restricción de SDK especificada en el archivo pubspec.yaml. A veces, un archivo Dart puede necesitar usar una versión de lenguaje anterior. Por ejemplo, es posible que no puedas migrar todos los archivos de un paquete a null safety al mismo tiempo.

Dart admite la selección de versión de lenguaje por biblioteca. Para optar por tener una versión de lenguaje diferente a la del resto del paquete, una biblioteca de Dart (Dart library) debe incluir un comentario con el siguiente formato:

// @dart = <major>.<minor>

Por ejemplo:

// Description of what's in this file.
// @dart = 2.17
import 'dart:math';
​
// ...

La cadena @dart debe estar en un comentario // (no /// ni /*), y debe aparecer antes de cualquier código Dart en el archivo. El espacio en blanco (tabulaciones y espacios) no importa, excepto dentro de las cadenas @dart y la versión. Como muestra el ejemplo anterior, pueden aparecer otros comentarios antes del comentario @dart.

El control de versiones del lenguaje ayuda a Dart y sus herramientas a evolucionar con el tiempo. Además de los posibles cambios semánticos y sintácticos que rompan la compatibilidad, las nuevas características y los cambios en las herramientas también podrían estar limitados a una versión del lenguaje. Por ejemplo, dart format podría formatear el código Dart de manera diferente según la versión del lenguaje de la biblioteca que esté formateando.

Para encontrar qué cambios introdujo cada versión del lenguaje, puedes consultar el historial de cambios filtrable de Dart (Dart changelog). Para conocer detalles específicos sobre cada versión del lenguaje y sus características, consulta la documentación del lenguaje y la especificación del lenguaje.