Skrypty kompilacji Blockly

Blockly składa się z ponad setki plików TypeScript. Przed użyciem muszą zostać skompilowane przez kompilator TypeScript (tsc) do kodu JavaScript. W ten sposób tworzona jest równie duża liczba plików .js, które nadają się do testów lokalnych, ale ładowanie tak dużej liczby plików przez internet jest powolne dla użytkowników. Aby przyspieszyć wczytywanie Blockly, kompilator Closure służy do kompresji (zmniejszenia) kodu i połączenia go w kilka plików („pakietów” lub „fragmentów”), których łączny rozmiar jest mniejszy niż połowa rozmiaru nieskompresowanych plików.

W ramach 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ększymi przeglądarkami. Dlatego ważne jest, aby użytkownicy końcowi otrzymywali tylko zoptymalizowany kod.

Repozytorium google/blockly zawiera tylko kod źródłowy. Wcześniej zawierała ona również produkty kompilacji, ale od 2019 r. zminiaturyzowane pakiety są publikowane jako pakiet NPM blockly, a od 2022 r. są też dołączane jako plik .tgz do każdej wersji na GitHubie. Nie musisz więc kompilować Blockly, chyba że chcesz wprowadzić zmiany w samej tej usłudze, w szczególności w plikach w katalogach core, blocks, generators lub msg.

Proces tworzenia, testowania i publikowania aplikacji Blockly jest zautomatyzowany za pomocą skryptów npm do uruchamiania zadań Gulp. Na tej stronie znajdziesz opis skryptów zasad i ich działanie.

Tryb skompresowany i nieskompresowany

Ładowanie Blockly bezpośrednio z pojedynczych plików .js wygenerowanych przez kompilator TypeScript nazywa się „trybem bez kompresji”. Umożliwia to szybkie edytowanie, kompilowanie i uruchamianie. Ułatwia też debugowanie, ponieważ wykonywany kod JavaScript jest prawie tak czytelny jak oryginalne źródła TypeScript, co eliminuje konieczność korzystania z map źródeł.

Ładowanie Blockly ze zminifikowanych pakietów jest nazywane „trybem skompresowanym”. To najlepszy sposób na przetestowanie zmian w Blockly, gdy jest używany jako zależność innego pakietu, ponieważ testuje (nieopublikowaną wersję) pakiet blocklynpm.

N.B.: W niektórych miejscach w repozytorium blockly terminy „tryb nieskompilowany” i „tryb skompilowany” są używane jako synonimy odpowiednio „trybu nieskompresowanego” i „trybu skompresowanego”. Wcześniej takie użycie było uzasadnione, ponieważ kompilator Closure służył do kompresji (zmniejszenia) kodu, ale teraz kompilator TypeScript jest zawsze potrzebny, nawet w trybie niezakompresowanym, więc ta alternatywna terminologia może być myląca i nie zalecamy jej używania.

Szybki start

Jeśli wprowadzisz zmiany lokalne i chcesz się upewnić, że nie zepsuły one kompilacji ani testów, uruchom
```
npm test
```
do kompilowania Blockly i uruchamiania zestawu testów.
Jeśli chcesz przetestować zmiany lokalne w przeglądarce, uruchom:
```
npm start
```
Spowoduje to skompilowanie Blockly i otwarcie przeglądarki z podświetlonym obszarem Blockly, w której działa Blockly w trybie nieskompresowanym.

Zmodyfikowane pliki w folderach core/, blocks/ i generators/ są automatycznie kompilowane. Aby zobaczyć zmiany, odśwież kartę przeglądarki.
Aby skompilować zmodyfikowaną lokalnie wersję Blockly i przetestować ją w trybie skompresowanym jako zależność innego pakietu npm, uruchom
```
npm run package
```
aby utworzyć pakiet Blockly, a następnie
```
cd dist && npm link
```
aby wskazać npm, gdzie znajdują się skompilowane pliki, a następnie cd do katalogu projektu przed uruchomieniem.
```
npm link blockly
```
aby Twój pakiet używał najnowszej wersji Blockly zamiast opublikowanego pakietu blockly.

Szczegółowe odniesienie do skryptu

W tej sekcji wymieniono zasady scripts w pliku package.json w Blockly wraz z wyjaśnieniem, do czego służą.

Skrypty te 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 ścieżki kompilacji.
Pliki w podkatalogu dist/ stanowią zawartość opublikowanego pakietu npm.

Żaden z tych katalogów nie jest śledzony w repozytorium git blockly.

`clean`

npm run clean czyści wszystkie wcześniejsze kompilacje, usuwając katalogi build/ i dist/. Przydatne do naprawiania niejasnych błędów kompilacji, zwłaszcza tych spowodowanych zmianą nazwy pliku źródłowego.

`messages`

npm run messages aktualizuje pliki wiadomości w msg/json/ o wszystkie zmiany wprowadzone w pliku msg/messages.js. Należy go uruchamiać po każdej zmianie w tym pliku.

`langfiles`

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

`tsc`

npm run tsc uruchamia kompilator TypeScript na zawartości katalogów core/, blocks/ i generators/ oraz wyprowadza poszczególne pliki .js do katalogu build/src/.

`minify`

npm run minify uruchamia closure-make-deps i closure-calculate-chunks, aby określić sposób podziału skompilowanych plików .js na fragmenty (zminiaturyzowane pakiety), a następnie uruchamia closure-compiler, aby utworzyć te fragmenty w ten sposób:

Treści z build/src/core/ stają się dist/blockly_compressed.js.
Treści z build/src/blocks/ stają się dist/blocs_compressed.js.
Treści z poziomu build/src/generators/javascript/ (oraz build/src/generators/javascript.js) stają się elementem dist/javascript_compressed.js.
To samo dotyczy błędów dart, lua, php i python.

Wygenerowane chuks używają oprawy, aby zapewnić zgodność z uniwersalną definicją modułu, więc nie trzeba ich dodatkowo przetwarzać, zanim zostaną uwzględnione w pakiecie.

`build`

npm run build uruchamia zadania minify i langfiles. To powinno wystarczyć do załadowania Playgroundu Blockly w trybie skompresowanym lub nieskompresowanym.

`package`

npm run package wykonuje zadania clean i build, a potem:

Zastosowanie opakowania UMD do plików w build/msg/ i umieszczenie zapakowanych wersji w dist/msg/.
Dodaje do dist/ różne dodatkowe pliki pomocnicze, w stosownych przypadkach z opakowaniami UMD.

`publish`

npm run publish jest używany przez zespół Blockly do publikowania pakietu blockly npm. Jest ona zależna od wewnętrznej infrastruktury Google, więc nie jest przydatna dla zewnętrznych deweloperów.

`lint`

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

`test`

npm test (lub npm run test) wykonuje zadanie package, a następnie różne testy automatyczne (w tym ESLint). Test powinien być wykonywany i powinien się powieść w przypadku każdego kodu przesłanego jako prośba o przeniesienie do repozytorium Blockly.