Cartes sources: rapides et faciles

Le mécanisme des cartes sources est utilisé pour mapper le code source du programme aux scripts générés sur leur base. Malgré le fait que le sujet n'est pas nouveau et qu'un certain nombre d'articles ont déjà été écrits dessus (par exemple, ceci , ceci et celui-ci ), certains aspects doivent encore être clarifiés. L'article présenté est une tentative d'organiser et de systématiser tout ce qui est connu sur ce sujet sous une forme concise et accessible.



L'article Source Maps est considéré en relation avec le développement client dans l'environnement des navigateurs populaires (par exemple, DevTools Google Chrome), bien que leur portée ne soit liée à aucun langage ou environnement particulier. La principale source de Source Maps est, bien sûr, la norme , bien qu'elle n'ait pas encore été adoptée (statut - proposition), mais toujours largement supportée par les navigateurs.



Le travail sur les cartes sources a commencé à la fin des années 2000, la première version a été créée pour le plugin Firebug Closure Inspector. La deuxième version a été publiée en 2010 et contenait des changements en termes de réduction de la taille du fichier de carte. La troisième version a été développée dans le cadre d'une collaboration entre Google et Mozilla et proposée en 2011 (dernière révision en 2013).



Actuellement, il existe une situation dans l'environnement de développement client où le code source n'est presque jamais intégré directement dans la page Web, mais il passe par différentes étapes de traitement: minification, optimisation, concaténation, de plus, le code source lui-même peut être écrit dans des langues nécessitant une traduction . Dans ce cas, à des fins de débogage, vous avez besoin d'un mécanisme qui vous permet d'observer exactement dans le débogueur le code source lisible par l'homme.



Les cartes source nécessitent les fichiers suivants:

• le fichier JavaScript réellement généré
• l'ensemble des fichiers source utilisés pour le créer
• fichier de mappage qui les mappe les uns aux autres

Fichier de carte

L'ensemble du travail de Source Maps est basé sur un fichier de carte, qui peut ressembler à ceci:

{
    "version":3,
    "file":"index.js",
    "sourceRoot":"",
    "sources":["../src/index.ts"],
    "names":[],
    "mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,SAAS,SAAS;IACd,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;",
    "sourcesContent": []
}

Habituellement, le nom du fichier de mappage est la somme du nom du script auquel il appartient, avec l'ajout de l'extension ".map", bundle.js - bundle.js.map. Il s'agit d'un fichier json standard avec les champs suivants:

• "Version" - version des cartes sources;
• "Fichier" - (facultatif) le nom du fichier généré auquel appartient le fichier cartographique actuel;
• "SourceRoot" - préfixe (facultatif) pour les chemins vers les fichiers source;
• "Sources" - une liste de chemins d'accès aux fichiers source (résolus de la même manière que les adresses src de la balise de script, vous pouvez utiliser file: //.);
• «Noms» - une liste de noms de variables et de fonctions qui ont subi une modification dans le fichier généré;
• "Mappings" - coordonnées des variables de mappage et des fonctions des fichiers source vers un fichier généré au format Base64 VLQ;
• "SourcesContent" - (facultatif) dans le cas d'un fichier de carte autonome, une liste de lignes, chacune contenant le texte source du fichier provenant des sources;

Télécharger les cartes sources

Pour que le navigateur charge le fichier de carte, l'une des méthodes suivantes peut être utilisée:

• Le fichier JavaScript est fourni avec un en-tête HTTP: SourceMap: <url> (auparavant obsolète, X-SourceMap: <url> était précédemment utilisé)
• le fichier JavaScript généré a un commentaire spécial de la forme:

//# sourceMappingURL=<url> ( CSS /*# sourceMappingURL=<url> */)

Ainsi, en téléchargeant le fichier de carte, le navigateur extraira les sources du champ «sources» et, en utilisant les données du champ «mappings», les affichera sur le script généré. Dans l'onglet Sources DevTools, vous pouvez trouver les deux options.



Le fichier: // pseudoprotocol peut être utilisé pour spécifier le chemin. De plus, le contenu du fichier de carte encodé en base64 peut être inclus dans <url>. Dans la terminologie Webpack, les cartes source comme celles-ci sont appelées cartes source en ligne.

