Einen Generator für Wrapper nativer Bibliotheken in vielen Sprachen korrigieren und testen

## Zuerst die Aufgabenleitfäden lesen und Eingaben statt erzeugter Dateien korrigieren ### Beginne mit aufgabenspezifischen Hinweisen Suche vor Codeänderungen oder besonderen Befehlen nach den kurzen, aufgabenspezifischen Leitfäden des Projekts. Lies den zur Arbeit passenden Leitfaden, statt Verfahren aus einer breiten Übersicht neu zusammenzusetzen. Typische Leitfäden behandeln: - die Ausführung der vollständigen Testsammlung, der Tests für eine Zielsprache oder eines einzelnen Testfalls; - die Fehlersuche im Compiler, die Untersuchung von Syntaxbäumen und die Verfolgung von Speicherfehlern; - die Bearbeitung des Benutzerhandbuchs und die Prüfung seiner Struktur; - Quelltextformatierung, Kommentare, Beitragsregeln und Texte für Änderungseinträge; - die Nachstellung von Fehlern, die nur in der kontinuierlichen Integration auftreten. Behandle diese gezielten Leitfäden als maßgeblich, wenn sie genaue Befehle, Optionen oder Regeln nennen. Wenn Suchaliase oder symbolische Verknüpfungen denselben Leitfaden an mehreren werkzeugspezifischen Stellen spiegeln, pflege nur eine maßgebliche Quelle und prüfe, dass die Verknüpfungen auf der Plattform der mitwirkenden Person richtig angelegt werden. ### Verstehe das System vor der Bearbeitung Der Quellcodebestand enthält einen compilerartigen Generator. Er liest native Deklarationen und Schnittstellenbeschreibungen und erzeugt anschließend Bindeschichten, über die viele Zielsprachen auf native Bibliotheken zugreifen können. Dieses Modell hat drei praktische Folgen: - erzeugte Dateien sind Ergebnisse und nicht die primäre Stelle zur Behebung eines Verhaltens; - gemeinsam genutzte Schnittstelleneingaben sollen sprachübergreifendes Verhalten enthalten, während ziellaufzeitspezifische Prüfungen in das zugehörige Testverzeichnis der Zielsprache gehören; - Änderungen an Syntaxanalyse, Typauflösung, Eigentümerschaft oder Erzeugung der Bindeschicht können viele Zielsprachenmodule betreffen, auch wenn das gemeldete Anzeichen nur bei einem davon auftritt. Nutze die projektinternen Leitfäden, Erstellungsdateien und Tests als Belege. Leite einen Arbeitsablauf nicht allein aus vertraut wirkenden Verzeichnisnamen oder aus den Regeln eines anderen Projekts ab. ## Mit dem Buildsystem der CI bauen und den kleinsten sinnvollen Test wählen ### Erstelle aus der richtigen Quellform Verwende das primäre Erstellungssystem der kontinuierlichen Integration. Eine aus der Versionsverwaltung bezogene Arbeitskopie kann einen Initialisierungsschritt zum Erzeugen von Konfigurationsdateien benötigen, während ein Veröffentlichungsarchiv sie bereits enthalten kann. Die übliche Reihenfolge lautet bei Bedarf initialisieren, danach konfigurieren und anschließend erstellen. Erhalte unterstützte Konfigurationsschalter wie das Installationspräfix und die Steuerung optionaler Abhängigkeiten. Ein zweites Erstellungssystem kann vorhanden sein, doch ersetze beim Untersuchen eines Fehlers der primären Verarbeitungskette nicht stillschweigend das erste System damit. Tests und Beispiele können ein Startskript für den nicht installierten Arbeitsbaum aufrufen, das die Laufzeit auf das soeben erstellte Bibliotheksverzeichnis verweist. Nutze dieses Startskript, damit die Tests die aktuelle Arbeitskopie statt einer installierten Fassung prüfen. Gehört ein zusätzlicher Compilerzwischenspeicher zum voreingestellten Erstellungs- und Prüfgraphen, beziehe ihn ein, sofern der maßgebliche Leitfaden die Ausführung nicht ausdrücklich einschränkt. ### Wähle den kleinsten aussagekräftigen Test Passe den Befehl an den Änderungsumfang an: - Führe während der wiederholten Prüfung eines örtlich begrenzten Verhaltens einen einzelnen Test der erzeugten Bindeschicht aus. - Führe bei verändertem Verhalten eines Zielsprachenmoduls die vollständige Testsammlung der betroffenen Zielsprache aus. - Führe gemeinsame Testsammlungen aus, wenn sich Syntaxanalysator, Typsystem, Eigentümerschaft oder gemeinsame Erzeugungslogik ändern. - Nutze parallele Ausführung nur, wenn das Projekt sie unterstützt. - Nutze bei breiten Prüfungen einen Weiterlaufmodus, wenn die Erfassung aller Fehler nützlicher ist als ein Abbruch beim ersten Fehler. Prüfziele bilden häufig die Quellform ab, etwa den Modus der nativen Sprache, den objektorientierten Modus oder den Mehrmodulmodus. Verwende die zum Fall passende Endung und führe das zugehörige Bereinigungsziel aus, bevor du ein veraltetes erzeugtes Artefakt für einen neuen Fehler hältst. ### Prüfe denselben Weg wie die Automatisierung Wenn ein Fehler nur in der kontinuierlichen Integration auftritt, stelle die Ausführungsumgebung mit dem gepflegten Containerabbild und den tatsächlichen Installationsskripten des Projekts nach. Bevorzuge die Hilfsfunktion, welche die gehostete Ausführungsumgebung nachbildet, gegenüber einer improvisierten Umgebung. Prüfe übereinstimmende Abhängigkeitsversionen, Umgebungsvariablen, Erstellungsarten und Prüfziele, bevor du den Unterschied dem Quelltext zuschreibst. Eine Fehlerbehebung oder Funktion soll normalerweise einen Regressionstest enthalten. Behaupte nicht, eine Änderung sei geprüft, nur weil der Compiler erfolgreich erstellt wurde. Die Erzeugung der Bindeschicht, die Übersetzung des erzeugten Codes und das Laufzeitverhalten in der Zielsprache sind getrennte Prüfpunkte. ## Die Verarbeitungsstufe finden, in der ein Fehler beginnt, und den Parser nie verschachtelt aufrufen ### Folge den Verarbeitungsschritten Verfolge das Verhalten der Verarbeitungskette in dieser Reihenfolge: 1. Der Präprozessor erweitert Schnittstelleneingaben und bedingte Anweisungen. 2. Der Lexer wandelt den Eingabetext in lexikalische Einheiten um. 3. Der Syntaxanalysator wendet die Grammatik an und erzeugt einen Baum aus attributtragenden Knoten. 4. Das Typsystem löst Namen, Gleichwertigkeiten, Vorlagen und Umwandlungen auf. 5. Baumdurchläufe ergänzen oder vereinheitlichen Informationen für spätere Schritte. 6. Ein Zielsprachenmodul durchläuft den Baum und erzeugt den Code der Bindeschicht. Finde den frühesten Schritt, an dem der tatsächliche vom erwarteten Zustand abweicht. Eine fehlerhafte Bindeschicht beweist nicht, dass das Zielsprachenmodul die Ursache ist. Es kann lediglich einen zuvor erzeugten falschen Syntaxknoten, Typ, Eigentumsmerker oder eine falsche Umwandlungsregel getreu umsetzen. ### Nutze die zentralen Abstraktionen des Modells Syntaxknoten verhalten sich wie Schlüssel-Wert-Objekte und werden von gemeinsamen Baumdurchläufen und Zielsprachenmodulen durchlaufen. Untersuche Attribute sowohl bei ihrer Erzeugung als auch bei ihrer späteren Verwendung. Typumwandlungstabellen steuern, wie native Werte die Grenze zu Werten der Zielsprache überschreiten. Prüfe bei falschem Umwandlungsverhalten die Auswahlrangfolge und Typgleichwertigkeit, bevor du den erzeugten Text änderst. Die Vorlageninstanziierung beruht auf demselben Verfahren zur Typgleichwertigkeit. Trenne daher die Zuordnung von Spezialisierungen von der Formatierung der Bindeschicht. Untersuche die gemeinsame Eigentums- und Speicherzuweisungsanalyse, bevor du zielsprachenmodulspezifische Umgehungen für die Lebensdauer hinzufügst. ### Beachte die Grenzen eines nicht wiedereintrittsfähigen Syntaxanalysators Gehe davon aus, dass der Syntaxanalysator nicht wiedereintrittsfähig ist, sofern die Implementierung nicht das Gegenteil belegt. Einstiegspunkte, die ihn umschließen, können den globalen Analysatorzustand überschreiben, darunter die aktuelle Eingabeposition, semantische Werte und die Vorausschau. Rufe diese Einstiegspunkte niemals rekursiv innerhalb einer Grammatikaktion auf. Muss eine Grammatikregel eine neue Parameterliste oder verwandte Teilsyntax erzeugen, verwende innerhalb der laufenden Analyse bestehende Grammatikproduktionen, statt eine verschachtelte Analyse zu starten. Prüfe die Änderung mit einem Regressionstest für den ältesten Sprachstandard, der das Grammatikmerkmal eingeführt hat. ### Verwende unterstützte Fehlersuchhilfen Nutze die dokumentierten Fehlersuchoptionen des Projekts, textuelle oder strukturierte Baumdarstellungen, Hilfen des Fehlersuchprogramms, Ausführungsumhüllungen, Variablen zur Funktionsauswahl und Diagnosen des Speicherpools. Stelle bei einem reinen Automatisierungsfehler zuerst die Automatisierungsumgebung nach, bevor du die Instrumentierung ausweitest. Halte Diagnoseänderungen vorläufig und mache eine lokale Umgehung nicht ohne einen fehlschlagenden Test, der ihre Notwendigkeit belegt, zum Produktionsverhalten. ## Jeden Regressionstest in die gemeinsame Eingabe oder das Sprachskript legen ### Ordne Verhalten der richtigen Schicht zu Ein Test besitzt gewöhnlich eine gemeinsame Schnittstelleneingabe, welche die Erzeugung steuert, und gegebenenfalls ein Laufzeitskript der Zielsprache, das die erzeugte Bindeschicht ausführt. Lege sprachunabhängige Grammatik- und Bindeschichtanforderungen in der gemeinsamen Eingabe ab. Lege Syntax der Zielsprache, Laufzeitprüfungen und sprachspezifische Grenzfälle im zugehörigen Laufzeitskript ab. Registriere neue Fälle in der Testgruppe, die ihrem tatsächlichen Umfang entspricht. Ein an einen Sprachstandard gebundener Präfix des Testnamens muss den ältesten Standard darstellen, der das Grammatikmerkmal eingeführt hat, und nicht einen neueren Standard eines bequemen Beispiels. Bestimme das Merkmal isoliert und ordne den Test danach der passenden Standardgruppe zu. ### Mache Fehler beobachtbar Verwende Prüfhelfer, die auch in optimierten Laufzeitarten aktiv bleiben. Kann eine Zielsprache ihre eingebaute Prüfanweisung während der Optimierung ausblenden, darf die Regressionsabdeckung niemals von dieser Anweisung abhängen. Nutze ausdrückliche Helfer für Gleichheit, Bedingungen und erwartete Ausnahmen, die bei einem Fehler nützliche Werte melden. Halte Testkommentare kurz und beschränke sie auf nicht offensichtliche Informationen. Erläutere eine Compilerumgehung oder eine semantische Falle in einer knappen Zeile und wiederhole nicht, was der Code bereits ausdrückt. Ein Regressionstest soll vor der Korrektur fehlschlagen, danach bestehen und das öffentlich nutzbare Verhalten statt einer zufälligen internen Hilfsfunktion prüfen. ### Prüfe gemeinsame Auswirkungen Teste bei Änderungen am Syntaxanalysator oder gemeinsamen Typsystem mehr als das ursprünglich fehlschlagende Zielsprachenmodul, wenn der betroffene Pfad gemeinsam genutzt wird. Weite bei rein zielsprachenmodulspezifischem Verhalten die Ausführung nicht ohne Beleg aus. Bereinige erzeugte Dateien zwischen wesentlich verschiedenen Prüfkonfigurationen und unterscheide im Bericht zwischen Erzeugungsfehlern, Fehlern der nativen Übersetzung und Laufzeitfehlern. ## Keine fremden Änderungen in Commits mischen und sichtbare Änderungen im Änderungsprotokoll festhalten ### Befolge die Regeln für Quelltext und Kommentare Nutze die Formatprüfungen und das Formatierungswerkzeug des Projekts, statt unbeteiligten Code von Hand zu vereinheitlichen. Halte den vorhandenen Kommentarstil der nativen Sprache, die Zitierweise lexikalischer Einheiten, die Zeilenbreite und die Regeln für Funktionsköpfe ein. Grammatikdateien können strengere Regeln für neuen Code vorgeben. Befolge sie und vermeide beim Ändern eines produktiven Syntaxanalysators sachfremde Umstrukturierungen. Prüfe vor einem Änderungseintrag den Unterschied auf erzeugte Dateien, versehentliche breite Ersetzungen und Änderungen außerhalb des vorgesehenen Teilsystems. Der Eintragstext muss klar, knapp und richtig sein. Nenne ein Automatisierungswerkzeug nicht als mitwirkende Urheberschaft. Verlangt das Projekt die Offenlegung wesentlicher automatisierter Hilfe, nutze den freigegebenen Hilfezusatz ohne E-Mail-Identität. ### Halte für Nutzende sichtbare Änderungen fest Jede für Nutzende sichtbare Fehlerbehebung, Funktion, Verhaltensänderung, Warnungsänderung oder Kennzeichnung als veraltet muss einen Eintrag im aktuellen Änderungsprotokoll erhalten. Beschreibe, was Nutzende beobachten, nicht die Namen interner Hilfsfunktionen oder Einzelheiten der Umstrukturierung. Befolge das festgelegte Datums- und Vorgangsformat, ordne neue Einträge wie vorgesehen ein und kennzeichne Kompatibilitätsrisiken ausdrücklich. Rein interne Änderungen ohne beobachtbare Wirkung benötigen keinen Eintrag für Nutzende. ### Pflege Dokumentation für Entwicklung und Nutzung Erhalte beim Bearbeiten des Handbuchs stabile, beschreibende Überschriftenanker statt erzeugter Zahlenanker. Verwende die dokumentierten Inhaltsklassen für Code, Beispiele der Zielsprache, Kommandozeilensitzungen und Diagramme. Verankere dokumentübergreifende Verknüpfungen an stabilen Zielen und führe anschließend die Erzeugung des Inhaltsverzeichnisses sowie die Dokumentationsprüfungen aus. Die Entwicklungsdokumentation soll das interne Objektmodell, Baumattribute, Typsystem und den Erweiterungspfad erklären. Die Benutzerdokumentation soll sich auf unterstützte Syntax und beobachtbares Verhalten konzentrieren. Prüfe sowohl die dargestellte Struktur als auch die Verknüpfungsziele. Eine erfolgreiche Quelltextänderung allein beweist nicht, dass das Handbuch weiterhin gut navigierbar ist.