Kod Deposu Kuralları

Sorun bildiropen_in_new Kaynağı gösteropen_in_new

Bu sayfada, kod deposu kurallarının nasıl oluşturulacağı anlatılmakta ve daha ayrıntılı bilgi için örnekler sunulmaktadır.

Harici depo, yalnızca WORKSPACE dosyasında kullanılabilen ve Bazel'ın yükleme aşamasında hermetik olmayan işlemi etkinleştiren bir kuraldır. Her harici depo kuralı, kendine ait BUILD dosyaları ve yapılarıyla kendi çalışma alanını oluşturur. Bunlar, üçüncü taraf kitaplıklara (ör. Maven paketlenmiş kitaplıklar) bağlı kalmakla birlikte, Bazel'in çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilir.

Kod deposu kuralı oluşturma

Bir .bzl dosyasında yeni bir depo kuralı oluşturmak ve bu kuralı genel değişkende depolamak için repository_rule işlevini kullanın.

Özel depo kuralları, yerel depo kuralları gibi kullanılabilir. Zorunlu bir name özelliği vardır ve derleme dosyalarında bulunan her hedef @<name>//package:target olarak verilebilir. Burada <name>, name özelliğinin değeridir.

Kural, siz açık bir şekilde derlediğinizde veya derlemenin bir bağımlılığıysa yüklenir. Bu durumda Bazel, implementation işlevini yürütür. Bu işlevde deponun, içeriğinin ve BUILD dosyalarının nasıl oluşturulacağı açıklanmaktadır.

Özellikler

Özellik, attrs kuralı bağımsız değişkenine dikte olarak iletilen kural bağımsız değişkenleridir. Özellikler ve türleri, bir depo kuralı tanımladığınızda listelenir. url ve sha256 özelliklerinin dize olarak tanımlandığı bir örnek:

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={
        "url": attr.string(mandatory=True)
        "sha256": attr.string(mandatory=True)
    }
)

Uygulama işlevindeki bir özelliğe erişmek için repository_ctx.attr.<attribute_name> öğesini kullanın:

def _impl(repository_ctx):
    url = repository_ctx.attr.url
    checksum = repository_ctx.attr.sha256

Tüm repository_rule'ler, dolaylı olarak tanımlanmış özelliklere sahiptir (derleme kurallarında olduğu gibi). İki örtülü özellik name (derleme kurallarında olduğu gibi) ve repo_mapping'dir. Bir depo kuralının adına repository_ctx.name ile erişilebilir. repo_mapping öğesinin anlamı, yerel depo kuralları local_repository ve new_local_repository ile aynıdır.

Bir özellik adı _ ile başlıyorsa gizlidir ve kullanıcılar bu özelliği ayarlayamaz.

Uygulama işlevi

Her kod deposu kuralı için bir implementation işlevi gerekir. Kuralın gerçek mantığını içerir ve kesinlikle Yükleme Aşamasında yürütülür.

İşlev tam olarak bir giriş parametresine (repository_ctx) sahiptir. İşlev, belirtilen parametrelere göre kuralın yeniden oluşturulabilir olduğunu belirtmek için None veya söz konusu kural için, aynı depoyu oluşturan tekrarlanabilir bir kurala dönüştürecek parametre grubunu içeren bir dikt değerini döndürür. Örneğin, bir git deposunu izleyen bir kural için başlangıçta belirtilen kayan dal yerine belirli bir kaydetme tanımlayıcısı döndürmeniz gerekir.

Giriş parametresi repository_ctx, özellik değerlerine ve hermetik olmayan işlevlere (ikili program bulma, ikili program yürütme, depoda dosya oluşturma veya internetten dosya indirme) erişmek için kullanılabilir. Daha fazla içerik için kitaplığa bakın. Örnek:

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

Uygulama işlevi ne zaman yürütülür?

Bir deponun uygulama işlevi, Bazel bu depodan bir hedefe ihtiyaç duyduğunda yürütülür. Örneğin, başka bir hedef (başka bir depoda) bu hedefe bağımlı olduğunda veya komut satırında bu hedeften bahsedildiğinde yürütülür. Daha sonra uygulama işlevinin dosya sisteminde depoyu oluşturması beklenir. Buna depoyu "getirme" denir.

