สคริปต์บิลด์ของ Blockly

Blockly ประกอบด้วยไฟล์ TypeScript กว่า 100 ไฟล์ ข้อมูลเหล่านี้ต้องถูกคอมไพล์โดยคอมไพเลอร์ TypeScript tsc ลงใน JavaScript ก่อนจะนำไปใช้ได้ การดำเนินการนี้จะสร้างไฟล์ .js ขึ้นมาเป็นจำนวนมากพอๆ กันซึ่งเหมาะสำหรับการทดสอบภายในเครื่อง แต่การโหลดไฟล์จำนวนมากผ่านทางอินเทอร์เน็ตทำให้ผู้ใช้ปลายทางได้รับประสบการณ์การใช้งานที่เชื่องช้า เพื่อให้ Blockly โหลดได้เร็วขึ้น เราใช้ Closure Compiler ในการบีบอัด (ลดขนาด) และรวมไฟล์เหล่านั้นให้เป็นไฟล์ขนาดครึ่งโหล ("กลุ่ม" หรือ "ส่วนย่อย") ที่มีขนาดรวมน้อยกว่าครึ่งหนึ่งของไฟล์ที่ไม่ได้บีบอัด

ในกระบวนการนี้ โค้ดที่ใช้ฟีเจอร์ ECMAScript ล่าสุด (ซึ่งเป็นฟีเจอร์ที่อาจใช้ไม่ได้กับเบราว์เซอร์ทั้งหมด) จะถูกแปลงเป็น ES6 ซึ่งโดยทั่วไปจะเข้ากันได้กับเบราว์เซอร์ที่ใช้กันอย่างแพร่หลายส่วนใหญ่ ด้วยเหตุนี้ คุณจึงควรแสดงเฉพาะโค้ดที่ลดขนาดให้ผู้ใช้ปลายทาง

ที่เก็บ google/blockly จะมี เฉพาะซอร์สโค้ดเท่านั้น ก่อนหน้านี้ก็มีผลิตภัณฑ์บิลด์ด้วย แต่ตั้งแต่ปี 2019 ได้มีการเผยแพร่แพ็กเกจที่ลดขนาดเป็นแพ็กเกจ blockly NPM และตั้งแต่ปี 2022 ได้แนบไฟล์ .tgz มากับGitHub แต่ละรุ่น คุณจึงไม่ต้องสร้าง Blockly อีกต่อไป เว้นแต่คุณถูกแฮ็กใน Blockly เอง โดยเฉพาะอย่างยิ่งในไฟล์ในไดเรกทอรี core, blocks, generators หรือ msg

ขั้นตอนการสร้าง ทดสอบ และเผยแพร่ Blockly เป็นแบบอัตโนมัติโดยใช้สคริปต์ NPM เพื่อเรียกใช้งาน Gulp หน้านี้จะแสดงสคริปต์หลักการและ หน้าที่ของสคริปต์แต่ละอย่าง

โหมดบีบอัดและไม่บีบอัด

การโหลด Blockly โดยตรงจากไฟล์ .js แต่ละไฟล์ที่สร้างโดยคอมไพเลอร์ TypeScript จะเรียกว่า "โหมดไม่บีบอัด" เนื่องจากหลีกเลี่ยงขั้นตอนการสร้างที่ช้าหลายขั้นตอน จึงสามารถช่วยให้รอบการแก้ไขและการเรียกใช้การคอมไพล์อย่างรวดเร็ว รวมทั้งช่วยให้แก้ไขข้อบกพร่องได้ง่าย เนื่องจากโค้ด JavaScript ที่ดำเนินการนั้นอ่านได้ใกล้เคียงกับแหล่งที่มา TypeScript ดั้งเดิมซึ่งทำให้ไม่ต้องอาศัยการแมปแหล่งที่มา

การโหลดแบบบล็อกจากแพ็กเกจที่ลดขนาดจะเรียกว่า "โหมดบีบอัด" วิธีนี้เป็นวิธีที่ดีที่สุดในการทดสอบการเปลี่ยนแปลงที่ทำกับ Blockly เมื่อใช้เป็นทรัพยากร Dependency ของแพ็กเกจอื่น เนื่องจากจะทดสอบแพ็กเกจ blockly npm (เวอร์ชันที่ไม่ได้เผยแพร่)

N.B.: ที่เก็บข้อมูลแบบบล็อกจะมีบางตำแหน่งที่ใช้คำว่า "โหมดไม่คอมไพล์" และ "โหมดคอมไพล์" เป็นคำพ้องความหมายสำหรับ "โหมดที่ไม่มีการบีบอัด" และ "โหมดบีบอัด" ตามลำดับ ในอดีตการใช้งานแบบนี้เข้าใจดี เนื่องจากมีการใช้ Closure Compiler ในการบีบอัด (ลดขนาด) โค้ด แต่ตอนนี้จำเป็นต้องใช้คอมไพเลอร์ TypeScript เสมอแม้ในโหมดไม่บีบอัด ดังนั้นคำศัพท์ทางเลือกนี้อาจทำให้สับสนและไม่แนะนำให้ใช้

