Tập lệnh bản dựng

Blockly bao gồm hơn 100 tệp TypeScript. Các tệp này phải được trình biên dịch TypeScript (tsc) biên dịch thành JavaScript thì mới có thể sử dụng. Điều này tạo ra một số lượng tệp .js tương đương, phù hợp để kiểm thử cục bộ, nhưng việc tải một số lượng lớn tệp như vậy qua Internet sẽ mang lại trải nghiệm chậm chạp cho người dùng cuối. Để Blockly tải nhanh hơn, Trình biên dịch Closure được dùng để nén (giảm thiểu) và kết hợp các tệp này thành khoảng 6 tệp ("gói" hoặc "đoạn") với tổng kích thước nhỏ hơn một nửa so với các tệp chưa nén.

Trong quá trình này, mã sử dụng các tính năng mới nhất của ECMAScript (những tính năng có thể không tương thích với tất cả các trình duyệt) sẽ được chuyển đổi xuống ES6, thường tương thích với hầu hết các trình duyệt được sử dụng rộng rãi. Do đó, bạn chỉ nên phân phát mã đã rút gọn cho người dùng cuối.

Kho lưu trữ google/blockly chỉ chứa mã nguồn. Trước đây, thư mục này cũng chứa các sản phẩm bản dựng, nhưng kể từ năm 2019, các gói được rút gọn đã được xuất bản dưới dạng gói blockly NPM và kể từ năm 2022 cũng được đính kèm dưới dạng tệp .tgz vào mỗi bản phát hành trên GitHub, vì vậy, bạn không cần phải tạo Blockly trừ phi bạn đang hack trên chính Blockly – cụ thể là trên các tệp trong thư mục core, blocks, generators hoặc msg.

Quá trình tạo, kiểm thử và xuất bản Blockly được tự động hoá bằng cách sử dụng các tập lệnh npm để chạy các tác vụ Gulp. Trang này ghi lại các tập lệnh chính và chức năng của từng tập lệnh.

Chế độ nén và không nén

Việc tải Blockly trực tiếp từ các tệp .js riêng lẻ do trình biên dịch TypeScript tạo ra được gọi là "chế độ chưa nén". Vì tránh được một số bước dựng chậm, nên việc này giúp chu trình chỉnh sửa-biên dịch-chạy diễn ra nhanh chóng; việc này cũng giúp gỡ lỗi vì mã JavaScript đang được thực thi gần như dễ đọc như các nguồn TypeScript ban đầu, loại bỏ nhu cầu phụ thuộc vào sourcemap.

Việc tải Blockly từ các gói được rút gọn được gọi là "chế độ nén". Đây là cách tốt nhất để kiểm thử các thay đổi đối với Blockly khi sử dụng Blockly làm phần phụ thuộc của một gói khác, vì cách này sẽ kiểm thử (một phiên bản chưa phát hành của) gói blocklynpm.

N.B.: Có một số nơi trong kho lưu trữ blockly sử dụng các thuật ngữ "chế độ chưa biên dịch" và "chế độ đã biên dịch" làm từ đồng nghĩa với "chế độ chưa nén" và "chế độ nén" tương ứng. Cách sử dụng này từng có ý nghĩa trong quá khứ vì Trình biên dịch Closure được dùng để nén (giảm thiểu) mã, nhưng giờ đây, trình biên dịch TypeScript luôn cần thiết, ngay cả ở chế độ không nén. Vì vậy, thuật ngữ thay thế này có thể gây nhầm lẫn và không nên dùng.

Bắt đầu nhanh

  • Nếu bạn đã thực hiện các thay đổi cục bộ và muốn đảm bảo rằng những thay đổi đó không làm hỏng bản dựng hoặc bất kỳ kiểm thử nào, hãy chạy

    npm test

    để tạo Blockly và chạy bộ kiểm thử của nó.

  • Nếu bạn muốn kiểm thử các thay đổi cục bộ trong trình duyệt, hãy chạy

    npm start

    Thao tác này sẽ biên dịch Blockly và mở một trình duyệt web trỏ đến sân chơi Blockly đang chạy Blockly ở chế độ chưa nén.

    Mọi tệp trong core/, blocks/ và generators/ đã được sửa đổi đều tự động được biên dịch lại; hãy tải lại thẻ trình duyệt để xem các thay đổi.

  • Để tạo phiên bản Blockly đã sửa đổi cục bộ và kiểm thử phiên bản đó ở chế độ nén, dưới dạng một phần phụ thuộc của một gói npm khác, hãy chạy

    npm run package

    để tạo gói Blockly, sau đó

    cd dist && npm link

    để cho npm biết nơi tìm các tệp đã biên dịch, sau đó cd vào thư mục của dự án trước khi chạy

    npm link blockly

    để gói của bạn sử dụng phiên bản mới biên dịch của Blockly thay cho gói blockly đã xuất bản.

