Komut dosyası oluşturma

Blockly, yüzün üzerinde TypeScript dosyasından oluşur. Bunlar kullanılmadan önce TypeScript derleyicisi tsc tarafından JavaScript'e derlenmelidir. Bu, yerel test için uygun olan eşit sayıda .js dosyası oluşturur ancak bu kadar çok sayıda dosyanın internet üzerinden yüklenmesi son kullanıcılar için yavaş bir deneyimdir. Blockly'nin daha hızlı yüklenmesi için Closure Compiler kullanılır. Bu derleyici, dosyaları sıkıştırıp (küçültüp) toplam boyutu sıkıştırılmamış dosyaların boyutunun yarısından daha az olan yarım düzine dosyada ("paketler" veya "parçalar") birleştirir.

Bu işlem sırasında, tüm tarayıcılarla uyumlu olmayabilecek en yeni ECMAScript özelliklerini kullanan kod, genellikle en yaygın kullanılan tarayıcılarla uyumlu olan ES6'ya dönüştürülür. Bu nedenle, son kullanıcılarınıza yalnızca küçültülmüş kodu sunmanız önemlidir.

google/blockly deposu yalnızca kaynak kodunu içerir. Daha önce derleme ürünlerini de içeriyordu ancak 2019'dan beri küçültülmüş paketler blockly NPM paketi olarak yayınlanıyor ve 2022'den beri de .tgz dosyası olarak her GitHub sürümüne ekleniyor. Bu nedenle, Blockly'nin kendisinde (özellikle core, blocks, generators veya msg dizinlerindeki dosyalarda) değişiklik yapmıyorsanız Blockly'yi derlemenize gerek yoktur.

Blockly'nin derlenmesi, test edilmesi ve yayınlanması süreci, Gulp görevlerini çalıştırmak için npm komut dosyaları kullanılarak otomatikleştirilir. Bu sayfada, temel komut dosyaları ve her birinin işlevi açıklanmaktadır.

Sıkıştırılmış ve Sıkıştırılmamış Mod

Blockly'yi doğrudan TypeScript derleyicisi tarafından oluşturulan ayrı .js dosyalarından yüklemeye "sıkıştırılmamış mod" adı verilir. Bu, çeşitli yavaş derleme adımlarından kaçındığı için hızlı bir düzenleme-derleme-çalıştırma döngüsünü kolaylaştırır. Ayrıca, yürütülen JavaScript kodu neredeyse orijinal TypeScript kaynakları kadar okunabilir olduğundan hata ayıklamayı da kolaylaştırır ve kaynak haritalarına bağımlı olma ihtiyacını ortadan kaldırır.

Blockly'nin küçültülmüş paketlerden yüklenmesine "sıkıştırılmış mod" denir. Bu, Blockly'yi başka bir paketin bağımlılığı olarak kullanırken yapılan değişiklikleri test etmenin en iyi yoludur. Çünkü bu yöntem, blocklynpm paketinin yayınlanmamış bir sürümünü test eder.

N.B.: Blockly deposunda, "uncompiled mode" (derlenmemiş mod) ve "compiled mode" (derlenmiş mod) terimlerinin sırasıyla "uncompressed mode" (sıkıştırılmamış mod) ve "compressed mode" (sıkıştırılmış mod) terimleriyle eş anlamlı olarak kullanıldığı bazı yerler vardır. Geçmişte Closure Compiler, kodu sıkıştırmak (küçültmek) için kullanıldığından bu kullanım mantıklıydı. Ancak artık sıkıştırılmamış modda bile TypeScript derleyicisine her zaman ihtiyaç duyuluyor. Bu nedenle, bu alternatif terminoloji kafa karıştırıcı olabilir ve önerilmez.

