DERLEME dosyaları

Önceki bölümlerde paketler, hedefler ve etiketler ile derleme bağımlılığı grafiği soyut olarak açıklanmıştır. Bu bölümde, paketi tanımlamak için kullanılan somut söz dizimi açıklanmaktadır.

Tanım gereği her paket, kısa bir program olan BUILD dosyası içerir.

BUILD dosyaları, emir kipiyle yazılmış bir dil olan Starlark kullanılarak değerlendirilir.

Bunlar, sıralı bir ifade listesi olarak yorumlanır.

Genel olarak, sıra önemlidir: Örneğin, değişkenler kullanılmadan önce tanımlanmalıdır. Ancak çoğu BUILD dosyası yalnızca derleme kurallarının bildirimlerinden oluşur ve bu ifadelerin göreli sırası önemli değildir. Önemli olan tek şey, paket değerlendirmesi tamamlandığında hangi kuralların hangi değerlerle bildirildiğidir.

cc_library gibi bir derleme kuralı işlevi yürütüldüğünde grafikte yeni bir hedef oluşturulur. Bu hedef daha sonra bir etiket kullanılarak referans verilebilir.

Basit BUILD dosyalarında, kurallar davranış değiştirilmeden serbestçe yeniden sıralanabilir.

Kod ve veri arasında net bir ayrım yapılmasını sağlamak için BUILD dosyaları işlev tanımları, for ifadeleri veya if ifadeleri içeremez (ancak liste kapsamaları ve if ifadelerine izin verilir). İşlevler bunun yerine .bzl dosyalarında bildirilebilir. Ayrıca, *args ve **kwargs bağımsız değişkenlerine BUILD dosyalarında izin verilmez. Bunun yerine, tüm bağımsız değişkenleri açıkça listeleyin.

En önemlisi, Starlark'taki programlar rastgele G/Ç işlemleri gerçekleştiremez. Bu değişmez, BUILD dosyalarının yorumlanmasını hermetik hale getirir. Yani yalnızca bilinen bir giriş kümesine bağlıdır. Bu da derlemelerin yeniden üretilebilir olmasını sağlamak için gereklidir. Daha ayrıntılı bilgi için Hermeticity başlıklı makaleyi inceleyin.

Temel kodun bağımlılıkları her değiştiğinde BUILD dosyalarının güncellenmesi gerektiğinden, bu dosyalar genellikle bir ekipteki birden fazla kişi tarafından yönetilir. BUILD dosya yazarları, her derleme hedefinin rolünü (halka açık kullanım için tasarlanıp tasarlanmadığına bakılmaksızın) ve paketin kendisinin rolünü belgelemek için bolca yorum yapmalıdır.

Uzantı yükleme

Bazel uzantıları, .bzl ile biten dosyalardır. Bir uzantıdan sembol içe aktarmak için load ifadesini kullanın.

load("//foo/bar:file.bzl", "some_library")

Bu kod, foo/bar/file.bzl dosyasını yükler ve ortama some_library sembolünü ekler. Bu işlev, yeni kuralları, işlevleri veya sabitleri (ör. dize ya da liste) yüklemek için kullanılabilir. load çağrısına ek bağımsız değişkenler kullanılarak birden fazla sembol içe aktarılabilir. Bağımsız değişkenler dize değişmezleri (değişken yok) olmalı ve load ifadeleri üst düzeyde görünmelidir. Bu ifadeler işlev gövdesinde olamaz.

load işlevinin ilk bağımsız değişkeni, .bzl dosyasını tanımlayan bir etikettir. Göreceli bir etiketse geçerli bzl dosyasını içeren pakete (dizine değil) göre çözümlenir. load ifadelerindeki göreli etiketler, başında : karakterini kullanmalıdır.

load, diğer adları da destekler. Bu nedenle, içe aktarılan sembollere farklı adlar atayabilirsiniz.

load("//foo/bar:file.bzl", library_alias = "some_library")

Tek bir load ifadesinde birden fazla takma ad tanımlayabilirsiniz. Ayrıca, bağımsız değişken listesi hem takma adları hem de normal sembol adlarını içerebilir. Aşağıdaki örnek tamamen yasaldır (lütfen tırnak işaretlerinin ne zaman kullanılacağını unutmayın).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

.bzl dosyasında, _ ile başlayan semboller dışa aktarılmaz ve başka bir dosyadan yüklenemez.

.bzl dosyasını kimlerin yükleyebileceğini kısıtlamak için yükleme görünürlüğünü kullanabilirsiniz.

Derleme kuralı türleri

Derleme kurallarının çoğu, dil temelinde gruplandırılmış aileler halinde gelir. Örneğin, cc_binary, cc_library ve cc_test sırasıyla C++ ikilileri, kitaplıkları ve testleri için derleme kurallarıdır. Diğer dillerde de aynı adlandırma şeması kullanılır ancak Java için java_* gibi farklı bir önek kullanılır. Bu işlevlerden bazıları Build Encyclopedia'da belgelenmiştir ancak herkes yeni kurallar oluşturabilir.

• *_binary kuralları, belirli bir dilde yürütülebilir programlar oluşturur. Derleme işleminden sonra yürütülebilir dosya, derleme aracının ikili çıkış ağacında kuralın etiketine karşılık gelen adla yer alır. Bu nedenle //my:program, (örneğin) $(BINDIR)/my/program konumunda görünür.

  Bazı dillerde bu kurallar, kurala ait bir data özelliğinde veya bağımlılıklarının geçişli kapanımındaki herhangi bir kuralda belirtilen tüm dosyaları içeren bir runfiles dizini de oluşturur. Bu dosya grubu, üretime dağıtımı kolaylaştırmak için tek bir yerde toplanır.

• *_test kuralları, otomatik test için kullanılan *_binary kuralının uzmanlık alanıdır. Testler, başarı durumunda sıfır döndüren programlardır.

  İkili dosyalar gibi testlerin de runfiles ağaçları vardır ve bu ağaçların altındaki dosyalar, bir testin çalışma zamanında yasal olarak açabileceği tek dosyalardır. Örneğin, bir program cc_test(name='x', data=['//foo:bar']) yürütme sırasında $TEST_SRCDIR/workspace/foo/bar açabilir ve okuyabilir. (Her programlama dilinin $TEST_SRCDIR değerine erişmek için kendi yardımcı işlevi vardır ancak bunların tümü, ortam değişkenini doğrudan kullanmaya eşdeğerdir.) Kurala uyulmaması, testin uzak bir test ana makinesinde yürütülmesi durumunda başarısız olmasına neden olur.

• *_library kuralları, belirtilen programlama dilinde ayrı ayrı derlenmiş modülleri belirtir. Kitaplıklar diğer kitaplıklara, ikili dosyalar ve testler de kitaplıklara bağlı olabilir. Bu durumda, ayrı derleme davranışı beklenir.

Dosya kodlama

BUILD ve .bzl dosyaları UTF-8 olarak kodlanmalıdır. ASCII, UTF-8'in geçerli bir alt kümesidir. Şu anda rastgele bayt dizilerine izin verilmektedir ancak gelecekte bu destek durdurulabilir.