คู่มือเริ่มต้นฉบับย่อ

  • หากคุณทำการเปลี่ยนแปลงในเครื่องและต้องการแน่ใจว่าการเปลี่ยนแปลงเหล่านั้นไม่มีปัญหาที่บิลด์หรือการทดสอบใดๆ ขัดข้อง ให้เรียกใช้

    npm test

    สร้าง Blockly และเรียกใช้ชุดทดสอบ

  • หากคุณต้องการทดสอบการเปลี่ยนแปลงในระบบบนเบราว์เซอร์ ให้เรียกใช้

    npm start

    ซึ่งจะคอมไพล์ Blockly และเปิดเว็บเบราว์เซอร์ที่ชี้ไปที่ Blockly Playground ที่ใช้ Blockly ในโหมดไม่บีบอัด

    ไฟล์ใน core/, blocks/ และ generators/ ที่มีการแก้ไขจะได้รับการคอมไพล์ซ้ำโดยอัตโนมัติ โหลดแท็บเบราว์เซอร์ซ้ำเพื่อดูการเปลี่ยนแปลง

  • หากต้องการสร้าง Blockly ในเวอร์ชันแก้ไขในเครื่องและทดสอบกับ โหมดบีบอัด โดยใช้ทรัพยากร Dependency ของแพ็กเกจ npm อื่น

    npm run package

    เพื่อสร้างแพ็กเกจ Blockly

    cd dist && npm link

    เพื่อบอกให้ npm ว่าจะค้นหาไฟล์ที่คอมไพล์ที่ใด จากนั้น cd ในไดเรกทอรีของโปรเจ็กต์ก่อนที่จะเรียกใช้

    npm link blockly

    เพื่อให้แพ็กเกจของคุณใช้ Blockly เวอร์ชันที่คอมไพล์ใหม่แทนแพ็กเกจ blockly ที่เผยแพร่

การอ้างอิงสคริปต์โดยละเอียด

ส่วนนี้จะแสดงหลักการ scripts ในไฟล์ package.json ของ Blockly พร้อมคำอธิบายเกี่ยวกับการทำงาน

สคริปต์เหล่านี้จะสร้างไฟล์จาก 2 ที่ ดังนี้

  • ไฟล์ในไดเรกทอรีย่อย build/ เป็นไฟล์สื่อกลางที่ใช้สำหรับการทดสอบในเครื่องหรือนำเข้าโดยส่วนถัดไปของไปป์ไลน์บิลด์
  • ไฟล์ในไดเรกทอรีย่อย dist/ เป็นเนื้อหาของแพ็กเกจ npm ที่เผยแพร่

ไม่มีการติดตามไดเรกทอรีใดในที่เก็บ Git แบบบล็อก

clean

npm run clean จะล้างข้อมูลบิลด์ก่อนหน้าโดยการลบไดเรกทอรี build/ และ dist/ มีประโยชน์สำหรับการแก้ไขความล้มเหลวของบิลด์ Arcane โดยเฉพาะไฟล์ที่เกิดจากการเปลี่ยนชื่อไฟล์ต้นฉบับ

messages

npm run messages จะอัปเดตไฟล์ข้อความใน msg/json/ ด้วยการเปลี่ยนแปลงใดก็ตามที่ทำใน msg/messages.js และควรเรียกใช้หลังจากทุกครั้งที่มีการแก้ไขไฟล์

langfiles

npm run langfiles สร้างไฟล์ภาษาที่คอมไพล์ใน build/msg/ จากไฟล์ข้อความใน msg/json

tsc

npm run tsc เรียกใช้คอมไพเลอร์ TypeScript ในเนื้อหาของไดเรกทอรี core/, blocks/ และ generators/ และส่งออกไฟล์ .js แต่ละไฟล์ไปยัง build/src/

minify

npm run minify จะเรียกใช้ closure-make-deps และ closure-calculate-chunks เพื่อกำหนดวิธีแบ่งไฟล์ .js ที่รวบรวมแล้วออกเป็นส่วนๆ (กลุ่มแบบย่อ) หลังจากนั้นจะเรียกใช้ closure-compiler เพื่อสร้างส่วนดังนี้

  • เนื้อหาของ build/src/core/ จะกลายเป็น dist/blockly_compressed.js
  • เนื้อหาของ build/src/blocks/ จะกลายเป็น dist/blocs_compressed.js
  • เนื้อหาของ build/src/generators/javascript/ (บวก build/src/generators/javascript.js) จะกลายเป็น dist/javascript_compressed.js
  • และในทำนองเดียวกันสำหรับ dart, lua, php และ python

ชัคที่สร้างขึ้นจะใช้ Wrapper เพื่อให้แน่ใจว่ามีความเข้ากันได้กับการกำหนดโมดูลสากล เพื่อให้ไม่จำเป็นต้องมีการประมวลผลเพิ่มเติมก่อนที่จะรวมมาในแพ็กเกจ

build

npm run build จะเรียกใช้งาน minify และ langfiles การดำเนินการนี้จะทำทุกอย่างที่จำเป็นในการโหลด Playground ของ Blockly ในโหมดบีบอัดหรือไม่บีบอัดอย่างใดอย่างหนึ่ง

package

npm run package จะเรียกใช้ clean และ build แล้วทำดังนี้

  • ใช้ Wrapper UMD ในไฟล์ใน build/msg/ โดยวางเวอร์ชันที่รวมไว้ใน dist/msg/
  • เพิ่มไฟล์สนับสนุนอื่นๆ ไปยัง dist/ พร้อม UMD Wrapper หากเกี่ยวข้อง

publish

ทีม Blockly ใช้ npm run publish เพื่อเผยแพร่แพ็กเกจ blockly npm ขึ้นอยู่กับโครงสร้างพื้นฐานภายใน Google จึงไม่เป็นประโยชน์ สำหรับนักพัฒนาภายนอก

lint

npm run lint เรียกใช้ ESLint ซึ่งทำการวิเคราะห์แบบคงที่ของซอร์สโค้ด Blockly เพื่อค้นหาปัญหา

test

npm test (หรือ npm run test) เรียกใช้งาน package แล้วทำการทดสอบอัตโนมัติหลายรายการ (รวมถึง ESLint) การดำเนินการนี้ควรเรียกใช้และส่งผ่านโค้ดที่ส่งเป็นพุลคำขอสำหรับที่เก็บแบบบล็อก