Hızlı Başlangıç

  • Yerel değişiklikler yaptıysanız ve bu değişikliklerin derlemeyi veya testleri bozmadığından emin olmak istiyorsanız

    npm test

    Blockly'yi oluşturmak ve test paketini çalıştırmak için.

  • Tarayıcıda yerel değişiklikleri test etmek istiyorsanız

    npm start

    Bu işlem, Blockly'yi derler ve Blockly'yi sıkıştırılmamış modda çalıştıran Blockly Playground'a yönlendiren bir web tarayıcısı açar.

    core/, blocks/ ve generators/ klasörlerindeki değiştirilen tüm dosyalar otomatik olarak yeniden derlenir. Değişiklikleri görmek için tarayıcı sekmesini yeniden yükleyin.

  • Blockly'nin yerel olarak değiştirilmiş sürümünü oluşturmak ve sıkıştırılmış modda başka bir npm paketinin bağımlılığı olarak test etmek için aşağıdaki komutu çalıştırın:

    npm run package

    Blockly paketini oluşturmak için

    cd dist && npm link

    npm'e derlenmiş dosyaları nerede bulacağını söylemek için ve ardından cd komutunu çalıştırmadan önce projenizin dizinine gidin.

    npm link blockly

    Paketinizin, yayınlanan blockly paketi yerine Blockly'nin yeni derlenmiş sürümünü kullanmasını istiyorsanız.

Ayrıntılı Komut Dosyası Referansı

Bu bölümde, Blockly'nin package.json dosyasındaki temel scripts listelenmekte ve bunların ne yaptığı açıklanmaktadır.

Bu komut dosyaları iki yerde dosya oluşturur:

  • build/ alt dizinindeki dosyalar, yerel test için kullanılan veya derleme işlem hattının sonraki bölümleri tarafından alınan ara dosyalardır.
  • dist/ alt dizinindeki dosyalar, yayınlanan npm paketinin içeriğini oluşturur.

İki dizin de blockly git deposunda izlenmiyor.

clean

npm run clean, build/ ve dist/ dizinlerini silerek önceki derlemeleri temizler. Özellikle bir kaynak dosyasının yeniden adlandırılmasından kaynaklanan, anlaşılması zor derleme hatalarını düzeltmek için kullanışlıdır.

messages

npm run messages, msg/json/ içindeki mesaj dosyalarını msg/messages.js'de yapılan değişikliklerle günceller ve bu dosya her değiştirildiğinde çalıştırılmalıdır.

langfiles

npm run langfiles, msg/json içindeki mesaj dosyalarından build/msg/ içinde derlenmiş dil dosyaları oluşturur.

tsc

npm run tsc, core/, blocks/ ve generators/ dizinlerinin içeriklerinde TypeScript derleyicisini çalıştırır ve build/src/ dizinine ayrı .js dosyaları çıkarır.

minify

npm run minify, derlenen .js dosyalarının nasıl parçalara (küçültülmüş paketler) bölüneceğini belirlemek için closure-make-deps ve closure-calculate-chunks işlemlerini çalıştırır. Ardından, parçaları aşağıdaki şekilde oluşturmak için closure-compiler işlemini çalıştırır:

  • build/src/core/ içeriği dist/blockly_compressed.js olur.
  • build/src/blocks/ içeriği dist/blocs_compressed.js olur.
  • build/src/generators/javascript/ (build/src/generators/javascript.js ile birlikte) içeriği dist/javascript_compressed.js olur.
  • Aynı durum dart, lua, php ve python için de geçerlidir.

Oluşturulan parçalar, Universal Module Definition ile uyumluluğu sağlamak için bir sarmalayıcı kullanır. Bu nedenle, pakete dahil edilmeden önce ek bir işleme gerek yoktur.

build

npm run build, minify ve langfiles görevlerini çalıştırır. Bu işlem, Blockly oyun alanını sıkıştırılmış veya sıkıştırılmamış modda yüklemek için gereken her şeyi yapmalıdır.

package

npm run package, clean ve build görevlerini çalıştırır ve ardından:

  • build/msg/ içindeki dosyalara UMD sarmalayıcısı uygular ve sarmalanmış sürümleri dist/msg/ içine yerleştirir.
  • dist/'ya çeşitli ek destek dosyaları ekler. Uygun durumlarda UMD sarmalayıcılar kullanılır.

publish

npm run publish, Blockly ekibi tarafından blockly npm paketini yayınlamak için kullanılır. Google'ın dahili altyapısına bağlı olduğundan harici geliştiriciler için kullanışlı değildir.

lint

npm run lint, sorunları bulmak için Blockly kaynak kodunun statik analizini yaparak ESLint'i çalıştırır.

test

npm test (veya npm run test), package görevini ve ardından çeşitli otomatik testleri (ESLint'i çalıştırma dahil) çalıştırır. Bu test, Blockly deposuna çekme isteği olarak gönderilen tüm kodlarda çalıştırılmalı ve başarılı olmalıdır.