Baklavalar

Sorun bildir Kaynağı göster Gece · 7,4 , 7.3 · 7,2 · 7,1 · 7,0 · 6,5

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

Genellikle bir işlem, geçişli bağımlılıklardan toplanan değerleri içeren büyük bir komut satırı gerektirir. Örneğin, bir bağlayıcı komut satırı, bağlanan tüm kitaplıkların ihtiyaç duyduğu her nesne dosyasını listeleyebilir. En iyi uygulama, bu tür geçişli verilerin birden fazla hedef tarafından paylaşılabilmesi için depset'larda depolanmasıdır. Ancak, kural yazarının bir işlem komut satırı oluşturmak için bu ayrıntılı bölümleri dize listelerine dönüştürmesi gerektiyse bu, bellek paylaşımı optimizasyonunu geçersiz kılar.

Bu nedenle, işlem oluşturma işlevleri dizelere ek olarak Args nesneleri de kabul eder. Her Args nesnesi, verileri değiştirmek için isteğe bağlı dönüşümler içeren dize ve depset dizilişi temsil eder. Args nesneleri, komut satırının hesaplanması gerektiğinde yürütme aşamasına kadar kapsadıkları depset'leri işlemez. Böylece, pahalı kopyalama işlemleri analiz aşaması tamamlanana kadar ertelenir. Daha fazla bilgi için Performansı Optimize Etme sayfasına bakabilirsiniz.

Args, ctx.actions.args() çağrısı yapılarak oluşturulur. Bunlar, ctx.actions.run() veya ctx.actions.run_shell() için arguments parametresi olarak iletilebilir. Bir Args nesnesinin her mutasyonu, nihai komut satırına değer 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 aşağıdaki gibi 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 çözümlenen bir dize gösterimine dönüştürülür. Mümkünse dize temsilinde, deposunun kanon adı yerine deposunun görünen adı kullanılır. Bu da bu temsili BUILD dosyalarında kullanıma uygun hale getirir. Temsil biçiminin tam olarak ne olacağı garanti edilmez. Bununla birlikte, //foo:bar, @repo//foo:bar ve @@canonical_name~//foo:bar.bzl tipik örneklerdir.
  • Diğer tüm türler, belirtilmemiş bir yöntemle dizelere dönüştürülür. Bu nedenle, add() öğesine dize veya File türü olmayan değerleri iletmekten kaçınmanız gerekir. Bunları add_all() veya add_joined()’e iletirseniz bir map_each işlevi sağlamanız gerekir.

Dize biçimlendirmesi (add*() yöntemlerinin format, format_each ve format_joined parametreleri) kullanılırken biçim şablonu, dizelerde % değiştirme ile aynı şekilde yorumlanır. Tek fark, şablonun tam olarak bir tane değiştirme yer tutucusu içermesi ve %s olması gerekir. Değişmez yüzde değerleri, %% olarak kod dışına alınabilir. Biçimlendirme, değer yukarıda belirtildiği gibi bir dizeye dönüştürüldükten sonra uygulanır.

add*() yöntemlerinin her birinin, ekstra konum parametresini (bağımsız değişken adı) kabul eden alternatif bir biçimi vardır. bağımsız değişkenlerin önüne eklenecek bir dize. add_all ve add_joined için sıra boş olursa fazladan dize eklenmez. Örneğin, aynı kullanım, belirli bir dizinin val1..val3 içerip içermediğine veya boş olup olmadığına bağlı olarak komut satırına --foo val1 val2 val3 --bar veya yalnızca --bar ekleyebilir.

Komut satırının boyutu, sistem tarafından izin verilen maksimum boyuttan daha uzun olabilir. Bu durumda bağımsız değişkenler parametre dosyalarına aktarılabilir. use_param_file() ve set_param_file_format() başlıklı makaleleri 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
Aşağıdaki 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 required
İki konumsal parametre iletilirse bu, arg adı olarak yorumlanır. Arg adı, herhangi bir işlem yapılmadan değerden önce eklenir. Yalnızca bir konum parametresi iletilirse value olarak yorumlanır (aşağıya bakın).
value varsayılan değer unbound
Eklenecek nesne. Bu değer, yukarıda belirtilen standart dönüşüm kullanılarak bir dizeye dönüştürülür. Bu işlev için map_each parametresi olmadığından, value bir dize veya File olmalıdır. File adlı liste, unsur, depset veya dizinin bu yöntem yerine add_all() veya add_joined() hizmetine iletilmesi gerekir.
format dize veya None; varsayılan değer None
value değerinin dize haline getirilmiş 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 çok bağımsız değişken ekler. Öğeler yürütme aşamasında geç işlenir.

