Skrypty kompilacji Blockly

Blockly składa się z ponad 100 plików TypeScriptu. Przed użyciem muszą one zostać skompilowane przez kompilator TypeScript (tsc) do kodu JavaScript. W ten sposób powstaje równie duża liczba plików .js, które nadają się do testów lokalnych, ale wczytywanie tak dużej liczby plików przez internet spowalnia pracę użytkowników. Aby przyspieszyć ładowanie Blockly, kompilator Closure Compiler skompresuje (minimalizuje) i połączy je w pół tuzina plików („pakietów” lub „fragmentów”) o łącznym rozmiarze mniejszym o połowę w przypadku plików nieskompresowanych.

W trakcie tego procesu kod korzystający z najnowszych funkcji ECMAScript, które mogą nie być zgodne ze wszystkimi przeglądarkami, jest transpilowany do wersji ES6, która jest ogólnie zgodna z większością używanych przeglądarek. Dlatego ważne jest, aby udostępniać użytkownikom tylko zminimalizowany kod.

Repozytorium google/blockly zawiera tylko kod źródłowy. Wcześniej zawierał on również usługi kompilacji, ale od 2019 roku zminimalizowane pakiety były publikowane jako pakiet blockly NPM, a od 2022 r. także dołączane jako plik .tgz do każdej wersji na GitHubie, więc nie musisz kompilować Blockly, chyba że hakujesz sam Blockly – w szczególności pliki w katalogach core, blocks, generators i msg.

Proces kompilowania, testowania i publikowania Blockly jest zautomatyzowany za pomocą skryptów npm do uruchamiania zadań Gulp. Na tej stronie opisujemy skrypty i działanie każdego z nich.

Tryb skompresowany i nieskompresowany

Wczytywanie Blockly bezpośrednio z poszczególnych plików .js wygenerowanych przez kompilator TypeScript jest nazywane „trybem nieskompresowanym”. Pozwala to uniknąć kilku powolnych kroków kompilacji, co przyspiesza cykl edycji, kompilowania i uruchamiania. Ułatwia to również debugowanie, ponieważ wykonywany kod JavaScript jest niemal tak samo czytelny jak oryginalne źródła TypeScript, co eliminuje potrzebę zależności od map źródłowych.

Wczytywanie Blockly ze zminifikowanych pakietów jest nazywane „trybem skompresowanym”. To najlepszy sposób na przetestowanie zmian w funkcji Blockly, gdy jest ona stosowana jako zależność innego pakietu, ponieważ testuje (nieopublikowaną wersję) pakietu npm blockly.

N.B.: W repozytorium blokowym są miejsca, w których terminy „tryb nieskompilowany” i „tryb skompilowany” są używane jako synonimy odpowiednio „tryb nieskompresowany” i „tryb skompresowany”. W przeszłości takie podejście miało sens, ponieważ do skompresowania (minimalizowania) kodu używano narzędzia Closure Compiler. Obecnie jednak kompilator TypeScript jest potrzebny zawsze, nawet w trybie nieskompresowanym, więc taka alternatywna terminologia może być myląca i odradzana.

Szybki start

  • Jeśli po wprowadzeniu zmian lokalnych chcesz sprawdzić, czy nie spowodowały uszkodzenia kompilacji ani testów,

    npm test

    do skompilowania Blockly i uruchomienia pakietu testowego.

  • Jeśli chcesz przetestować zmiany lokalne w przeglądarce, uruchom polecenie

    npm start

    Spowoduje to skompilowanie Blockly i otworzenie przeglądarki wskazującej Blockly playground, która uruchamia Blockly w trybie nieskompresowanym.

    Wszystkie zmodyfikowane pliki w core/, blocks/ i generators/ są automatycznie kompilowane ponownie. Aby zobaczyć zmiany, załaduj ponownie kartę przeglądarki.

  • Aby skompilować lokalnie zmodyfikowaną wersję Blockly i przetestować ją w trybie skompresowanym jako zależność innego pakietu npm, uruchom polecenie

    npm run package

    aby utworzyć pakiet Blockly, a następnie

    cd dist && npm link

    aby poinformować npm, gdzie znaleźć skompilowane pliki, a następnie cd do katalogu projektu, zanim uruchomisz

    npm link blockly

    aby Twój pakiet używał niedawno skompilowanej wersji Blockly w miejsce opublikowanego pakietu blockly.

