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

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

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

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

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

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

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

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

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

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

หากคุณทำการเปลี่ยนแปลงในเครื่องและต้องการดูว่าการเปลี่ยนแปลงดังกล่าวไม่ได้ทำให้บิลด์หรือการทดสอบใช้งานไม่ได้ ให้เรียกใช้
```
npm test
```
เพื่อสร้าง Blockly และเรียกใช้ชุดทดสอบ
ถ้าต้องการทดสอบการเปลี่ยนแปลงในเครื่องในเบราว์เซอร์ ให้เรียกใช้
```
npm start
```
ซึ่งจะคอมไพล์ Blockly และเปิดเว็บเบราว์เซอร์ที่ชี้ไปที่ Blockly IDE ที่รัน 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/ มีประโยชน์สำหรับการแก้ไขข้อผิดพลาดในการบิลด์ที่เข้าใจยาก โดยเฉพาะข้อผิดพลาดที่เกิดจากการเปลี่ยนชื่อไฟล์ต้นฉบับ

`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 ที่คอมไพล์แล้วออกเป็นกลุ่ม (กลุ่มที่ผ่านการมินify) จากนั้นจะเรียกใช้ 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 เพื่อให้แน่ใจว่าจะเข้ากันได้กับUniversal การกําหนดโมดูลเพื่อไม่ให้มีการประมวลผลเพิ่มเติม ก่อนที่จะรวมอยู่ในแพ็กเกจ

`build`

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

`package`

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

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

`publish`

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

`lint`

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

`test`

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