İşlemenin çoğu, aşağıdaki adımlara göre eklenecek bağımsız değişkenler listesi üzerinde gerçekleşir:

  1. Her dizin File öğesi, söz konusu dizinde yinelenen şekilde bulunan tüm File öğeleri ile değiştirilir.
  2. map_each sağlanırsa her öğeye uygulanır ve elde edilen dize 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, standart dönüşümün her öğeye uygulanmasının sonucudur.
  3. Listede bulunan her bağımsız değişken (varsa) format_each ile biçimlendirilir.
  4. uniquify Doğru değerine ayarlanırsa yinelenen bağımsız değişkenler kaldırılır. İlk kullanım kalır.
  5. Bir before_each dizesi sağlanırsa listedeki mevcut her bağımsız değişkenin önüne yeni bir bağımsız değişken olarak eklenir. Bu, bu noktaya kadar eklenecek bağımsız değişken sayısını etkili bir şekilde ikiye katlar.
  6. Listenin boş olması ve omit_if_empty değerinin doğru (varsayılan) olması dışında, bağımsız değişken adı ve terminate_with (varsa) sırasıyla ilk ve son bağımsız değişkenler 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 required
İki konumsal parametre iletilirse bu, arg adı olarak yorumlanır. Arg adı, herhangi bir işlem yapılmadan ayrı bir bağımsız değişken olarak values öğesinin önüne eklenir. omit_if_empty doğruysa (varsayılan) ve başka öğe eklenmezse (values boşsa veya tüm öğeleri filtrelenirse olduğu gibi) bu bağımsız değişken 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
Öğelerinin ekleneceği liste, tuple veya depset.
map_each callable; veya None; varsayılan değer None
Her bir öğeyi sıfır veya daha fazla dizeye dönüştüren ve eklemeden önce daha ayrıntılı şekilde işlenebilecek bir işlev. 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ı DirectoryExpander. İkinci bağımsız değişken yalnızca sağlanan işlev kullanıcı tanımlıysa (yerleşik değil) ve birden fazla parametre bildirirse iletilir.

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

  • Her öğenin tek bir dizeye dönüştüğü yaygın durumda işlev bu dizeyi döndürmelidir.
  • Öğenin tamamen filtrelenmesi gerekiyorsa 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 1 veya 0 uzunluğunda bir liste döndürmekle aynı etkiye sahiptir. Ancak, gerekmediği durumlarda liste oluşturmaktan kaçınmak daha verimli ve okunaklı bir yöntemdir.

Normalde, expand_directories=True ayarlandığında dizin olan öğeler otomatik olarak içeriklerini içerecek şekilde genişletilir. Ancak bu işlem, diğer değerlerin içinde bulunan dizinleri genişletmez. Örneğin, öğeler alan olarak dizin içeren yapılar olduğunda. Bu durumda, belirli bir dizindeki dosyaları manuel olarak almak için DirectoryExpander bağımsız değişkeni uygulanabilir.

Analiz aşamasındaki büyük veri yapılarının yürütme aşamasında istenmeden tutulmasını önlemek için map_each işlevi üst düzey bir def ifadesiyle tanımlanmalıdır; varsayılan olarak iç içe yerleştirilmiş bir işlev kapatma olamaz.

Uyarı: map_each çağrısı sırasında yürütülen print() ifadeleri, görünür herhangi bir çıktı oluşturmaz.

format_each dize; veya None; varsayılan olarak None
İsteğe bağlı bir biçim dizesi kalıbı. map_each işlevi tarafından döndürülen her dizeye uygulanır. Biçim dizesinde tam olarak bir tane "%s" yer tutucu olmalıdır.
before_each dize; veya None; varsayılan değer None
values kaynağından türetilen her bağımsız değişken eklenmeden önce eklenecek isteğe bağlı bir bağımsız değişken.
omit_if_empty varsayılan değer True
True (doğru) değerine ayarlanırsa values işlevinden türetilen eklenebilecek bağımsız değişken yoksa sonraki tüm işlemler atlanır ve komut satırında değişiklik olmaz. Yanlış değerine ayarlanırsa bağımsız değişken adı ve sağlandığı takdirde terminate_with, başka bağımsız değişken olup olmadığına bakılmaksızın yine eklenir.
uniquify varsayılan değer False
Doğru değerine ayarlanırsa values öğesinden türetilen yinelenen bağımsız değişkenler atlanır. Her bağımsız değişkenin yalnızca ilk geçtiği yer kalır. Etiketler halihazırda yinelenen öğeleri atladığı için bu özellik genellikle gerekli değildir ancak map_each, birden fazla öğe için aynı dizeyi yayınlarsa bu özellik yararlı olabilir.
expand_directories varsayılan değer True
Değer true ise values içindeki tüm dizinler düz bir dosya listesine genişletilir. Bu, map_each uygulanmadan önce gerçekleşir.
terminate_with dize; 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 eklenmezse (values boşsa veya tüm öğeleri filtrelenirse olduğu gibi) bu bağımsız değişken eklenmez.
allow_closure varsayılan değer False
True (doğru) ise map_each gibi işlev parametrelerinde kapanışların kullanılmasına izin verir. Genellikle bu gerekli değildir ve analiz aşamasındaki büyük veri yapılarını yürütme aşamasında tutma riskini alı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 fazla değeri birbirine bağlayarak 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 öğesinden türetilen bağımsız değişkenler listesi, join_with.join(...) gibi tek bir bağımsız değişkende birleştirilir ve ardından belirtilen format_joined dize şablonu kullanılarak biçimlendirilir. Öğeler tek bir bağımsız değişkende birleştirildiğinde genellikle kullanışlı olmadıkları için add_all() parametresinden farklı olarak before_each veya terminate_with parametresi yoktur.