Szczegółowe informacje o skrypcie

W tej sekcji wymieniono zasadę scripts w pliku package.json firmy Blockly i objaśniono jej działanie.

Te skrypty generują pliki w 2 miejscach:

  • Pliki w podkatalogu build/ to pliki pośrednie używane do testowania lokalnego lub przetwarzane przez późniejsze części potoku kompilacji.
  • Pliki w podkatalogu dist/ stanowią zawartość opublikowanego pakietu npm.

Żaden katalog nie jest śledzony w repozytorium bloku git.

clean

npm run clean czyści wszystkie wcześniejsze kompilacje przez usunięcie katalogów build/ i dist/. Przydaje się do naprawiania błędów kompilacji, w szczególności tych spowodowanych zmianą nazwy pliku źródłowego.

messages

Narzędzie npm run messages aktualizuje pliki wiadomości w pliku msg/json/ o wszelkie zmiany, które zostały wprowadzone w komponencie msg/messages.js. Musi być ona uruchamiana po każdej modyfikacji pliku.

langfiles

npm run langfiles generuje skompilowane pliki językowe w build/msg/ z plików wiadomości w pliku msg/json.

tsc

npm run tsc uruchamia kompilator TypeScript na zawartości katalogów core/, blocks/ i generators/, a pojedyncze pliki .js kieruje do pliku build/src/.

minify

npm run minify uruchamia closure-make-deps i closure-calculate-chunks, aby określić, jak podzielić skompilowane pliki .js na fragmenty (zmniejszone pakiety), a potem uruchamia polecenie closure-compiler, aby utworzyć fragmenty w ten sposób:

  • Zawartość pola build/src/core/ zmieni się na dist/blockly_compressed.js.
  • Zawartość pola build/src/blocks/ zmieni się na dist/blocs_compressed.js.
  • Zawartość pola build/src/generators/javascript/ (plus build/src/generators/javascript.js) zmieni się na dist/javascript_compressed.js.
  • I podobnie dla: dart, lua, php i python.

Wygenerowane kody chuks wykorzystują kod, który zapewnia zgodność z definicją modułu uniwersalnego, dzięki czemu nie jest wymagane dodatkowe przetwarzanie przed umieszczeniem ich w pakiecie.

build

npm run build uruchamia zadania minify i langfiles. Powinno to zadziałać wszystko, co jest potrzebne do wczytania obszaru roboczego Blockly w trybie skompresowanym lub nieskompresowanym.

package

npm run package uruchamia zadania clean i build, a następnie:

  • Stosuje opakowanie UMD do plików w komponencie build/msg/, umieszczając wersje opakowane w elemencie dist/msg/.
  • Dodaje do dist/ różne dodatkowe pliki pomocy z kodami UMD, jeśli są potrzebne.

publish

Parametr npm run publish jest używany przez zespół Blockly do opublikowania pakietu npm blockly. Zależy on od wewnętrznej infrastruktury Google, więc nie jest przydatny dla zewnętrznych programistów.

lint

npm run lint uruchamia ESLint, wykonując statyczną analizę kodu źródłowego Blockly w poszukiwaniu problemów.

test

npm test (lub npm run test) uruchamia zadanie package, a następnie przeprowadza różne testy automatyczne (w tym uruchomienie ESLint). Należy go uruchomić i przekazać na każdym kodzie przesłanym w ramach żądania pull do repozytorium zablokowanych.