Baklavalar

Sorun bildir Kaynağı görüntüle Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Komut satırının bir kısmını veya tamamını oluşturmak için gereken verileri belleği verimli bir şekilde kapsayan bir nesne.

Bir işlemin, geçişli bağımlılıklardan toplanan değerleri içeren büyük bir komut satırı gerektirdiği durumlar sıkça görülür. Örneğin, bir bağlayıcı komut satırı, bağlanmakta olan tüm kitaplıkların ihtiyaç duyduğu her nesne dosyasını listeleyebilir. Bu tür geçişli verilerin birden fazla hedef tarafından paylaşılabilmesi için depset'lerde depolanması en iyi uygulamadır. Ancak kuralı yazan kişi, bir işlem komut satırı oluşturmak için bu bağımlılık kümelerini dize listelerine dönüştürmek zorunda kalırsa bu bellek paylaşımı optimizasyonu bozulur.

Bu nedenle, işlem oluşturma işlevleri dizelerin yanı sıra Args nesnelerini de kabul eder. Her Args nesnesi, dizelerin ve bağımlılık kümelerinin birleştirilmesini temsil eder. Verileri işlemek için isteğe bağlı dönüşümler kullanılabilir. Args nesneleri, komut satırını hesaplama zamanı geldiğinde yürütme aşamasına kadar kapsadıkları bağımlılık kümelerini işlemez. Bu sayede, analiz aşaması tamamlanana kadar maliyetli kopyalama işlemleri ertelenir. Daha fazla bilgi için Performansı Optimize Etme sayfasına bakın.

Args, ctx.actions.args() aranarak oluşturulur. Bunlar, ctx.actions.run() veya ctx.actions.run_shell() işlevinin arguments parametresi olarak iletilebilir. Args nesnesinin her mutasyonu, değerleri nihai komut satırına ekler.

map_each özelliği, öğelerin dizelere nasıl dönüştürüleceğini özelleştirmenize olanak tanır. map_each işlevi sağlamazsanız standart dönüşüm şu şekilde olur:

  • Zaten dize olan değerler olduğu gibi bırakılır.
  • File nesneleri, File.path değerlerine dönüştürülür.
  • Label nesneleri, ana depo bağlamında çözümlendiğinde aynı nesneye geri dönen bir dize gösterimine dönüştürülür. Mümkünse dize gösterimi, deponun kanonik adı yerine deponun görünen adını kullanır. Bu da gösterimi BUILD dosyalarında kullanıma uygun hale getirir. Temsilin tam şekli garanti edilmese de tipik örnekler //foo:bar, @repo//foo:bar ve @@canonical_name+//foo:bar.bzl'dir.
  • Diğer tüm türler belirtilmemiş şekilde dizelere dönüştürülür. Bu nedenle, add() işlevine dize veya File türünde olmayan değerler iletmekten kaçınmalısınız. Bu değerleri add_all() veya add_joined() işlevine iletirseniz map_each işlevini sağlamanız gerekir.

Dize biçimlendirmesi (format, format_each ve format_joined parametreleri add*() yöntemleri) kullanılırken biçim şablonu, dizelerde % yerine koyma işlemiyle aynı şekilde yorumlanır. Ancak şablonun tam olarak bir yerine koyma yer tutucusu olması ve bu yer tutucunun %s olması gerekir. Değişmez yüzdeler %% olarak çıkış yapılabilir. Biçimlendirme, değer yukarıdaki gibi bir dizeye dönüştürüldükten sonra uygulanır.

add*() yöntemlerinin her birinin, diğer bağımsız değişkenlerden önce eklenecek bir "arg name" dizesi olan ek bir konumsal parametreyi kabul eden alternatif bir biçimi vardır. add_all ve add_joined için dizi boş çıkarsa ek dize eklenmez. Örneğin, aynı kullanım, verilen dizinin val1..val3 içerip içermemesine veya boş olmasına bağlı olarak komut satırına --foo val1 val2 val3 --bar ya da yalnızca --bar ekleyebilir.

Komut satırının boyutu, sistemin izin verdiği maksimum boyuttan daha uzun olabilirse bağımsız değişkenler parametre dosyalarına taşabilir. use_param_file() ve set_param_file_format() hükümlerini inceleyin.

Örnek: Şu komut satırını oluşturmak istediğimizi varsayalım:

--foo foo1.txt foo2.txt ... fooN.txt --bar bar1.txt,bar2.txt,...,barM.txt --baz
Şu Args nesnesini kullanabiliriz:
# foo_deps and bar_deps are depsets containing
# File objects for the foo and bar .txt files.
args = ctx.actions.args()
args.add_all("--foo", foo_deps)
args.add_joined("--bar", bar_deps, join_with=",")
args.add("--baz")
ctx.actions.run(
  ...
  arguments = [args],
  ...
)

Üyeler

add

Args Args.add(arg_name_or_value, value=unbound, *, format=None)

Bu komut satırına bir bağımsız değişken ekler.

Parametreler

Parametre Açıklama
arg_name_or_value zorunlu
İki konumsal parametre iletilirse bu, argüman adı olarak yorumlanır. Arg adı, değerden önce herhangi bir işlem yapılmadan eklenir. Yalnızca bir konumsal parametre iletilirse bu parametre value olarak yorumlanır (aşağıya bakın).
value Varsayılan değer unbound
'dir. Eklenecek nesne. Yukarıda bahsedilen standart dönüştürme kullanılarak dizeye dönüştürülür. Bu işlev için map_each parametresi olmadığından value, dize veya File olmalıdır. Bu yöntem yerine add_all() veya add_joined() öğesine liste, demet, depset veya dizin File iletilmelidir.
format dize veya None; varsayılan değer None
value öğesinin dizeleştirilmiş sürümüne uygulanacak bir biçim dizesi kalıbı.

add_all

Args Args.add_all(arg_name_or_values, values=unbound, *, map_each=None, format_each=None, before_each=None, omit_if_empty=True, uniquify=False, expand_directories=True, terminate_with=None, allow_closure=False)

Bu komut satırına birden fazla bağımsız değişken ekler. Öğeler, yürütme aşamasında geç işlenir.

İşlemin çoğu, aşağıdaki adımlarda belirtildiği gibi eklenecek bir bağımsız değişkenler listesi üzerinde gerçekleşir:

  1. Her dizin File öğesi, o dizinde yinelemeli olarak bulunan tüm File'lerle değiştirilir.
  2. map_each verilirse her öğeye uygulanır ve ortaya çıkan dizeler listeleri, ilk bağımsız değişken listesini oluşturmak için birleştirilir. Aksi takdirde, ilk bağımsız değişken listesi her öğeye standart dönüştürme uygulanarak elde edilen sonuçtur.
  3. Listede varsa her bağımsız değişken format_each ile biçimlendirilir.
  4. uniquify doğruysa yinelenen bağımsız değişkenler kaldırılır. İlk oluşum kalır.
  5. Bir before_each dizesi verilirse listedeki her mevcut bağımsız değişkenden önce yeni bir bağımsız değişken olarak eklenir. Bu, bu noktaya kadar eklenecek bağımsız değişkenlerin sayısını ikiye katlar.
  6. Liste boş olmadığı ve omit_if_empty doğru (varsayılan) olduğu durumlar hariç olmak üzere, arg adı ve terminate_with, verilmişse sırasıyla ilk ve son bağımsız değişken olarak eklenir.
Boş dizelerin, tüm bu işleme adımlarına tabi olan geçerli bağımsız değişkenler olduğunu unutmayın.

Parametreler

Parametre Açıklama
arg_name_or_values zorunlu
İki konumsal parametre iletilirse bu, argüman adı olarak yorumlanır. Arg adı, values işaretinden önce ayrı bir bağımsız değişken olarak herhangi bir işlem yapılmadan eklenir. omit_if_empty doğruysa (varsayılan) ve başka öğe eklenmemişse (values boşsa veya tüm öğeleri filtrelenmişse olduğu gibi) bu argüman adı eklenmez. Yalnızca bir konumsal parametre iletilirse bu parametre values olarak yorumlanır (aşağıya bakın).
values sequence veya depset; varsayılan değer unbound
Öğeleri eklenecek liste, demet veya depset.
map_each callable; veya None; varsayılan değer None
Her öğeyi sıfır veya daha fazla dizeye dönüştüren bir işlevdir. Bu dizeler, eklenmeden önce daha fazla işlenebilir. Bu parametre sağlanmazsa standart dönüşüm kullanılır.

İşleve bir veya iki konum bağımsız değişkeni iletilir: dönüştürülecek öğe ve ardından isteğe bağlı bir DirectoryExpander. İkinci bağımsız değişken yalnızca sağlanan işlev kullanıcı tanımlıysa (yerleşik değilse) ve birden fazla parametre bildiriyorsa iletilir.