Filtrelemeden sonra bağımsız değişkene katılacak dize yoksa ve omit_if_empty doğru (varsayılan) ise 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 required
İki konumsal parametre iletilirse bu, arg adı olarak yorumlanır. Bağımsız değişken adı, herhangi bir işlenmeden values öncesine eklenir. omit_if_empty doğru (varsayılan) ise ve birleştirilecek values alanından türetilmiş herhangi bir dize yoksa bu bağımsız değişken, values boşsa veya tüm öğeleri filtrelenirse 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, tuple veya depset.
join_with zorunlu
string.join() ile aynı şekilde, map_each ve format_each uygulanarak elde edilen dizeleri birleştirmek için kullanılan bir ayırıcı dize.
map_each callable; veya None; varsayılan değer None
add_all ile aynıdır.
format_each dize veya None; varsayılan değer None
add_all ile aynıdır.
format_joined dize; veya None; varsayılan değer None
Birleştirilen dizeye uygulanan isteğe bağlı bir biçim dizesi kalıbı. Biçim dizesinde tam olarak bir tane "%s" yer tutucu olmalıdır.
omit_if_empty varsayılan değer True
Doğru değerine ayarlanırsa (values boş olduğu veya tüm öğeleri filtrelendiği için) birleştirilecek dize yoksa diğer tüm işlemler atlanır ve komut satırında değişiklik olmaz. Yanlış değeri döndürülürse 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 dizelerin mantıksal birleştirmesi).
uniquify varsayılan değer False
add_all ile aynıdır.
expand_directories varsayılan değer True
add_all ile aynıdır.
allow_closure 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 required
Şu değerlerden biri olmalıdır:
  • "multiline": Her öğe (bağımsız değişken adı veya değer), param dosyasına tam olarak yazılır ve arkasından yeni bir satır karakteri eklenir.
  • "shell" (kabuk): "çoklu" ile aynıdır, ancak öğeler kabuk tırnak içine alınmıştır
  • "flag_per_line": "multiline" ile aynıdır, ancak (1) param dosyasına sadece işaretler ("--" ile başlar) yazılır ve (2) flag'lerin değerleri (varsa) aynı satıra bir '=" ile yazılır. ayırıcı olarak sunar. Bu, Abseil flags kitaplığı tarafından beklenen biçimdir.

Çağırılmazsa biçim 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, param dosyası işaretçisiyle değiştirerek bir params dosyasına aktarır. args parametreniz sistemdeki komut uzunluğu sınırları için çok büyük olabileceğinde kullanın.

Bazel, verimlilik için yürütme sırasında parametre dosyasını çıkış ağacına yazmayı tercih edebilir. İşlemlerde hata ayıklama yapıyorsanız ve parametre dosyasını incelemek istiyorsanız derlemenize --materialize_param_files parametresini iletin.

Parametreler

Parametre Açıklama
param_file_arg zorunlu
Tek bir "%s" içeren biçim dizesi. args bir params dosyasına dökülürse params dosyasının yoluyla biçimlendirilmiş bu dizeden oluşan bir bağımsız değişkenle değiştirilir.

Örneğin, bağımsız değişkenler "params.txt" adlı bir parametre dosyasına dökülürse "--file=%s" belirtildiğinde işlem komut satırında "--file=params.txt" yer alır.

use_always varsayılan değer False
Parametrelerin her zaman bir parametreler dosyasına aktarılıp aktarılmayacağını belirtir. Yanlış ise bazel, sisteminize ve arg uzunluğuna göre bağımsız değişkenlerin dökülmesi gerekip gerekmediğine karar verir.