Membuat skrip

Blockly terdiri dari lebih dari seratus file TypeScript. File ini harus dikompilasi oleh compiler TypeScript, tsc, menjadi JavaScript sebelum dapat digunakan. Hal ini akan membuat file .js dalam jumlah yang sama besarnya dan cocok untuk pengujian lokal, tetapi memuat file dalam jumlah besar melalui Internet akan memberikan pengalaman yang lambat bagi pengguna akhir. Agar Blockly dimuat lebih cepat, Closure Compiler digunakan untuk mengompresi (meminimalkan) dan menggabungkannya menjadi setengah lusin file ("bundle" atau "chunk") dengan total ukuran kurang dari setengah ukuran file yang tidak dikompresi.

Dalam prosesnya, kode yang menggunakan fitur ECMAScript terbaru—yang mungkin tidak kompatibel dengan semua browser—ditranspilasi ke ES6, yang umumnya kompatibel dengan sebagian besar browser yang paling banyak digunakan. Oleh karena itu, Anda harus menayangkan hanya kode yang di-minify kepada pengguna akhir.

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

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

Mode Terkompresi dan Tidak Terkompresi

Memuat Blockly langsung dari masing-masing file .js yang dihasilkan oleh kompiler 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 dieksekusi hampir dapat dibaca seperti sumber TypeScript asli, sehingga tidak perlu bergantung pada peta sumber.

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

N.B.: Ada beberapa tempat di repositori blockly yang menggunakan istilah "mode tidak dikompilasi" dan "mode dikompilasi" sebagai sinonim untuk "mode tidak dikompresi" dan "mode dikompresi". Penggunaan ini masuk akal pada masa lalu karena Closure Compiler digunakan untuk mengompresi (meminimalkan) kode, tetapi sekarang kompilator 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 membuat 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 platform uji coba Blockly yang menjalankan Blockly dalam mode tidak terkompresi.

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

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

    npm run package

    untuk membangun paket Blockly, lalu

    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, bukan paket blockly yang dipublikasikan.

Referensi Skrip Mendetail

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

Skrip ini menghasilkan file di dua tempat:

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

Kedua direktori tidak 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 dimodifikasi.

langfiles

npm run langfiles menghasilkan file bahasa yang dikompilasi dalam 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 chunk (paket yang di-minify), lalu menjalankan closure-compiler untuk membuat chunk seperti berikut:

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

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

build

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

package

npm run package menjalankan tugas clean dan build, lalu:

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

lint

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

test

npm test (atau npm run test) menjalankan tugas package, lalu menjalankan berbagai pengujian otomatis (termasuk menjalankan ESLint). Hal ini harus dijalankan—dan lulus—pada kode apa pun yang dikirimkan sebagai permintaan pull terhadap repositori Blockly.