Kod Deposu Kuralları

Sorun bildirme Kaynağı görüntüleme Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bu sayfada, depo kurallarının nasıl oluşturulacağı ele alınmakta ve daha fazla bilgi için örnekler verilmektedir.

Harici depolama alanı, yalnızca WORKSPACE dosyasında kullanılabilen ve Bazel'in yükleme aşamasında hermetik olmayan işlemi etkinleştiren bir kuraldır. Her harici depolama alanı kuralı, kendi BUILD dosyaları ve yapılarıyla kendi çalışma alanını oluşturur. Üçüncü taraflara bağımlı olmak için kitaplıklarını (Maven paketlenmiş kitaplıkları gibi) yanı sıra BUILD dosyası oluşturmayı da sağlar. ana makineye özgü olduğunu unutmayın.

Depo kuralı oluşturma

Yeni bir depolama alanı kuralı oluşturmak ve bunu bir genel değişkende depolamak için .bzl dosyasında repository_rule işlevini kullanın.

Özel depolama alanı kuralları, yerel depolama alanı kuralları gibi kullanılabilir. Google zorunlu bir name özelliğine ve derleme dosyalarında bulunan her hedefe sahiptir @<name>//package:target olarak ifade edilebilir. Burada <name>, name özelliği için de kullanılmaktadır.

Kural, açıkça derlediğinizde yüklenir. seçeceğim. Bu durumda, Bazel implementation işlevini yürütür. Bu işlev, deposunun, içeriğinin ve BUILD dosyalarının nasıl oluşturulacağını açıklar.

Özellikler

Özellik, attrs kural bağımsız değişkenine sözlük olarak iletilen kural bağımsız değişkenleridir. Bir depo kuralı tanımladığınızda, tanımlanan özellikler ve türleri listelenir. url ve sha256 özelliklerini dize olarak tanımlayan ö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>:

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

Tüm repository_rule'lar, örtülü olarak tanımlanmış özelliklere sahiptir (tıpkı kuralları) belirlemeye olanak tanır. İki gizli özellik name (derleme kurallarında olduğu gibi) ve repo_mapping'dır. Bir depo kuralının adına şu kişiler kullanılarak erişilebilir: repository_ctx.name repo_mapping kelimesinin anlamı yerel depo kuralları local_repository ve new_local_repository.

Özellik adı _ ile başlıyorsa özeldir ve kullanıcılar bunu ayarlayamaz.

Uygulama işlevi

Her depo kuralı için implementation işlevi gerekir. Belge, yükleme Aşamasında tam olarak yürütülür.

İşlev, repository_ctx adlı tam bir giriş parametresine sahiptir. İşlev, belirtilen parametreler göz önüne alındığında kuralın yeniden üretilebilir olduğunu belirtmek için None değerini veya söz konusu kural için bir dizi parametre içeren ve bu kuralı aynı deposu oluşturan yeniden üretilebilir bir kurala dönüştüren bir sözlük döndürür. Örneğin, Örneğin, Git deposunu izleyen bir kural için ilk başta bu değerde olan kayan bir dal yerine belirli bir taahhüt tanımlayıcısı belirtiliyor.

repository_ctx giriş parametresi, özellik değerlerine ve hermetik olmayan işlevlere (ikili dosya bulma, ikili dosya yürütme, depolama alanında dosya oluşturma veya İnternet'ten dosya indirme) erişmek için kullanılabilir. Daha fazla bağlam bilgisi 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?

Deponun uygulama işlevi, Bazel için bir başka bir hedef her zaman başka bir hedef olduğunda veya komut satırında belirtip belirtmediğine bağlıdır. İlgili içeriği oluşturmak için kullanılan uygulama işlevinin dosyada depoyu oluşturması beklenir. bahsedeceğim. Buna "getirme" adı verilir seçeceğim.

Normal hedeflerin aksine depolar, kod deposunun farklı olmasına yol açacak birtakım değişiklikler yapmaktır. Bunun nedeni, Bazel'in değişiklikleri algılayamadığı veya her derlemede çok fazla ek yüke neden olduğu şeyler (ör. ağdan getirilen öğeler) olmasıdır. Bu nedenle, depolar yalnızca aşağıdaki şeyler değişir:

  • WORKSPACE dosyası yükleyin.
  • Deponun uygulanmasını içeren Starlark kodu.
  • environ ile belirtilen tüm ortam değişkenlerinin değeri repository_rule özelliğinin değeri. Bu ortam değişkenlerinin değerleri, komutta kablolara bağlı olabilir. , --action_env (ancak bu işaret, derlemenin her işlemini geçersiz kılar).
  • read(), execute() ve benzeri öğelere iletilen dosyaların içeriği bir etiketle başvuruda bulunulan repository_ctx yöntemleri (örneğin, //mypkg:label.txt ancak mypkg/label.txt değil)
  • 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 depo yalnızca bazel sync parametresi kendisine iletildiğinde --configure üzerinde yeniden getirilir (özelliğin değeri kaldırılırsa bu komut yeniden getirme işlemine neden olmaz)
  • local işareti ayarlanmışsa, yukarıdaki durumlara ek olarak Bazel sunucusu yeniden başlatıldığında veya deponun tanımını etkileyen herhangi bir dosya (ör. WORKSPACE dosyası veya yüklediği bir dosya) değiştiğinde de depo yeniden getirilir. Bu değişiklikler, deponun tanımında veya kodunda bir değişikliğe neden olup olmadığına bakılmaksızın yapılır.

    Yerel olmayan depolar bu durumlarda yeniden getirilmez. Çünkü bu depoların ağ ile iletişim kurduğu veya başka bir Pahalı.

Uygulama işlevini yeniden başlatma

İstediği bir bağımlılık eksikse, uygulama işlevi bir depo getirilirken yeniden başlatılabilir. Bu durumda, uygulama işlevinin yürütmesi durdurulur, eksik bağımlılık çözülür ve bağımlılık çözüldükten sonra işlev yeniden yürütülür. Gereksiz yeniden başlatmaları (ağ erişiminin tekrarlanması gerekebileceğinden pahalı olan) önlemek için, tüm etiket bağımsız değişkenlerinin mevcut bir dosyaya çözülmesi koşuluyla etiket bağımsız değişkenleri önceden getirilir. Sorun çözüldüğünde, yalnızca yürütme sırasında oluşturulan bir dizeden veya etiketten alınan yol işlevin yeniden başlatılması yeniden başlatmaya neden olabilir.

Harici depoların yeniden getirilmesini zorlama

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 depodan gelen kaynaklar bir üçüncü taraf deposunun belirli bir dalını takip edebilir ve yeni üzerinden erişilebilir. Bu durumda, bazel sync çağrısını yaparak bazel'den tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı kurallar yerel makineyi denetler ve yerel makine yeni sürüme geçirildiyse güncel değildir. Burada bazel'den yalnızca repository_rule tanımının configure özelliğinin ayarlandığı harici depoları yeniden getirmesini isteyebilirsiniz. bazel sync --configure değerini kullanın.

Örnekler

  • C++ otomatik yapılandırılmış araç seti: Yerel C++ derleyiciyi, ortamı ve C++ derleyicinin desteklediği işaretçileri 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 üzere çeşitli repository_rule öğelerini kullanır.

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