Skrip Build Blockly

Blockly terdiri dari lebih dari seratus file TypeScript. Library ini harus dikompilasi oleh compiler TypeScript, tsc, ke dalam JavaScript agar dapat digunakan. Tindakan ini akan menghasilkan jumlah file .js yang sama besarnya yang cocok untuk pengujian lokal, tetapi memuat file dalam jumlah besar melalui internet akan membuat pengguna akhir merasa lambat. Untuk mempercepat pemuatan Blockly, Closure Compiler digunakan untuk mengompresi (minifikasi) dan menggabungkannya menjadi setengah lusin file ("paket" atau "bagian") dengan ukuran total kurang dari setengah dari ukuran file yang tidak dikompresi.

Dalam prosesnya, kode yang menggunakan fitur ECMAScript terbaru—yang mungkin tidak kompatibel dengan semua browser—akan ditranspilasi menjadi ES6, yang umumnya kompatibel dengan browser yang paling banyak digunakan. Oleh karena itu, Anda harus menayangkan kode yang diminifikasi saja kepada pengguna akhir Anda.

Repositori google/blockly hanya berisi kode sumber. Sebelumnya juga berisi produk build, tetapi sejak 2019, paket yang diminifikasi telah dipublikasikan sebagai paket NPM blockly dan sejak 2022 juga dilampirkan sebagai file .tgz ke setiap rilis GitHub, sehingga tidak perlu mem-build Blockly kecuali jika Anda meretas Blockly sendiri—khususnya pada file di direktori core, blocks, generators, atau msg.

Proses pembuatan, pengujian, dan publikasi Blockly diotomatiskan menggunakan skrip npm untuk menjalankan tugas Gulp. Halaman ini mendokumentasikan skrip-skrip utama dan fungsinya masing-masing.

Mode Terkompresi dan Tidak Dikompresi

Pemuatan Blockly langsung dari setiap file .js yang dihasilkan oleh compiler TypeScript disebut sebagai "mode tidak dikompresi". Karena menghindari beberapa langkah build yang lambat, hal ini memfasilitasi siklus edit-kompilasi-menjalankan dengan cepat; juga memfasilitasi proses debug karena kode JavaScript yang dijalankan hampir dapat dibaca seperti sumber TypeScript asli, sehingga menghindari kebutuhan untuk bergantung pada peta sumber.

Pemuatan Blockly dari paket yang diminifikasi disebut sebagai "mode terkompresi". Ini adalah cara terbaik untuk menguji perubahan pada Blockly saat menggunakannya sebagai dependensi paket lain karena menguji (versi yang tidak dipublikasikan dari) paket npm blockly.

N.B.: Ada beberapa tempat di repositori blockly tempat istilah "mode tidak dikompilasi" dan "mode kompilasi" digunakan sebagai sinonim untuk masing-masing "mode tidak terkompresi" dan "mode terkompresi". Penggunaan ini cukup masuk akal pada masa lalu karena Closure Compiler digunakan untuk mengompresi (meminimalkan) kode, tetapi sekarang compiler TypeScript selalu diperlukan, bahkan dalam mode yang tidak dikompresi, sehingga terminologi alternatif ini berpotensi membingungkan dan tidak disarankan.

Mulai Cepat

  • Jika Anda telah membuat perubahan lokal dan ingin memastikan perubahan tersebut tidak merusak build atau pengujian apa pun, jalankan

    npm test

    untuk membangun Blockly dan menjalankan rangkaian pengujiannya.

  • Jika Anda ingin menguji perubahan lokal di browser, jalankan

    npm start

    Fungsi ini mengompilasi Blockly dan membuka browser web yang mengarah ke playground Blockly yang berjalan di Blockly dalam mode tanpa kompresi.

    Setiap file dalam core/, blocks/, dan generators/ yang dimodifikasi akan otomatis dikompilasi ulang; muat ulang tab browser untuk melihat perubahannya.

  • Untuk membuat versi Blockly yang dimodifikasi secara lokal dan mengujinya, dalam mode terkompresi, sebagai dependensi paket npm lain, jalankan

    npm run package

    untuk membuat paket Blockly, lalu

    cd dist && npm link

    untuk memberi tahu npm tempat menemukan file yang dikompilasi, lalu cd ke direktori project Anda sebelum berjalan

    npm link blockly

    agar paket Anda menggunakan versi Blockly yang baru dikompilasi sebagai pengganti paket blockly yang dipublikasikan.

Referensi Skrip Mendetail

Bagian ini mencantumkan scripts prinsip dalam file package.json Blockly dengan penjelasan tentang fungsinya.

Skrip ini menghasilkan file di dua tempat:

  • File dalam subdirektori build/ adalah file perantara yang digunakan untuk pengujian lokal atau diserap oleh bagian pipeline build berikutnya.
  • File dalam subdirektori dist/ membentuk konten paket npm yang dipublikasikan.

Tidak ada direktori yang dilacak di repositori git blockly.

clean

npm run clean membersihkan build sebelumnya dengan menghapus direktori build/ dan dist/. Berguna untuk memperbaiki kegagalan build yang sulit, terutama yang disebabkan oleh penggantian nama file sumber.

messages

npm run messages memperbarui file pesan di msg/json/ dengan setiap perubahan yang telah dilakukan pada msg/messages.js, dan harus dijalankan setelah setiap kali file diubah.

langfiles

npm run langfiles menghasilkan file bahasa terkompilasi di build/msg/ dari file pesan di msg/json.

tsc

npm run tsc menjalankan compiler TypeScript pada konten direktori core/, blocks/, dan generators/, serta menghasilkan file .js individual ke build/src/.

minify

npm run minify menjalankan closure-make-deps dan closure-calculate-chunks untuk menentukan cara membagi file .js yang dikompilasi menjadi beberapa bagian (paket yang diminifikasi), setelah itu, closure-compiler akan dijalankan untuk membuat potongan sebagai berikut:

  • Konten build/src/core/ menjadi dist/blockly_compressed.js.
  • Konten build/src/blocks/ menjadi dist/blocs_compressed.js.
  • Konten build/src/generators/javascript/ (plus build/src/generators/javascript.js) menjadi dist/javascript_compressed.js.
  • Demikian juga untuk dart, lua, php, dan python.

Chuk yang dihasilkan menggunakan wrapper untuk memastikan kompatibilitas dengan Universal Modul Definition sehingga tidak ada pemrosesan tambahan yang diperlukan sebelum disertakan dalam paket.

build

npm run build menjalankan tugas minify dan langfiles. Fungsi ini akan melakukan semua yang diperlukan untuk memuat playground Blockly dalam mode terkompresi atau tidak dikompresi.

package

npm run package menjalankan tugas clean dan build, lalu:

  • Menerapkan wrapper UMD file di build/msg/, yang menempatkan versi yang digabungkan dalam dist/msg/.
  • Menambahkan berbagai file dukungan tambahan ke dist/, dengan wrapper UMD jika berlaku.

publish

npm run publish digunakan oleh tim Blockly untuk memublikasikan paket npm blockly. Solusi ini bergantung pada infrastruktur internal Google sehingga tidak berguna bagi developer eksternal.

lint

npm run lint menjalankan ESLint, yang menjalankan analisis statis kode sumber Blockly untuk menemukan masalah.

test

npm test (atau npm run test) menjalankan tugas package, lalu menjalankan berbagai pengujian otomatis (termasuk menjalankan ESLint). Pengujian ini harus dijalankan dan diteruskan pada setiap kode yang dikirimkan sebagai permintaan pull terhadap repositori blockly.