Normal hedeflerin aksine, deponun farklı olmasına neden olacak bir değişiklik olduğunda depolar yeniden getirilmez. Bunun nedeni, Bazel'ın değişiklikleri algılayamadığı veya her derlemede çok fazla ek yüke (ör. ağdan getirilen öğeler) yol açabilmesidir. Bu nedenle, depolar yalnızca aşağıdakilerden biri değişirse yeniden getirilir:

• WORKSPACE dosyasındaki depo bildirimine iletilen parametreler.
• Deponun uygulanmasını içeren Starlark kodu.
• repository_ctx ürününün getenv() yöntemine iletilen veya repository_rule özelliğinin environ özelliğiyle bildirilen herhangi bir ortam değişkeninin değeri. Bu ortam değişkenlerinin değerleri, --repo_env işaretiyle komut satırına sabit bir şekilde bağlanabilir.
• Etiketin başvuruda bulunduğu read(), execute() ve benzer repository_ctx yöntemlerine iletilen herhangi bir dosyanın içeriği (örneğin, mypkg/label.txt değil //mypkg:label.txt)
• bazel sync yürütüldüğünde.

Depoların ne zaman yeniden getirileceğini kontrol eden iki repository_rule parametresi vardır:

• configure işareti ayarlanırsa yalnızca bazel sync tarihinde kod deposuna --configure parametresi kendisine aktarıldığında yeniden getirilir (özellik ayarlanmazsa bu komut yeniden getirme işlemine neden olmaz)

• local işareti ayarlanırsa yukarıdaki durumlara ek olarak, değişikliklerin, depo ya da kod deposunun beyanında bir değişikliğe yol açıp açmamalarından bağımsız olarak, yukarıdaki durumlara ek olarak, Bazel sunucusu yeniden başlatıldığında veya deponun bildirilmesini etkileyen herhangi bir dosya (ör. WORKSPACE dosyası veya yüklendiği bir dosya) değiştiğinde de depo yeniden getirilir.

  Bu durumlarda yerel olmayan depolar yeniden getirilmez. Bunun nedeni, bu kod depolarının ağ ile iletişim kurduğunun veya başka bir şekilde pahalı olduğu varsayılmasıdır.

Uygulama işlevini yeniden başlatma

Uygulama işlevi, istediği bir bağımlılık eksikse depo getirilirken yeniden başlatılabilir. Bu durumda, uygulama işlevinin yürütülmesi durdurulur, eksik bağımlılık çözümlenir ve işlev, bağımlılık çözüldükten sonra yeniden yürütülür. Gereksiz yeniden başlatmalardan (ağ erişiminin tekrarlanması gerekebileceği için pahalıdır) önlemek için tüm etiket bağımsız değişkenlerinin mevcut bir dosyaya çözümlenebilmesi koşuluyla etiket bağımsız değişkenleri önceden getirilir. Yalnızca işlevin yürütülmesi sırasında oluşturulan bir dizeden veya etiketten bir yolun çözümlenmesinin yeniden başlatmaya neden olabileceğini unutmayın.

Harici depoları yeniden getirmeyi zorunlu kılma

Bazen harici bir depo, tanımında veya bağımlılıklarında herhangi bir değişiklik olmadan güncelliğini yitirebilir. Örneğin, depo getirme kaynakları, üçüncü taraf deponun belirli bir dalını izleyebilir ve bu dalda yeni kayıtlar kullanılabilir. Bu durumda, bazel sync çağrısı yaparak Bazel'dan tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı kurallar yerel makineyi denetler ve yerel makine yükseltilirse güncelliğini yitirebilir. Burada Bazel'dan yalnızca repository_rule tanımının configure özelliğinin ayarlandığı harici kod depolarını yeniden getirmesini isteyebilirsiniz. bazel sync --configure kullanın.

Örnekler

• C++ otomatik yapılandırılmış araç zinciri: Yerel C++ derleyicisi, ortam ve C++ derleyicisinin desteklediği işaretleri arayarak Bazel için C++ yapılandırma dosyalarını otomatik olarak oluşturmak üzere bir depo kuralı kullanır.

• Go depoları, Go kurallarını kullanmak için gereken bağımlılıkların listesini tanımlamak için birkaç repository_rule kullanır.

• rules_jvm_external, varsayılan olarak geçişli bağımlılık ağacındaki her Maven yapısı için derleme hedefleri oluşturan, @maven adında harici bir depo oluşturur.