Tài liệu tham khảo chi tiết về tập lệnh

Phần này liệt kê nguyên tắc scripts trong tệp package.json của Blockly kèm theo nội dung giải thích về chức năng của các nguyên tắc đó.

Các tập lệnh này tạo tệp ở hai vị trí:

  • Các tệp trong thư mục con build/ là các tệp trung gian được dùng để kiểm thử cục bộ hoặc được các phần sau của quy trình tạo bản dựng tiếp nhận.
  • Các tệp trong thư mục con dist/ tạo thành nội dung của gói npm đã xuất bản.

Không có thư mục nào được theo dõi trong kho lưu trữ git của blockly.

clean

npm run clean dọn dẹp mọi bản dựng trước đó bằng cách xoá các thư mục build/ và dist/. Hữu ích khi khắc phục các lỗi bản dựng khó hiểu, đặc biệt là những lỗi do đổi tên tệp nguồn.

messages

npm run messages cập nhật các tệp thông báo trong msg/json/ bằng mọi thay đổi đã được thực hiện đối với msg/messages.js và phải chạy sau mỗi lần tệp đó được sửa đổi.

langfiles

npm run langfiles tạo các tệp ngôn ngữ đã biên dịch trong build/msg/ từ các tệp thông báo trong msg/json.

tsc

npm run tsc chạy trình biên dịch TypeScript trên nội dung của các thư mục core/, blocks/ và generators/, đồng thời xuất các tệp .js riêng lẻ sang build/src/.

minify

npm run minify chạy closure-make-deps và closure-calculate-chunks để xác định cách chia các tệp .js đã biên dịch thành các đoạn (gói được rút gọn), sau đó chạy closure-compiler để tạo các đoạn như sau:

  • Nội dung của build/src/core/ sẽ trở thành dist/blockly_compressed.js.
  • Nội dung của build/src/blocks/ sẽ trở thành dist/blocs_compressed.js.
  • Nội dung của build/src/generators/javascript/ (cộng với build/src/generators/javascript.js) sẽ trở thành dist/javascript_compressed.js.
  • Tương tự đối với dart, lua, php và python.

Các chuk được tạo sử dụng một trình bao bọc để đảm bảo khả năng tương thích với Định nghĩa mô-đun chung, do đó, không cần xử lý thêm trước khi chúng được đưa vào gói.

build

npm run build chạy các tác vụ minify và langfiles. Thao tác này sẽ thực hiện mọi việc cần thiết để tải sân chơi Blockly ở chế độ nén hoặc không nén.

package

npm run package chạy các tác vụ clean và build, sau đó:

  • Áp dụng trình bao bọc UMD cho các tệp trong build/msg/, đặt các phiên bản được bao bọc trong dist/msg/.
  • Thêm nhiều tệp hỗ trợ bổ sung vào dist/, có trình bao bọc UMD (nếu có).

publish

npm run publish được nhóm Blockly dùng để xuất bản gói blockly npm. Vì phụ thuộc vào cơ sở hạ tầng nội bộ của Google nên tính năng này không hữu ích cho các nhà phát triển bên ngoài.

lint

npm run lint chạy ESLint, thực hiện phân tích tĩnh mã nguồn Blockly để tìm ra các vấn đề.

test

npm test (hoặc npm run test) chạy tác vụ package, sau đó chạy nhiều kiểm thử tự động (bao gồm cả việc chạy ESLint). Thao tác này phải được chạy (và vượt qua) trên mọi mã được gửi dưới dạng yêu cầu kéo đối với kho lưu trữ Blockly.