//# sourceMappingURL=data:application/json;charset=utf-8;base64,<source maps Base64 code>

Fichiers de carte autonomes

Le code des fichiers source peut être inclus directement dans le fichier de la carte dans le champ "sourcesContent", si ce champ est présent, il n'est pas nécessaire de les télécharger séparément. Dans ce cas, les noms des fichiers dans "sources" ne reflètent pas leur adresse réelle et peuvent être complètement arbitraires. C'est pourquoi, dans l'onglet Sources des DevTools, vous pouvez voir ces étranges "protocoles": webpack: //, ng: //, etc.

Mappings

L'essence du mécanisme de mappage est que les coordonnées (ligne / colonne) des noms des variables et des fonctions dans le fichier généré sont mappées aux coordonnées dans le fichier de code source correspondant. Pour que le mécanisme d'affichage fonctionne, les informations suivantes sont requises:



(# 1) numéro de ligne dans le fichier généré;

(# 2) numéro de colonne dans le fichier généré;

(# 3) index de la source dans "sources";

(# 4) numéro de ligne source;

(# 5) numéro de colonne source;



Toutes ces données se trouvent dans le champ «mappings», dont la valeur est une longue chaîne avec une structure spéciale et des valeurs encodées en Base64 VLQ.



La ligne est séparée par des points-virgules (;) en sections correspondant aux lignes du fichier généré (# 1).



Chaque section est séparée par des virgules (,) en segments, chacun pouvant contenir 1,4 ou 5 valeurs:

• le numéro de colonne dans le fichier généré (# 2);
• index des sources dans "sources" (# 3);
• numéro de ligne source (# 4);
• numéro de colonne source (# 5);
• index du nom de variable / fonction de la liste des noms;

Les valeurs des numéros de ligne et de colonne sont relatives, indiquent le décalage par rapport aux coordonnées précédentes et uniquement le premier à partir du début du fichier ou de la section.



Chaque valeur est un numéro VLQ Base64. VLQ (Variable-length Quantity) est un principe de codage d'un nombre arbitrairement grand en utilisant un nombre arbitraire de blocs binaires de longueur fixe.



Les cartes sources utilisent des blocs de six bits, qui sont classés de bas en haut. Le 6e bit le plus élevé de chaque bloc (bit de continuation) est réservé, s'il est défini, le bloc actuel est suivi du bloc suivant du même numéro, s'il est réinitialisé, la séquence est terminée.



Étant donné que la valeur doit avoir un signe dans les cartes sources, le bit le moins significatif (bit de signe) lui est également réservé, mais uniquement dans le premier bloc de la séquence. Comme prévu, le bit de signe défini signifie un nombre négatif.



Ainsi, si un nombre peut être codé avec un seul bloc, il ne peut pas être modulo 15 (1111 ₂ ), car dans le premier bloc de six bits de la séquence deux bits sont réservés: le bit de continuation sera toujours effacé, le bit de signe sera mis à 1 en fonction du signe du nombre.



Les blocs VLQ à six bits sont mappés au codage Base64, où chaque séquence à six bits est mappée à un caractère ASCII spécifique.







Nous décodons le nombre mE. Inversez l'ordre, la dernière partie est Em. Nous décodons les nombres de Base64: E - 000100, m - 100110. Dans le premier, nous supprimons le bit de continuation élevé et deux zéros de tête - 100. Dans le second, nous supprimons les bits de continuation élevée et de faible signe (le bit de signe est effacé - le nombre est positif) - 0011. Par conséquent, nous obtenons 100 0011 ₂ , qui correspond au décimal 67.



Il est possible dans le sens opposé, encoder 41. Son code binaire est 101001 ₂, nous avons divisé en deux blocs: la partie haute - 10, la partie basse (toujours 4 bits) - 1001. À la partie haute, nous ajoutons le bit de continuation d'ordre supérieur (effacé) et trois zéros non significatifs - 000010. À la partie basse, nous ajoutons le bit de continuation d'ordre supérieur (ensemble) et le bit de signe le moins significatif (effacé - le nombre est positif) - 110010. Nous codons les nombres en Base64: 000010 - C, 110010 - y. Nous inversons l'ordre et, par conséquent, nous obtenons yC.



La bibliothèque du même nom est très utile pour travailler avec VLQ .