Döndürülen değerin türü, öğe için kaç bağımsız değişken oluşturulacağına bağlıdır:

  • Her öğenin tek bir dizeye dönüştüğü genel durumda, işlev bu dizeyi döndürmelidir.
  • Öğe tamamen filtrelenecekse işlev None değerini döndürmelidir.
  • Öğe birden fazla dizeye dönüşürse işlev bu dizelerin listesini döndürür.
Tek bir dize veya None döndürmek, sırasıyla uzunluğu 1 veya 0 olan bir liste döndürmekle aynı etkiye sahiptir. Ancak, gerekli olmayan yerlerde liste oluşturmaktan kaçınmak daha verimli ve okunabilir bir yöntemdir.

Normalde, expand_directories=True ayarlandığında dizin olan öğeler içeriklerine göre otomatik olarak genişletilir. Ancak bu, diğer değerlerin içinde bulunan dizinleri genişletmez. Örneğin, öğeler alan olarak dizinlere sahip yapılar olduğunda bu durum geçerlidir. Bu durumda, belirli bir dizinin dosyalarını manuel olarak almak için DirectoryExpander bağımsız değişkeni uygulanabilir.

Büyük analiz aşaması veri yapılarının yürütme aşamasında istenmeden saklanmasını önlemek için map_each işlevi üst düzey bir def ifadesiyle bildirilmelidir. Bu işlev, varsayılan olarak iç içe yerleştirilmiş bir işlev kapatması olmayabilir.

Uyarı: print() ifadeleri, map_each çağrısı sırasında yürütüldüğünde görünür bir çıkış üretmez.

format_each dize veya None; varsayılan değer None
map_each işlevi tarafından döndürülen her dizeye uygulanan isteğe bağlı bir biçim dizesi kalıbı. Biçim dizesinde tam olarak bir "%s" yer tutucusu olmalıdır.
before_each string; veya None; varsayılan değer None
values'den türetilen her bağımsız değişkenden önce eklenecek isteğe bağlı bir bağımsız değişken.
omit_if_empty bool; varsayılan değer True
Doğruysa, values öğesinden türetilen ve eklenecek bağımsız değişken yoksa tüm sonraki işlemler bastırılır ve komut satırı değişmez. Yanlışsa diğer bağımsız değişkenler olup olmadığına bakılmaksızın bağımsız değişken adı ve terminate_with (varsa) eklenmeye devam eder.
uniquify bool; varsayılan değer False
Doğruysa values öğesinden türetilen yinelenen bağımsız değişkenler atlanır. Yalnızca her bağımsız değişkenin ilk oluşumu kalır. Bu özellik, genellikle depsets zaten yinelenenleri atladığı için gerekli değildir ancak map_each birden fazla öğe için aynı dizeyi yayınlıyorsa yararlı olabilir.
expand_directories bool; varsayılan değer True
True ise values içindeki tüm dizinler düz bir dosya listesi olarak genişletilir. Bu işlem, map_each uygulanmadan önce gerçekleşir.
terminate_with string; veya None; varsayılan değer None
Diğer tüm bağımsız değişkenlerden sonra eklenecek isteğe bağlı bir bağımsız değişken. omit_if_empty doğruysa (varsayılan) ve başka öğe eklenmemişse (values boşsa veya tüm öğeleri filtrelenmişse olduğu gibi) bu bağımsız değişken eklenmez.
allow_closure bool; varsayılan değer False
Doğruysa map_each gibi işlev parametrelerinde kapanımların kullanılmasına izin verir. Bu genellikle gerekli değildir ve büyük analiz aşaması veri yapılarının yürütme aşamasında tutulması riskini taşır.

add_joined

Args Args.add_joined(arg_name_or_values, values=unbound, *, join_with, map_each=None, format_each=None, format_joined=None, omit_if_empty=True, uniquify=False, expand_directories=True, allow_closure=False)

Bir ayırıcı kullanarak birden çok değeri birleştirerek bu komut satırına bir bağımsız değişken ekler. Öğeler, yürütme aşamasında geç işlenir.

İşleme add_all() işlevine benzer ancak values işlevinden türetilen bağımsız değişkenler listesi, join_with.join(...) işleviyle birleştirilmiş gibi tek bir bağımsız değişkende birleştirilir ve ardından verilen format_joined dize şablonu kullanılarak biçimlendirilir. add_all()'dan farklı olarak, öğeler tek bir bağımsız değişkende birleştirildiğinde genellikle yararlı olmadıkları için before_each veya terminate_with parametresi yoktur.

