Kod Deposu Kuralları

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

Harici depo, 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. Bunlar, üçüncü taraf kitaplıklara (Maven paketlenmiş kitaplıkları gibi) bağımlı olmak için kullanılabilir ancak Bazel'in çalıştığı ana makineye özel BUILD dosyaları oluşturmak için de kullanılabilir.

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 depo kuralı, yerel depo kuralı gibi kullanılabilir. Zorunlu bir name özelliğine sahiptir ve derleme dosyalarında bulunan her hedefe @<name>//package:target olarak atıfta bulunulabilir. Burada <name>, name özelliğinin değeridir.

Kural, açıkça derlediğinizde veya derlemenin bağımlılığı olduğunda yüklenir. Bu durumda, Bazel implementation işlevini yürütür. Bu işlev, deposu, içeriğini ve BUILD dosyalarını nasıl oluşturacağınızı açıklar.

Özellikler

Özellik, attrs kural bağımsız değişkenine sözlük olarak iletilen kural bağımsız değişkenleridir. Özellikler ve türleri, bir depo kuralı tanımladığınızda 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> öğesini kullanın:

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

Tüm repository_rule'ların, örtülü olarak tanımlanmış özellikleri vardır (tıpkı derleme kuralları gibi). İki örtülü özellik, name (tıpkı derleme kurallarında olduğu gibi) ve repo_mapping şeklindedir. Bir kod deposu kuralının adına repository_ctx.name ile erişilebilir. repo_mapping, yerel depo kuralları local_repository ve new_local_repository ile aynı anlama gelir.

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

Uygulama işlevi

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

İşlevin tam olarak bir giriş parametresi (repository_ctx) vardır. İşlev, kuralın belirtilen parametrelere göre tekrarlanabilir olduğunu belirtmek için None veya bu kural için bir dizi parametre içeren ve kuralı, aynı depoyu oluşturan tekrarlanabilir bir kurala dönüştürecek bir dikte döndürür. Örneğin, bir git deposunu izleyen bir kural söz konusu olduğunda, bu, başlangıçta belirtilen kayan bir dal yerine belirli bir kaydetme tanımlayıcısı döndürme anlamına gelir.

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?

Bir deposunun uygulama işlevi, Bazel'in söz konusu depodan bir hedefe ihtiyacı olduğunda (ör. başka bir depodaki başka bir hedef ona bağlı olduğunda veya komut satırında söz konusu depodan 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ın yeniden getirilmesi gerekmez. 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 durumlardan biri değiştiğinde yeniden getirilir:

• WORKSPACE dosyasındaki depo bildirimine iletilen parametreler.
• Deponun uygulanmasını içeren Starlark kodu.
• repository_rule öğesinin environ özelliğiyle belirtilen herhangi bir ortam değişkeninin değeri. Bu ortam değişkenlerinin değerleri, --action_env işaretiyle komut satırına sabitlenebilir (ancak bu işaret, derlemenin her işlemini geçersiz kılar).
• read(), execute() ve etiket tarafından atıfta bulunulan repository_ctx benzer yöntemleri (örneğin, //mypkg:label.txt ancak mypkg/label.txt hariç)
• 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 adresinde --configure parametresi iletildiğinde yeniden getirilir (özellik ayarlanmadan bırakılırsa bu komut yeniden getirmeyi sağlamaz).

• 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. Bunun nedeni, bu depoların ağla iletişim kurduğu veya başka bir şekilde pahalı olduğu varsaymasıdır.

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şlatmalardan kaçınmak (ağ erişiminin tekrarlanması gerekebileceği için pahalıdır) ve 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 yolun çözümlenmesinin yine de yeniden başlatmaya neden olabileceğini unutmayın.

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, kaynak getiren bir depo, üçüncü taraf deposunun belirli bir dalını takip edebilir ve bu dalda yeni taahhütler kullanılabilir. Bu durumda, bazel sync kodunu çağırarak bazel'den tüm harici depoları koşulsuz olarak yeniden getirmesini isteyebilirsiniz.

Ayrıca, bazı kurallar yerel makineyi denetler ve yerel makine yükseltilmişse güncelliğini yitirebilir. 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 olarak yapılandırılmış araç zinciri: Yerel C++ derleyicisi, ortam ve C++ derleyicinin 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 ü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.