Skrip Build Blockly

Perhatian: Kecuali jika Anda mengubah kode sumber Blockly secara langsung, Anda mungkin tidak perlu mem-build Blockly untuk menjalankan skrip apa pun yang didokumentasikan di bawah ini. Sebagai gantinya, ikuti petunjuk di bagian "Dapatkan Kode" di halaman Mulai untuk menginstal paket blockly NPM atau download file .tgz yang dilampirkan ke rilis terbaru di GitHub.

Blockly terdiri dari lebih dari seratus file TypeScript. File ini harus dikompilasi oleh compiler TypeScript, tsc, menjadi JavaScript sebelum dapat digunakan. Hal ini akan menghasilkan file .js dalam jumlah yang sama besar yang cocok untuk pengujian lokal, tetapi memuat file dalam jumlah besar melalui Internet akan memberikan pengalaman yang lambat bagi pengguna akhir. Agar pemuatan Blockly lebih cepat, Closure Compiler digunakan untuk mengompresi (meminifikasi) dan menggabungkannya menjadi setengah lusin file ("paket" atau "potongan") 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 ditranspil ke ES6, yang umumnya kompatibel dengan sebagian besar browser yang paling banyak digunakan. Oleh karena itu, Anda harus hanya menayangkan kode yang diminifikasi kepada pengguna akhir.

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

Proses mem-build, menguji, dan memublikasikan Blockly diotomatiskan menggunakan skrip npm untuk menjalankan tugas Gulp. Halaman ini mendokumentasikan skrip prinsip dan fungsi setiap skrip.

Mode Dikompresi dan Tidak Dikompresi

Memuat 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-jalankan yang cepat; hal ini juga memfasilitasi proses debug karena kode JavaScript yang dijalankan hampir semudah dibaca seperti sumber TypeScript asli, sehingga tidak perlu bergantung pada sourcemap.

Memuat 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) paket npm blockly.

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

Mulai Cepat

Perhatian: Kecuali jika Anda mengubah kode sumber Blockly secara langsung, Anda mungkin tidak perlu mem-build Blockly untuk menjalankan skrip apa pun yang didokumentasikan di bawah ini. Sebagai gantinya, ikuti petunjuk di bagian "Dapatkan Kode" di halaman Mulai untuk menginstal paket NPM blockly atau mendownload file .tgz yang dilampirkan ke rilis terbaru di GitHub.

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

  npm test
  

  untuk mem-build Blockly dan menjalankan rangkaian pengujiannya.

• Jika Anda ingin menguji perubahan lokal di browser, jalankan

  npm start
  

  Tindakan ini akan mengompilasi Blockly dan membuka browser web yang mengarah ke Blockly playground yang menjalankan Blockly dalam mode tidak dikompresi.

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

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

  npm run package
  

  untuk membangun paket Blockly,

  cd dist && npm link
  

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

  npm link blockly
  

  agar paket Anda menggunakan Blockly versi yang baru dikompilasi sebagai ganti 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 selanjutnya dari pipeline build.
• 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 tidak jelas, terutama yang disebabkan oleh penggantian nama file sumber.

messages

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

langfiles

npm run langfiles menghasilkan file bahasa yang dikompilasi 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 setiap file .js 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), lalu menjalankan closure-compiler untuk membuat bagian tersebut 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 Definisi Modul Universal sehingga tidak diperlukan pemrosesan tambahan sebelum disertakan dalam paket.

build

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

package

npm run package menjalankan tugas clean dan build, lalu:

• Menerapkan wrapper UMD file di build/msg/, menempatkan versi yang digabungkan di 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. Metrik ini bergantung pada infrastruktur internal Google sehingga tidak berguna bagi developer eksternal.

lint

npm run lint menjalankan ESLint, yang melakukan 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). Ini harus dijalankan—dan diteruskan—pada kode apa pun yang dikirimkan sebagai permintaan pull terhadap repositori blockly.