Filtrelemeden sonra bir bağımsız değişkene birleştirilecek dize yoksa ve omit_if_empty doğruysa (varsayılan) herhangi bir işlem yapılmaz. Aksi takdirde, birleştirilecek dize yoksa ancak omit_if_empty yanlışsa birleştirilen dize boş bir dize olur.

Parametreler

Parametre Açıklama
arg_name_or_values zorunlu
İki konumsal parametre iletilirse bu, argüman adı olarak yorumlanır. Arg adı, herhangi bir işlem yapılmadan values öğesinden önce eklenir. omit_if_empty doğruysa (varsayılan) ve birleştirilecek values'den türetilmiş dize yoksa (values boşsa veya tüm öğeleri filtrelenmişse bu durum oluşabilir) bu argüman eklenmez. Yalnızca bir konumsal parametre iletilirse bu parametre values olarak yorumlanır (aşağıya bakın).
values sequence veya depset; varsayılan değer unbound
Öğeleri birleştirilecek liste, demet veya depset.
join_with string; gerekli
map_each ve format_each uygulanarak elde edilen dizeleri string.join() ile aynı şekilde birleştirmek için kullanılan bir ayırıcı dize.
map_each callable; veya None; varsayılan değer None
'dir. add_all ile aynıdır.
format_each string; veya None; varsayılan değer None
add_all ile aynıdır.
format_joined dize veya None; varsayılan değer None
Birleştirilmiş dizeye uygulanan isteğe bağlı biçim dizesi kalıbı. Biçim dizesinde tam olarak bir "%s" yer tutucusu olmalıdır.
omit_if_empty bool; varsayılan değer True
Doğruysa birleştirilecek dize yoksa (values boş olduğu veya tüm öğeleri filtrelendiği için) tüm sonraki işlemler bastırılır ve komut satırı değişmez. Yanlışsa birleştirilecek dize olmasa bile iki bağımsız değişken eklenir: bağımsız değişken adı ve ardından boş bir dize (sıfır dizenin mantıksal birleşimi).
uniquify bool; varsayılan değer False
add_all ile aynıdır.
expand_directories bool; varsayılan değer True
add_all ile aynıdır.
allow_closure bool; varsayılan değer False
add_all ile aynıdır.

set_param_file_format

Args Args.set_param_file_format(format)

Kullanılıyorsa param dosyasının biçimini ayarlar

Parametreler

Parametre Açıklama
format string; required
Must be one of:
  • "multiline": Her öğe (bağımsız değişken adı veya değeri), parametre dosyasına aynen yazılır ve ardından yeni satır karakteri eklenir.
  • "shell": "multiline" ile aynıdır ancak öğeler kabuk tırnaklıdır.
  • "flag_per_line": "multiline" ile aynıdır ancak (1) yalnızca parametre dosyasına yazılan işaretler ("--" ile başlayanlar) ve (2) varsa işaretlerin değerleri "=" ayırıcıyla aynı satıra yazılır. Bu, Abseil flags kitaplığının beklediği biçimdir.

Biçim, çağrılmadığı takdirde varsayılan olarak "shell" olur.

use_param_file

Args Args.use_param_file(param_file_arg, *, use_always=False)

Bağımsız değişkenleri bir params dosyasına aktarır ve bunları params dosyasına yönelik bir işaretçiyle değiştirir. Bağımsız değişkenleriniz sistemin komut uzunluğu sınırları için çok büyük olduğunda kullanılır.

Bazel, verimlilik için yürütme sırasında parametreler dosyasını çıkış ağacına yazmayı atlamayı seçebilir. İşlemlerde hata ayıklıyorsanız ve param dosyasını incelemek istiyorsanız derlemenize --materialize_param_files iletin.

Parametreler

Parametre Açıklama
param_file_arg string; required
Tek bir "%s" içeren bir biçim dizesi. Bağımsız değişkenler bir params dosyasına taşarsa bu dizeyle biçimlendirilmiş ve params dosyasının yolunu içeren bir bağımsız değişkenle değiştirilirler.

Örneğin, args bir "params.txt" parametre dosyasına taşırılıyorsa "--file=%s" belirtildiğinde işlem komut satırı "--file=params.txt" içerir.

use_always bool; varsayılan değer False
Bağımsız değişkenlerin her zaman bir parametre dosyasına aktarılıp aktarılmayacağı. Yanlışsa Bazel, sisteminize ve argüman uzunluğuna göre argümanların taşırılması gerekip gerekmediğine karar verir.